Proofpoint Essentials Rest API Guide

Introduction

The Proofpoint Essentials API is a REST API based around resource-focused, noun URLs, with HTTP verbs being used to operate on these resources. This page aims to outline at a high level the intent of the API, while the API Specification page will detail the endpoints and data schemas.

Resources

This section details the REST resources exposed by the API.

Organization

In this context ‘Organization’ can refer to entities of any type (OEM Partner, Strategic Partner, Channel Partner and Organization). An Organization is core resource which owns various sub-resources such as Domains and Users. When referring to an Organization in an API request, we do so using the primary domain. For example to read data for the Organization "My Company" the following URL would be used.

https://us1.proofpointessentials.com/api/v1/orgs/mycompany.com

There are a few points to note when examining the URL structure:

  1. https is used to provide security of the request (including auth headers), and response.
  2. the domain name in this case is us1.proofpointessentials.com, this will depend on where the Organization being queried resides. The endpoint for a domain can be queried using the "endpoints" URL.
  3. api/v1 specifies the version of API that is to be used. This will dictate which endpoints are valid, as well as the request and response schemas.
  4. orgs is the resource name.
  5. mycompany.com is the primary domain for this Organization, and is used as the identifier in the request URL.

Domain

An Organization may have a number of domains associated with it. In the example above My Company may also be associated with mycompany.ca, mycompany.co.uk etc. A GET to an Organization will return all of the domains associated with it, but if actions are required on a single domain it can be addressed as follows:

https://us1.proofpointessentials.com/api/v1/orgs/mycompany.com/domains/mycompany.ca

This will simply return data for the .ca domain. Domains may also be created (POST), updated (PUT) and removed (DELETE) using this form of URL.

Users

As with Domains, Users are resources owned by a single Organization, so all requests to individual users are addressed via the Organization, and identified using the primary email address of the User.

https://us1.proofpointessentials.com/api/v1/orgs/mycompany.com/users/bob@mycompany.com

This will simply return data for the Bob user. Users may also be created (POST), updated (PUT) and removed (DELETE) using this form of URL.

Endpoint

An Organization may exist on any Proofpoint Essentials instance (in some cases more than one). To find out which endpoint to use for a particular Organization the following URL may be used against any instance. All further requests should be directed at the correct instance.

https://us1.proofpointessentials.com/api/v1/endpoints/mycompany.com

The response will show a list of usable endpoints:

{
  "endpoints": [
    "https://us1.proofpointessentials.com",
    "https://eu1.proofpointessentials.com"
  ]
}

Features

An Organization has a number of available features (such as URL Defense, Encryption etc) which will depend on which licensing package is currently configured. These features can be read via a GET request, and updated via a PUT request.

Feature Beginner Business Advanced Professional
attachment_defense Yes Yes Yes
disclaimers Yes Yes Yes Yes
dlp Yes Yes Yes
email_archive Yes
email_encryption Yes Yes
instant_replay Yes Yes Yes
outbound_relaying Yes Yes Yes Yes
smtp_discovery Yes Yes Yes Yes
social_media_account_protection Yes Yes
url_defense Yes Yes Yes

Package

As mentioned previously each Organization is defined by its Package. The package may be updated via the API (it can be read by reading the orgs resource).

Licensing

The licensing endpoint allows basic Organization license information to be read (GET) and updated (PUT) via the following URL:

https://us1.proofpointessentials.com/api/v1/orgs/mycompany.com/licensing

Reporting

Requests for email flow reports are made using the primary company domain as an identifier followed by a parameter that indicates the target time period. An optional direction parameter can be added to produce additional filtering. The URL is as follows:

https://us1.proofpointessentials.com/api/v1/reporting/mycompany.com

This will return data for a chosen time period, segregated by inbound/outbound, and broken down into both a total as well as time slots. An example for a monthly report is shown below (shortened for clarity):

