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.

WARNING: This API is deprecated in favor of our Metrics API.

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
{
  • "stats": [
    • {
      }
    ],
  • "start": "Tue, 14 Feb 2012 00:00:00 UTC",
  • "description": "Optional Description",
  • "end": "Fri, 01 Apr 2012 00:00:00 UTC",
  • "resolution": "month"
}

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
{
  • "stats": [
    • {
      }
    ],
  • "start": "Tue, 14 Feb 2012 00:00:00 UTC",
  • "end": "Fri, 01 Apr 2012 00:00:00 UTC",
  • "description": "Optional Description",
  • "resolution": "month"
}

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
{
  • "end": "Fri, 01 Apr 2012 00:00:00 UTC",
  • "description": "Optional Description",
  • "start": "Tue, 14 Feb 2012 00:00:00 UTC",
  • "stats": [
    • {
      }
    ],
  • "resolution": "month"
}

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
{
  • "end": "Fri, 01 Apr 2012 00:00:00 UTC",
  • "resolution": "month",
  • "start": "Tue, 14 Feb 2012 00:00:00 UTC",
  • "stats": [
    • {
      }
    ],
  • "description": "Optional Description"
}

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": {
      },
    • "gmail.com": {
      }
    }
}

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": {
    • "tablet": {
      },
    • "unknown": {
      },
    • "desktop": {
      },
    • "mobile": {
      }
    }
}

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": {
      },
    • "ru": {
      }
    }
}