Statistics API

Full Documentation

The coding to connect requires a connection with the Base URL, along with the path: /api/v1. Make sure to appropriately use the base path of the stack of the domain you are working with is specifically on. API calls are stack-dependent, if you only have credentials for one stack i.e. US3 you will have to validate your credentials against that URL

Example for US3: https://us-spambrella.cloud-protect.net/api/v1

Example for EU1: https://spambrella.cloud-protect.net/api/v1

Stats Data Calls

All Statistic reporting from the API is 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: All total inbound mail.
ob_total: All total outbound 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 quarantined as spam.
ib_virus: Total inbound mail quarantined as virus.
ib_mal_att: Total inbound mail quarantined as containing a malicious attachment. [Attachment Defense/Sandboxing included]
ib_imposter: Total inbound mail quarantined as imposter.
ib_phish: Total inbound mail quarantined 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 that the domain is normally accessed through.

Stats For A Single Domain

https://stack#.spambrella.cloud-protect.net/api/v1/stats/domain.com/partner

Stats For A Domain And Associated Children

https://stack#.spambrella.cloud-protect.net/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 (REST API Specification) for a full list of calls and what type of data are associated with them.

Last Updated/Reviewed: Mar-31-2022

Statistics API

Integrate via API