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.

Copy

Copied

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:

Copy

Copied

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

Copy

Copied

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:

Copy

Copied

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