Skip to content
Mailgun Optimize/API Documentation/
/
List Spam Trap Hits

Alerts (0.0.1)

Our alerting solution is centered around two concepts: events and channels. The occurrence of an event can be configured to trigger an alert. A channel describes the delivery method for an alert. Every configured alert consists of an event type / channel pair. This level of granularity allows alerting to be configured to your exact preference.

Download OpenAPI description
inboxready.json
inboxready.yaml
Languages
Servers
US Mailgun

https://api.mailgun.net/

EU Mailgun

https://api.eu.mailgun.net/

Domains

Operations

DMARC Reports

DMARC reporting provides valuable insights into your infrastructure, helping you identify potential issues like senders, misconfigured email servers, or phishing attempts.

Operations

Inbox Placement

Inbox Placement testing allows you to see the likely deliverability of your email campaigns.

Operations

Spam Traps Monitoring

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

Operations

List Spam Trap Hits

Request

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.

Security
basicAuth
Query
startstring(date-time)

The start timestamp in RFC3339 format(YYYY-MM-DDThh:mm:ssZ) of the timeframe for which you wish to see data. Default is 7 days ago

endstring(date-time)

The end timestamp in RFC3339 format(YYYY-MM-DDThh:mm:ssZ) of the timeframe for which you wish to see data. Default is now

dimensionstring

Use this field to group results.

Enum ValueDescription
timestamp

Group by date

domain_name

Group by domain

ip

Group by IP address

sender

Group by sender address

from

Group by from

tags

Group by tags

subaccount

Group by subaccount

sortstring

Sort field and order, in form of 'field:order'

Default "same as dimension"
ipArray of strings

Use this field to filter results by ip(s).

domainArray of strings

Use this field to filter results by domain(s).

senderArray of strings

Use this field to filter results by sender email address.

fromArray of strings

Use this field to filter results by from address.

limitintegerrequired

Limits the number of items returned in a request

include_subaccountsboolean

Include subaccounts

Default false
curl -i -X GET \
  -u <username>:<password> \
  'https://api.mailgun.net/v2/spamtraps?start=2019-08-24T14%3A15%3A22Z&end=2019-08-24T14%3A15%3A22Z&dimension=timestamp&sort=same+as+dimension&ip=string&domain=string&sender=string&from=string&limit=0&include_subaccounts=false'

Responses

A 200 response

Bodyapplication/json
itemsArray of objects(Spamtraps_Analytics_Service_github.com-mailgun-spamtraps-model-CountsItem)required
items[].​account_idstring or null

Mailgun account ID.

items[].​account_namestring or null

Mailgun account name.

items[].​timestampstring or null(date-time)
items[].​domainstring or null

Domain name.

items[].​ipstring or null

IP address.

items[].​senderstring or null

Sender address, e.g. john.smith@example.com

items[].​fromstring or null

From address, e.g. "John Smith" john.smith@example.com

items[].​tagsArray of strings

Tags. See User Manual -> Tracking Messages -> Tagging for more details.

items[].​ip_poolstring or null

IP pool ID.

items[].​pristineinteger(int64)required

Pristine counter.

items[].​recycledinteger(int64)required

Recycled counter.

items[].​typointeger(int64)required

Typo counter.

items[].​harvestedinteger(int64)required

Harvested counter.

items[].​totalinteger(int64)required

Sum of pristine, recycled, typo, harvested counters.

pagingobject(Spamtraps_Analytics_Service_github.com-mailgun-spamtraps-api-PagingResponse)required
paging.​firststringrequired
paging.​previousstringrequired
paging.​nextstringrequired
paging.​laststringrequired
totalinteger(int64)required
Response
application/json
{
  "items": [
    { … },
    { … }
  ],
  "paging": {},
  "total": 2
}

Get Spam Trap HitsDeprecated

Request

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. Deprecated: Use /v2/spamtraps endpoint.

Security
basicAuth
Query
startstringrequired

The start date in UTC (format YYYY-MM-DD) of the timeframe for which you wish to see data.

endstringrequired

The end date in UTC (format YYYY-MM-DD) of the timeframe for which you wish to see data.

sortbystring

Acceptable values include date, totals, domain, subject, ip, and from. Defaults to date.

groupbystring

Use this field to group results. Acceptable values include domain, subject, ip, and from.

subjectArray of strings

Use this field to filter results by email subject(s).

domainArray of strings

Use this field to filter results by domain(s).

ipArray of strings

Use this field to filter results by ip(s).

fromArray of strings

Use this field to filter results by from address.

limitintegerrequired

Limits the number of items returned in a request

curl -i -X GET \
  -u <username>:<password> \
  'https://api.mailgun.net/v1/spamtraps?start=string&end=string&sortby=string&groupby=string&subject=string&domain=string&ip=string&from=string&limit=0'

Responses

A 200 response

Bodyapplication/json
itemsArray of objects(Spamtraps_Analytics_Service_github.com-mailgun-spamtraps-model-DatedTotals)required
items[].​datestringrequired
items[].​pristineinteger(int32)required
items[].​recycledinteger(int32)required
items[].​typointeger(int32)required
items[].​harvestedinteger(int32)required
items[].​totalinteger(int32)required
pagingobject(Spamtraps_Analytics_Service_github.com-mailgun-spamtraps-api-PagingResponse)required
paging.​firststringrequired
paging.​previousstringrequired
paging.​nextstringrequired
paging.​laststringrequired
Response
application/json
{
  "items": [
    { … },
    { … }
  ],
  "paging": {}
}

Email Health Score

Operations

IP Blocklist Monitoring

Operations

Domain Blocklist Monitoring

Blocklist Monitoring enables you to keep an eye on your reputation. Monitor your domains against our curated list of blocklist providers to make sure you aren't being blocked.

Operations

Google Postmaster Tools

This API provides access to Google Postmaster data.

Operations

Microsoft SNDS

This API provides access to Microsoft SNDS data.

Operations

Alerts

Operations