Skip to main content
My preferencesSign out
Proofpoint, Inc.

Stats API

Statistics API (/Stats)

Proofpoint does have 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 be examining the Stats 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.

Stats Data Calls

All Statistic reporting from the API are merely numeric. You cannot view any data regarding the emails such as To, From, Subject, Date, etc. It is only for a numeric report of the quantity of emails that were sent, received, blocked, marked as spam, or marked as a virus for inbound and outbound mail flow.

 From the documentation on the site, you can expect the following output from the Statistics call:

ib_total: Total inbound mail, including clean mail.
ob_total: Total outbound mail, including clean mail.
ib_blocked: Total inbound blocked mail, including all threats detected and blocked mail (organization/user blocked sender list entries and filters).
ob_blocked: Total outbound blocked mail, including all threats detected and blocked mail (organization/user filters).
active_users: Number of active users during each period. Active users are those with mail during the time period.
ib_spam: Total inbound mail marked as spam. This includes all mail marked as spam, imposter and phish.
ib_virus: Total inbound mail marked as virus.
ib_mal_att: Total inbound mail marked as containing a malicious attachment.
ib_imposter: Total inbound mail marked as imposter.
ib_phish: Total inbound mail marked as a phish.
ob_enc: Total outbound encrypted mail.
The time periods (UTC) are defined as follows:
1 day: 24 hours from the previous midnight.
7 day: 7 days from the previous midnight.
30 day: 30 days from the previous midnight.
90 day: 90 days from the previous midnight.

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 Stats, you will only need to utilize headers in order to connect to the API.

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.
  • X-password - This will be the password for the username being used for this call.

Available Calls

For Stats, there are two 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.

Stats for a Single Domain

https://stack#.proofpointessentials.com/api/v1/stats/domain.com/partner

Stats for a Domain and Associated Children

https://stack#.proofpointessentials.com/api/v1/stats/domain.com/partner/orgs

Sample Readout

When you have successfully completed the API call, you should get a response in a format similar to the ones below.

The data reported is fictional and only a portion of the final result.

           "active_users": {
                "count_1d": 192,
                "count_7d": 1171,
                "count_30d": 1726,
                "count_90d": 2133
            },
            "ib_total": {
                "count_1d": 1740,
                "count_7d": 2081,
                "count_30d": 12023,
                "count_90d": 42812

Conclusion

This data can be used to help understand patterns and behaviors within the organization. With the aid of scripting, you can acquire more precise data to help find trends or identify specific mail flow behaviors. For all of the potential calls within the API, and to find out if this method could benefit your usage with Proofpoint, please utilize any of the links above to visit the API Specifications (https://us1.proofpointessentials.com/api/v1/docs/specification.php) for a full list of calls and what type of data are associated with them.