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.

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}, {

    "}

    ...

    "safelist_total": 0,

    "safelist": {

      "{timestamp}": {value}, {

      "{timestamp}": {value}, {

    "}

  },

  "outbound": {

    "attachment_defended_total": 0,

    "attachment_defended": {

      "{timestamp}": {value}, {

      "{timestamp}": {value}, {

    "}

    ...

    "safelist_total": 0,

    "safelist": {

      "{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

Roles and Authorization

Entity Types

User Roles and Privileges

Odin Authentication

Odin Setup through User Interface

Activating Odin for Strategic/OEM Partner

Allowing Strategic/OEM Partner Admin to Impersonate

Allowing Organization Partner Admin to be Imitated

Generating Login Tokens

{"auth_token":"cXR6ZDV-uZzl4dn-VqcWpjb"}

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

States/Provinces

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

Migrating to v1

Endpoint Changes

Data Changes

Request Changes

Response Changes

Errors

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

Deprecation Notices

Sender List Terms

Sender lists in requests and responses have undergone a name change.
Please note: There is no change to the functionality of sender lists.

Request Changes

Deprecated terms will continue be supported in request data.

It is highly recommended that the terms used in requests are updated at your earliest convenience. Support for old terms will be available for a limited time only.

When the support for the deprecated terms is removed, the presence of the deprecated terms will cause the following error:

Response Changes

Deprecated terms will continue be supported in response data.

The deprecated terms will continue to be included in response data by default for the following items while they are supported.

It is highly recommended that the terms used in responses are updated at your earliest convenience. Support for old terms will be available for a limited time only. In order to transition towards using the new updated terms in responses, the following header can be included when making a request, this will ensure new terms are returned in response data:

X-Terms-Update: true

When the support for the deprecated terms is removed, the following items will no longer include the deprecated terms in response bodies, they will instead be replaced by the updated terms e.g. white_list_senders replaced by safe_list_senders.

Reporting Image Stats

Image totals have been deprecated. They will continue to be supported in the response data, but will always be zero.
Please note: There is no change to the functionality of reporting.