Spam Trap Monitoring¶
Our spam trap monitoring service surfaces how much of your email is being sent to known spam traps.
Add Domain¶
This endpoint allows domains to be registered for spam trap monitoring. Please
note that your domain or subdomain must be verified before spam trap monitoring
can begin. Once your domain has been added, add the provided TXT record
(txt_record
) to your domain configuration within your DNS provider. For
more details, see our documentation. Following TXT record configuration, use
the Verify Domain endpoint to begin the domain verification process.
NOTE: If your domain is already verified for sending email via Mailgun, you do not need to configure the provided TXT record. Instead, skip to the Verify Domain section.
POST /v1/inboxready/domains
The available request fields are as follows:
Field | Description |
---|---|
domain |
Required. The domain or subdomain that you wish to add. |
Example 200 response:
{
"domain": {
"ID": "<ID>",
"created_at": 123456789,
"name": "example.com",
"verified": {
"verified_at": 0,
"status": "pending"
},
"services": {
"spam_trap_monitoring": true
},
"txt_record": "<HASHED TXT RECORD KEY>"
},
"message": "The domain has been added"
}
Verify Domain¶
Use this endpoint to start the domain verification process. When called, a background process will begin to periodically attempt domain verification for up to 24 hours.
Please note that domain verification is not instant. DNS verification typically takes 1 hour to complete, but in some cases may take up to 24 hours to complete. Feel free to check your DNS configuration for accuracy, but please allow for up to 24 hours for the verification process to complete.
The Get Domains endpoint can be used to check verification status. On
verification success, the domain verified.status
property will contain a
value of “inbox_ready” or “sending”.
NOTE: In the case that your domain is already verified for sending email
via Mailgun, you will still need to use this endpoint to begin the verification
process. Your domain verification status will be inherited from Mailgun. Upon
verification, your domain’s verified.status
will be set to “sending”. Please
note that in this scenario, verification is still performed via the background
process workflow and that there will be a ~1 hour delay in verification.
PUT /v1/inboxready/domains/verify
The available request fields are as follows:
Field | Description |
---|---|
domain |
Required. The domain or subdomain that you wish to verify. |
Example 200 response:
{
"message": "Domain pending verification"
}
Get Domains¶
This endpoint returns a list of domains.
GET /v1/inboxready/domains
Example 200 response:
{
"items": [
{
"ID": "<ID>",
"created_at": 123456789,
"name": "example.com",
"verified": {
"verified_at": 123456789,
"status": "inbox_ready"
},
"services": {
"spam_trap_monitoring": true
},
"txt_record": "<HASHED TXT RECORD KEY>"
},
...
],
"paging": {
"previous": "<URL>",
"first": "<URL>",
"next": "<URL>",
"last": "<URL>"
}
}
Remove Domain¶
This endpoint can be used to remove a domain from spam trap monitoring.
DELETE /v1/inboxready/domains
The available request fields are as follows:
Field | Description |
---|---|
domain |
Required. The domain or subdomain that you wish to remove. |
Example 200 response:
{
"message": "example.com has been removed from InboxReady"
}
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": {
...
}
}