{
  "period": "30d",
  "frequency": "24h",
  "inbound": {
    "attachment_defended_total": 0,
    "attachment_defended": {
      "{timestamp}": {value}, {
      "{timestamp}": {value}, {
    "}
    ...
    "whitelist_total": 0,
    "whitelist": {
      "{timestamp}": {value}, {
      "{timestamp}": {value}, {
    "}
  },
  "outbound": {
    "attachment_defended_total": 0,
    "attachment_defended": {
      "{timestamp}": {value}, {
      "{timestamp}": {value}, {
    "}
    ...
    "whitelist_total": 0,
    "whitelist": {
      "{timestamp}": {value}, {
      "{timestamp}": {value}, {
    "}
  }
}

Standard Conventions

There are some standard conventions used throughout the Proofpoint Essentials API:

All successful GET requests for a single resource will return a 200 OK response, along with a JSON representation of the resource requested.

{
  "primary_email": "bob@mycompany.com"
  ...
}

All successful GET requests for multiple resources will return a 200 OK response along with a list of resources, identified by the resource type (e.g. users)

{
  "users": [
    {
      "primary_email": "bob@mycompany.com"
      ...
    },
    {
      "primary_email": "jane@mycompany.com"
      ...
    }
  ]
}

All successful POST requests for a single resource will return a 201 Created response, along with a JSON representation of the created object.

All successful POST requests for multiple resources will return a 207 Multi-Status response, along with a list of created resources, and any failures. For example if a request to create three users was sent, and only two were successfully created, then the following response would be sent by the server:

{
  "users": [
    {
      "primary_email": "bob@mycompany.com"
      ...
    },
    {
      "primary_email": "jane@mycompany.com"
      ...
    }
  ],
 "errors": [
 {
   "status": 403,
   "identifier": "sue@unknowndomain.com",
   "error_message": "Forbidden: The domain is not registered to this Organization"
 }
 ]
}

All successful PUT requests will return a 204 No Content response, with no data returned.

All successful PATCH requests will return a 204 No Content response, with no data returned.

All authentication errors will return a 401 Unauthorized response, with no additional information.

All access errors will return a 403 Forbidden response, with an indication of the problem. Common causes are trying to access an organization not associated with the user, or trying to access the API with a user type that does not have API access.

NOTE: Only Organization Admins can access the API. It is not available to End Users.

When trying to create a resource that already exists a 409 Conflict will be returned.

When trying to create a resource with invalid data a 422 Unprocessable Entity will be returned, along with an indication of the problem.

Other errors will be specified by a 500 Internal Server Error response. In this case additional information on the error is not available.

Authentication

User-level

• User authentication is carried out by passing a Proofpoint Essentials registered username and password over TLS/SSL. These must be sent in every request in headers:

  X-User
  X-Password

• The log-in credentials provided during user authentication correspond to users registered on the Proofpoint Essentials platform, and the actions that any user can take using REST requests are limited by their role as described in the authorization section below.
• Unauthenticated users cannot make API requests.

Roles and Authorization

Proofpoint Essentials provides a hierarchy of entities and user types, with the rule of thumb being that higher-level resources can manage and create lower level resources.

Entity Types

Type Description
OEM Partner This type of entity can be a parent to Strategic and Channel partners as well as Organizations.
Strategic Partner This type of entity can be a parent to a Channel partner and an Organization.
Channel Partner This type of entity can be a parent to an Organization.
Organization This type of entity has no child entities beneath it.

User Roles and Privileges


Role Description
OEM Partner Admin Users with this role can create and update Strategic Partner, Channel partner and Organization type entities.
Strategic Partner Admin Users with this role can create and update Channel and Organization type entities.
Channel Partner Admin Users with this role can create and update Organization type entities.
Organization Admin Users with this role can create and update End Users and Silent Users within their Organization.
End-User Users with this role can manage their own configuration (UI only).
Silent User User with this role may not interact directly with the system.

Note: One admin account per Organization can be designated as a “Service Account”. The service account is not billable and is not factored into license or active user counts.

Odin Authentication

Some Organizations are configured to allow an additional authentication mechanism when logging into the Proofpoint Essentials Interface UI. To do this they use an Auth Token which is generated via an API request to the /api/v1/token endpoint.

The token endpoint will (if certain criteria is met) issue a token on request. Additional concerns to all API users are that the User resource has an odin_settings field with some odin specific fields. These can be ignored unless the user has the correct permissions and may result in a 422 response if erroneously specified. For non Odin users this field should be either set to null or simply omitted from POST/PUT requests.



Odin Setup through User Interface

Odin settings can be managed using either the API or the UI. The following guide uses the UI. See the API Documentation to complete Odin Setup through the API.

Activating Odin for Strategic/OEM Partner
Login as your Strategic/OEM Partner Admin. Navigate to the "Company Settings" tab. Tick the "Odin Platform Partner" box, then click the "Update Account Configuration" button. Ensure the Settings were saved.





Allowing Strategic/OEM Partner Admin to Impersonate
Login as your Strategic/OEM Partner Admin. Navigate to the "Users and Groups" tab. Select your Strategic/OEM Partner Admin User. Tick the "Can Impersonate (Service Access)" box, then click the "Save" button. Ensure the User Account was updated.







Allowing Organization Partner Admin to be Imitated
Login as your Organization Partner Admin. Navigate to the "Users and Groups" tab. Select your Organization Partner Admin User. Tick the "Is Imitable (Service Access)" box, then click the "Save" button. Ensure the User Account was updated.







Generating Login Tokens
Tokens may now be generated using the API. This token may be appended to the login URL and impersonation can proceed. Here is an example response from a token request.

{"auth_token":"cXR6ZDV-uZzl4dn-VqcWpjb"}
Append the token like shown:

https://us1.proofpointessentials.com/app/login.php?auth_token="cXR6ZDV-uZzl4dn-VqcWpjb"

You will now be imitating the chosen user.

Valid Values

This section details the values acceptable by the API.

Country Codes

2 character country identifiers

Country / Region Name Identifier
Afghanistan AF
Albania AL
Algeria DZ
American Samoa AS
Andorra AD
Angola AO
Anguilla AI
Antarctica AQ
Antigua and Barbuda AG
Argentina AR
Armenia AM
Aruba AW
Australia AU
Austria AT
Azerbaijan AZ
Bahamas BS
Bahrain BH
Bangladesh BD
Barbados BB
Belarus BY
Belgium BE
Belize BZ
Benin BJ
Bermuda BM
Bhutan BT
Bolivia BO
Bosnia and Herzegovina BA
Botswana BW
Brazil BR
British Indian Ocean Territory IO
British Virgin Islands VG
Brunei BN
Bulgaria BG
Burkina Faso BF
Burundi BI
Cambodia KH
Cameroon CM
Canada CA
Cape Verde CV
Cayman Islands KY
Central African Republic CF
Chad TD
Chile CL
China CN
Christmas Island CX
Cocos Islands CC
Colombia CO
Comoros KM
Cook Islands CK
Costa Rica CR
Croatia HR
Cuba CU
Curacao CW
Cyprus CY
Czech Republic CZ
Democratic Republic of the Congo CD
Denmark DK
Djibouti DJ
Dominica DM
Dominican Republic DO
East Timor TL
Ecuador EC
Egypt EG
El Salvador SV
Equatorial Guinea GQ
Eritrea ER
Estonia EE
Ethiopia ET
Falkland Islands FK
Faroe Islands FO
Fiji FJ
Finland FI
France FR
French Polynesia PF
Gabon GA
Gambia GM
Georgia GE
Germany DE
Ghana GH
Gibraltar GI
Greece GR
Greenland GL
Grenada GD
Guam GU
Guatemala GT
Guernsey GG
Guinea-Bissau GW
Guinea GN
Guyana GY
Haiti HT
Honduras HN
Hong Kong HK
Hungary HU
Iceland IS
India IN
Indonesia ID
Iran IR
Iraq IQ
Ireland IE
Isle Of Man IM
Israel IL
Italy IT
Ivory Coast CI
Jamaica JM
Japan JP
Jersey JE
Jordan JO
Kazakhstan KZ
Kenya KE
Kiribati KI
Kosovo XK
Kuwait KW
Kyrgyzstan KG
Laos LA
Latvia LV
Lebanon LB
Lesotho LS
Liberia LR
Libya LY
Liechtenstein LI
Lithuania LT
Luxembourg LU
Macau MO
Macedonia MK
Madagascar MG
Malawi MW
Malaysia MY
Maldives MV
Mali ML
Malta MT
Marshall Islands MH
Mauritania MR
Mauritius MU
Mayotte YT
Mexico MX
Micronesia FM
Moldova MD
Monaco MC
Mongolia MN
Montenegro ME
Montserrat MS
Morocco MA
Mozambique MZ
Myanmar MM
Namibia NA
Nauru NR
Nepal NP
Netherlands Antilles AN
Netherlands NL
New Caledonia NC
New Zealand NZ
Nicaragua NI
Niger NE
Nigeria NG
Niue NU
North Korea KP
Northern Mariana Islands MP
Norway NO
Oman OM
Pakistan PK
Palau PW
Palestine PS
Panama PA
Papua New Guinea PG
Paraguay PY
Peru PE
Philippines PH
Pitcairn PN
Poland PL
Portugal PT
Puerto Rico PR
Qatar QA
Republic of the Congo CG
Réunion RE
Romania RO
Russia RU
Rwanda RW
Saint Barthélemy BL
Saint Helena SH
Saint Kitts and Nevis KN
Saint Lucia LC
Saint Martin MF
Saint Pierre and Miquelon PM
Saint Vincent and The Grenadines VC
Samoa WS
San Marino SM
Sao Tome and Principe ST
Saudi Arabia SA
Senegal SN
Serbia RS
Seychelles SC
Sierra Leone SL
Singapore SG
Sint Maarten SX
Slovakia SK
Slovenia SI
Solomon Islands SB
Somalia SO
South Africa ZA
South Korea KR
South Sudan SS
Spain ES
Sri Lanka LK
Sudan SD
Suriname SR
Svalbard and Jan Mayen SJ
Swaziland SZ
Sweden SE
Switzerland CH
Syria SY
Taiwan TW
Tajikistan TJ
Tanzania TZ
Thailand TH
Togo TG
Tokelau TK
Tonga TO
Trinidad and Tobago TT
Tunisia TN
Turkey TR
Turkmenistan TM
Turks and Caicos Islands TC
Tuvalu TV
Uganda UG
Ukraine UA
United Arab Emirates AE
United Kingdom GB
United States US
Uruguay UY
US Virgin Islands VI
Uzbekistan UZ
Vanuatu VU
Vatican VA
Venezuela VE
Vietnam VN
Wallis and Futuna WF
Western Sahara EH
Yemen YE
Zambia ZM
Zimbabwe ZW

States/Provinces

State or Province for the Organization (required if Country is US or CA).

State / Province Name Identifier
Alabama AL
Alaska AK
Arizona AZ
Arkansas AR
California CA
Colorado CO
Connecticut CT
Delaware DE
District of Columbia DC
Florida FL
Georgia GA
Hawaii HI
Idaho ID
Illinois IL
Indiana IN
Iowa IA
Kansas KS
Kentucky KY
Louisiana LA
Maine ME
Maryland MD
Massachusetts MA
Michigan MI
Minnesota MN
Mississippi MS
Missouri MO
Montana MT
Nebraska NE
Nevada NV
New Hampshire NH
New Jersey NJ
New Mexico NM
New York NY
North Carolina NC
North Dakota ND
Ohio OH
Oklahoma OK
Oregon OR
Pennsylvania PA
Rhode Island RI
South Carolina SC
South Dakota SD
Tennessee TN
Texas TX
Utah UT
Vermont VT
Virginia VA
Washington WA
West Virginia WV
Wisconsin WI
Wyoming WY
Commonwealth/Territory
American Samoa AS
Federated States of Micronesia FM
Guam GU
Marshall Islands MH
Northern Mariana Islands MP
Palau PW
Puerto Rico PR
Virgin Islands VI
Canadian Provinces
Alberta AB
British Columbia BC
Manitoba MB
New Brunswick NB
Newfoundland and Labrador NL
Northwest Territories NS
Nova Scotia NT
Nunavut NU
Ontario ON
Prince Edward Island PE
Quebec QC
Saskatchewan SK
Yukon YT

Migrating to v1

Endpoint Changes

Existing Endpoint Endpoint changed? Versioned Endpoint GET POST PUT PATCH DEL Notes
/api/endpoint/{domain} Y /api/v1/endpoints/{domain} Y N N N N Read list of endpoints for an org.
/api/orgs/{domain} N /api/v1/orgs/{domain} Y N Y N Y Single Org actions.
/api/orgs/{domain}/orgs N /api/v1/orgs/{domain}/orgs Y Y N N N Actions on set of orgs. POST will add org(s).
/api/domains/{domain} Y /api/v1/orgs/{domain}/domains Y Y N N N List of domains belonging associated with an Org.
/api/domains/{domain}/{domain} Y /api/v1/orgs/{domain}/domains/{domain} Y N N Y Y Single domain, which is under an Org.
/api/orgs/{domain}/users N /api/v1/orgs/{domain}/users Y Y N N N Actions on set of users. POST will add user(s).
/api/orgs/{domain}/users/{user_email} N /api/v1/orgs/{domain}/users/{user_email} Y N Y N Y Read existing user, PUT to update, DELETE to remove.
/api/orgs/{domain}/features N /api/v1/orgs/{domain}/features Y N Y N N Read and update features.
/api/orgs/{domain}/licensing N /api/v1/orgs/{domain}/licensing Y N Y N N Read and update licensing.
/api/orgs/{domain}/package N /api/v1/orgs/{domain}/package N N Y N N Update the package type.
/api/token N /api/v1/token N Y N N N Changed from PUT to POST.

Data Changes

Item Change Details
All Schema All booleans Will be either true/false. No more 0/1 "false"/"true" values will be returned.
All strings Will be "" if not present, rather than null.
All arrays All arrays should be empty arrays, rather than null.
Org Schema type Changed spelling of 'organisation' to 'organization'
licencing_package Renamed licensing_package
user_licences Renamed user_licenses
on_trial Renamed is_on_trial
beginner_plus_enabled Renamed is_beginner_plus_enabled
send_welcome_email Added to schema
exe_bypass_enabled Removed from schema
smtp_discovery_enabled Renamed is_smtp_discovery_enabled
admin_user See User schema change. Note that it is now consistent with the specific user schema.
domains See Domain schema change. Note that it is now consistent with the specific domain schema.
eid Now shown in Org GET
organization_hierarchy New field to show the hierarchy of the org. This is a list of it's self + parents ("eid : name").
odin_capabilities New field to show if odin capabilities exist on the org.
av_bypass_senders Removed from V1 Orgs.
white_list_senders Sender lists are validated up front before the org is created, to avoid partial list creation. Any invalid items will cause a 422 and error with the offending items.
black_list_senders
User Schema isactive Renamed is_active
uid Now shown in User GET.
type Changed spelling of 'organisation' to 'organization'.
is_billable Regular user parameter now, defaults to true.
is_imitable, can_impersonate Moved into an odin_settings sub object. Any values supplied are IGNORED unless they are allowed by the user type. Should be null if not required.
white_list_senders Sender lists are validated up front before the org is created, to avoid partial list creation. Any invalid items will cause a 422 and error with the offending items.
black_list_senders
Domain Schema domain_name / name Always name
failover Renamed failovers. Changed from string to an array of values.
transports Removed from versioned API.
Features Schema All items Uses booleans now (with exception of instant_replay).
Licensing Schema on_trial Renamed is_on_trial
Package Schema eula_confirmed Renamed is_eula_confirmed
trial_extended Renamed is_trial_extended
activate Renamed is_activated
Reporting Schema options hourly/weekly/monthly Changed to daily/weekly/monthly
V Renamed virus
A Renamed attachment_defended
I Renamed image_blocked
B Renamed blacklist
W Renamed whitelist
S Renamed spam
C Renamed clean
Extra fields Added period and frequency fields for clarity, e.g. "period": "30d", "frequency": "24h".
Added totals Added totals for inbound and outbound metrics. inbound_totals + outbound_totals.

Request Changes

Item Change Details
Org Endpoint PUT on Org Resource Replaced with PATCH as only the is_active field can be changed. PUT would require the entire Org resource.
Token Endpoint PUT changed to POST We are creating a new token so POST + 201 response is more appropriate.
All PUT requests Ignoring features that are not available to the entity is now removed and any such requests will result in a 403 Forbidden with appropriate error message.

Response Changes

Item Change Details
All Schema All responses will set the HTTP response code header correctly (200/400/500 etc) and will match the code specified in the body (if applicable).
Batch updates Batch updates (multiple entities in a POST request) will return the following schema (includes the created resource(s)):

{ "users": [ { ..user1.. }, { ..user2.. } }, "errors": [ { "status": 404, "error_message": "Not Found" } ] }
All Endpoints All requests with invalid auth Return a 401 with no message. For security reasons no information will be given on failure reason.
All GET responses Reworked to remove Result wrapper. Simply returns the requested resource/list of resources.
All PUT responses All PUT requests return 204 (NO_CONTENT) on successful update.
All PATCH responses All PATCH requests return 204 (NO_CONTENT) on successful update.
All POST requests where resource already exists Return a 409 (CONFLICT) on successful update.
All POST / PUT requests with invalid data Return a 422 (UNPROCESSABLE_ENTITY) with some indication of what failed.
Trying to access a resource you don't have access to Return a 403 (FORBIDDEN).

Errors

Errors will be wrapped in a generic JSON object with error messages etc.

Error Responses Error Code Notes
Authentication failure 401 Any problems with credentials will result in a 401 with NO additional information. These include missing or malformed parameters.
Bad Request 400 General bad request data, empty/malformed JSON etc.
Authorization failure 403 Credentials are valid, but an attempt is made to access a restricted resource.
Resource not found 404 Unknown / malformed endpoint
Conflict (resource exists) 409 Trying to create a resource that exists. e.g. a user already on system.
Validation error 422 POST/PUT/PATCH value errors (missing fields, badly formatted values etc).
General server error 500 Generic server side error. Request should be able to be retried.