Skip to main content
Contact Us
My preferencesSign out
Proofpoint, Inc.

API and Domains

  1. Last updated
  2. Save as PDF
Situation You want to use the API but need to learn how to add, remove, or update domains from the organization via scripting/JSON.
Solution Using this guide to review the options that the API has to offer as well as validate the information being sent to ensure that it successfully makes the changes requested.

API /domains

Proofpoint has a REST API with a variety of features. It can be accessed with any software/programming language that can interpret JSON. For this article, we will examine the Domains (/domains) feature more closely.

Keep in mind: Proofpoint will not troubleshoot scripts or programming calls made to utilize the API. However, we can test to ensure that there are no issues concerning API functionality.

Domains Call Examples

Domains calls (/domains) has a number of uses and functionality. Here you are able to create, manage, and delete domains associated with the organization. You may also designate delivery destination as well as fail-overs for the domain. Assume the following for this documentation:

 From the documentation on the site, you can expect the following GET output from /domains:

Sample call for GET:
https://stack#.proofpointessentials.com/api/v1/orgs/domain.com/domains

JSON Results:

{
  "name": "sample.com",
  "is_active": false,
  "is_relay": false,
  "destination": "10.20.30.40",
  "failovers": [
    "10.30.40.50",
    "10.40.50.60"
  ]
}


How To Make Calls To The API

REQUIREMENTS

A call for this role of the API will require coding, software, or scripting utilizing JSON. Internally we have used Powershell & Python to communicate with the API but any language that has JSON interaction will be able to accomplish the same goal. For Domains (/domains), you will need to utilize header fields for GET commands & DELETE commands. For PUT & POST commands, you will also need to include JSON structured requests.

Permissions

The call must use the credentials of a user who is at least an Organization Admin.

Headers

Ensure your headers have two entries:

  • X-user - This will be your full email address associated with the organization with the required permissions.
  • X-password - This will be the password for the username being used for this call.

Available Calls

For Domains (/domains), there are four (4) available calls. You will want to replace domain.com with the domain that you wish to use for this service. Additionally, you will replace stack# with the appropriate stack which the domain is normally accessed through.

GET Call (Information Grab)

Method: GET

https://stack#.proofpointessentials.com/api/v1/orgs/domain.com/domains
POST Call (Add a New Domain to the Organization)

Method: POST

https://stack#.proofpointessentials.com/api/v1/orgs/domain.com/domains/newdomain.com
Required Fields for JSON POST Request
{
  "name": "mydomain.com",
  "is_active": false,  #acceptable inputs: false, true
  "is_relay": false,  #acceptable inputs: false, true
  "destination": "10.20.30.40",
  "failovers": [   #Alternatively can be left blank by doing open/closed brackets
    "10.30.40.50",
    "10.40.50.60"
  ]
}

## Failovers blank example:
  "failovers": [
  ]
Response Codes for POST Requests (/domains):
Code Description
201 single domain created (Should echo the domain that was added with the configuration set.)
207 batch response, individual responses contained within. (201 with the created domain, for example)
400 bad request (invalid data, missing data, incorrect values used, etc)
403 not authorized (account permissions need to be corrected, invalid account used, etc)
409 resource already exists (domain is already existing on the Essentials platform)
422 invalid request data (invalid data, missing data, incorrect values used, etc)
500 internal server error (connection timed out, missing headers, ISP issue, etc)
PUT Call (Update Existing Domain Information)

Method: PUT 

https://stack#.proofpointessentials.com/api/v1/orgs/domain.com/domains/domaintoupdate.com

This will Update existing domains only. You can use this with the primary domain by putting in the domain name after the domains call. Example to update primary domain:

https://stack#.proofpointessentials.com/api/v1/orgs/domain.com/domains/domain.com
Required Fields for JSON PUT Request:
{
  "name": "mydomain.com",
  "is_active": false,  #acceptable inputs: false, true
  "is_relay": false,  #acceptable inputs: false, true
  "destination": "10.20.30.40",
  "failovers": [   #Alternatively can be left blank by doing open/closed brackets (see below call)
    "10.30.40.50",
    "10.40.50.60"
  ]
}

## Failovers blank example:
  "failovers": [
  ]

Return Codes related to this request:

Code Description
204 no content, successfully updated the domain
400 bad request (invalid syntax, no headers, incorrect address, etc)
401 invalid credentials (mistyped username/password, no headers included with call, etc)
403 not authorized (incorrect permissions, incorrect domain, incorrect address)
422 invalid request data (JSON missing mandatory fields, incorrect data change requests, etc)
500 internal server error (connection timed out, missing headers, ISP issue, etc)
DELETE Call (Removal of domains from an organization)

Method: DELETE

https://stack#.proofpointessentials.com/api/v1/orgs/domain.com/domains/deletethis.com
Required Fields for JSON Delete Call:

None. This is a call strictly made via the call from your program. The following return codes may be of use to determine the success of your call:

Code Description
204 no content, successful deletion
400 bad request (Invalid Site, mistyped address, etc)
401 invalid credentials (incorrect permission level, bad password, bad username, etc)
403 not authorized (not associated with the domain, wrong stack number, wrong location)
500 internal server error (bad call syntax, did not include headers, timeout issue, ISP issue, etc)

Conclusion

Creating scripts to regularly maintain your customers will help create fail-proof, rapid-fire results that will allow you the ability to quickly adjust a company's domain configuration and even queue up multiple changes if you are looking to make sweeping updates. These calls will help you manage your clients via scripting and the API that Proofpoint Essentials has to offer.