Stats

Mailgun collects many different events and generates event statistics which are available in your Control Panel. This data is also available via our stats API endpoint.

Totals for entire account

get/v3/stats/total

Gets stat totals for an entire account

SecuritybasicAuth

Request

query Parameters

event required	string Name of the event(s) to receive the stats for (Multiple events are allowed). Supported events are: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored
start	string The start date in RFC 2822 format or unix epoch (default: 7 days ago)
end	string The end date in RFC 2822 format or unix epoch (default: current time)
resolution	string The gregorian resolution the query is for 'day, month, hour` (default: day)
duration	string If duration is provided than it's calculated from the 'end' date and overwrites the 'start' date

Responses

200

A 200 response

Response Schema: application/json

description required	string
start required	string
end required	string
resolution required	string
required	Array of objects
tag	string
	object

400

A 400 response

Request samples

Response samples

application/json

{"resolution": "month",
"description": "Optional Description",
"start": "Tue, 14 Feb 2012 00:00:00 UTC",
"stats": [{"accepted": {"incoming": 2,
"outgoing": 1,
"total": 3
},
"clicked": {"total": 1,
"unique": 1
},
"delivered": {"http": 10,
"optimized": 5,
"smtp": 15,
"total": 20
},
"opened": {"total": 20,
"unique": 1
},
"time": "Fri, 01 Apr 2012 00:00:00 UTC"
}
],
"end": "Fri, 01 Apr 2012 00:00:00 UTC"
}

Totals for entire domain

get/v3/{domain}/stats/total

Gets stat totals for an entire domain

SecuritybasicAuth

Request

path Parameters

domain

required

string

The domain name

query Parameters

event required	string Name of the event(s) to receive the stats for (Multiple events are allowed). Supported events are: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored
start	string The start date in RFC 2822 format or unix epoch (default: 7 days ago)
end	string The end date in RFC 2822 format or unix epoch (default: current time)
resolution	string The gregorian resolution the query is for 'day, month, hour` (default: day)
duration	string If duration is provided than it's calculated from the 'end' date and overwrites the 'start' date

Responses

200

A 200 response

Response Schema: application/json

description required	string
start required	string
end required	string
resolution required	string
required	Array of objects
tag	string
	object

400

A 400 response

Request samples

Response samples

application/json

{"resolution": "month",
"description": "Optional Description",
"stats": [{"accepted": {"incoming": 2,
"outgoing": 1,
"total": 3
},
"clicked": {"total": 1,
"unique": 1
},
"delivered": {"http": 10,
"optimized": 5,
"smtp": 15,
"total": 20
},
"opened": {"total": 20,
"unique": 1
},
"time": "Fri, 01 Apr 2012 00:00:00 UTC"
}
],
"start": "Tue, 14 Feb 2012 00:00:00 UTC",
"end": "Fri, 01 Apr 2012 00:00:00 UTC"
}

Totals for account domains for a single time resolution

get/v3/stats/total/domains

Gets stat totals for domains in an account for a single time resolution

SecuritybasicAuth

Request

query Parameters

event required	string Name of the event(s) to receive the stats for (Multiple events are allowed). Supported events are: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored
timestamp required	string The date/time of the 'resolution' we are retrieving
limit	string Skip x number of domains; used to page through large numbers of domains
resolution	string The gregorian resolution the query is for 'day, month, hour` (default: day)

Responses

200

A 200 response

Response Schema: application/json

description required	string
start required	string
end required	string
resolution required	string
required	Array of objects
tag	string
	object

400

A 400 response

Request samples

Response samples

application/json

{"start": "Tue, 14 Feb 2012 00:00:00 UTC",
"description": "Optional Description",
"end": "Fri, 01 Apr 2012 00:00:00 UTC",
"resolution": "month",
"stats": [{"accepted": {"incoming": 2,
"outgoing": 1,
"total": 3
},
"clicked": {"total": 1,
"unique": 1
},
"delivered": {"http": 10,
"optimized": 5,
"smtp": 15,
"total": 20
},
"opened": {"total": 20,
"unique": 1
},
"time": "Fri, 01 Apr 2012 00:00:00 UTC"
}
]
}

