Spam Trap Monitoring

Our spam trap monitoring service surfaces how much of your email is being sent to known spam traps.

To add and remove domains from our spam trap monitoring service, see the domain management API docs.

Get Counts

Use this endpoint to understand how much of your mail being sent to known spam traps. This endpoint returns daily spam trap hit counts for a provided timerange, categorized by trap type.

NOTE: You must provide a timerange via start and end query params. If any date(s) at the start and/or end boundaries of your provided timerange contain zero spam trap hits, those dates will be excluded from the response.

GET /v1/spamtraps?start=2022-01-01&end=2022-01-31

The available request fields are as follows:

Field	Description
start	Required. The start date in UTC (format YYYY-MM-DD) of the timeframe for which you wish to see data.
end	Required. The end date in UTC (format YYYY-MM-DD) of the timeframe for which you wish to see data.
sortby	Optional. Acceptable values include date, totals, domain, subject, ip, and from. Defaults to date.
groupby	Optional. Use this field to group results. Acceptable values include domain, subject, ip, and from.

Example 200 response:

{
  "items": [
    {
      "date": "2022-01-01",
      "pristine": 34,
      "recycled": 258,
      "typo": 178,
      "total": 470
    },
    ...
  ],
  "paging": {
    ...
  }
}

For more details on the data returned by this API endpoint such as trap types, see our help documentation.

Filtered Results

The request fields below can be used to filter spam trip hit counts:

Field	Description
ip	Optional. Use this field to filter results by ip(s).
domain	Optional. Use this field to filter results by domain(s).
subject	Optional. Use this field to filter results by email subject.
from	Optional. Use this field to filter results by sender email address.

Example request of results grouped by IP and filtered by multiple IP addresses:

GET /v1/spamtraps?start=2022-01-01&end=2022-01-31&groupby=ip&ip=208.75.123.183&ip=208.75.123.186

Example 200 response:

{
  "items": [
    {
      "208.75.123.183": [
        {
          "date": "2022-01-01",
          "pristine": 2,
          "recycled": 85,
          "typo": 32,
          "total": 119
        },
        ...
      ]
    },
    {
      "208.75.123.186": [
        ...
      ]
    },
  ],
  "paging": {
    ...
  }
}