Filtered/grouped totals for entire account

get/v3/stats/filter

Gets filtered and group stat totals for an entire account

SecuritybasicAuth

Request

query Parameters

event required	string Name of the event(s) to receive the stats for (Multiple events are allowed). Supported events are: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored
start	string The start date in RFC 2822 format or unix epoch (default: 7 days ago)
end	string The end date in RFC 2822 format or unix epoch (default: current time)
resolution	string The gregorian resolution the query is for 'day, month, hour` (default: day)
duration	string If duration is provided than it's calculated from the 'end' date and overwrites the 'start' date
filter	string A filter for account level metrics such as filter=domain:my.example.com
group	string The key to group metrics by. Must be one of total, time, day, month, domain, ip, provider, tag, country

Responses

200

A 200 response

Response Schema: application/json

description required	string
start required	string
end required	string
resolution required	string
required	Array of objects
tag	string
	object

400

A 400 response

Request samples

Response samples

application/json

{"stats": [{"accepted": {"incoming": 2,
"outgoing": 1,
"total": 3
},
"clicked": {"total": 1,
"unique": 1
},
"delivered": {"http": 10,
"optimized": 5,
"smtp": 15,
"total": 20
},
"opened": {"total": 20,
"unique": 1
},
"time": "Fri, 01 Apr 2012 00:00:00 UTC"
}
],
"resolution": "month",
"start": "Tue, 14 Feb 2012 00:00:00 UTC",
"description": "Optional Description",
"end": "Fri, 01 Apr 2012 00:00:00 UTC"
}

Aggregate counts by ESP

get/v3/{domain}/aggregates/providers

Gets aggregate counts by email service provider

SecuritybasicAuth

Request

path Parameters

domain

required

string

The domain name

Responses

200

A 200 response

Response Schema: application/json

object

additional property

object

property name*

additional property

integer <int32>

400

A 400 response

Request samples

Response samples

application/json

{"providers": {"aol.com": {"unsubscribed": 0,
"accepted": 0,
"clicked": 1,
"opened": 1,
"unique_clicked": 1
},
"gmail.com": {"accepted": 0,
"clicked": 2,
"opened": 1,
"unique_clicked": 1,
"unsubscribed": 0
}
}
}

Aggregate counts by devices triggering events

get/v3/{domain}/aggregates/devices

Gets aggregate counts on devices that triggered events ('tablet', 'phone', 'pc', etc…)

SecuritybasicAuth

Request

path Parameters

domain

required

string

The domain name

Responses

200

A 200 response

Response Schema: application/json

object

additional property

object

property name*

additional property

integer <int32>

400

A 400 response

Request samples

Response samples

application/json

{"devices": {"unknown": {"unsubscribed": 0,
"accepted": 0,
"clicked": 2,
"opened": 1,
"unique_clicked": 1
},
"desktop": {"accepted": 0,
"clicked": 1,
"opened": 1,
"unique_clicked": 1,
"unsubscribed": 0
},
"mobile": {"accepted": 0,
"clicked": 2,
"opened": 1,
"unique_clicked": 1,
"unsubscribed": 0
},
"tablet": {"unsubscribed": 0,
"accepted": 0,
"clicked": 2,
"opened": 1,
"unique_clicked": 1
}
}
}

Aggregate counts by country

get/v3/{domain}/aggregates/countries

Gets aggregate counts by country (USA, RUS, etc…)

SecuritybasicAuth

Request

path Parameters

domain

required

string

The domain name

Responses

200

A 200 response

Response Schema: application/json

object

additional property

object

property name*

additional property

integer <int32>

400

A 400 response

Request samples

Response samples

application/json

{"countries": {"us": {"accepted": 0,
"clicked": 1,
"opened": 1,
"unique_clicked": 1,
"unsubscribed": 0
},
"ru": {"accepted": 0,
"clicked": 2,
"opened": 1,
"unique_clicked": 1,
"unsubscribed": 0
}
}
}

Cookie Policy GDPR Email Compliance Acceptable Use Policy Terms of Service Privacy Policy