Tags

Mailgun lets you tag each outgoing message with a custom value. When you access stats on your messages, they will be aggregated by these tags.

List all tags

get/v3/{domain}/tags

List all tags associated with a domain

SecuritybasicAuth
Request
path Parameters
domain
required
string

The domain name

query Parameters
page
string

The page direction based on the tag parameter; valid choices are (first, last, next, prev)

limit
integer

Limits the number of items returned in a request

tag
string

The tag that marks the end of the current page and the start of the next

prefix
string

List only tags that begin with this prefix

Responses
200

A 200 response

Response Schema: application/json
required
Array of objects
required
object
400

A 400 response

Request samples
Response samples
application/json
{}

Get a tag

get/v3/{domain}/tag

Get a tag associated with a domain

SecuritybasicAuth
Request
path Parameters
domain
required
string

The domain name

query Parameters
tag
required
string

The name of the tag

Responses
200

A 200 response

Response Schema: application/json
tag
required
string
description
required
string
last-seen
string <date-time>
first-seen
string <date-time>
400

A 400 response

Request samples
Response samples
application/json
{
  • "tag": "my-tag-1",
  • "description": "Optional description",
  • "first-seen": "2023-01-02 02:14:27 +0000 UTC",
  • "last-seen": "2023-09-06 18:45:51 +0000 UTC"
}

Update tag

put/v3/{domain}/tag

Update a tag associated with a domain

SecuritybasicAuth
Request
path Parameters
domain
required
string

The domain id

query Parameters
tag
required
string

The name of the tag

description
string

The description of the tag

Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

Request samples
Response samples
application/json
{
  • "message": "Tag updated"
}

Delete tag

delete/v3/{domain}/tag

Delete a tag associated with a domain

SecuritybasicAuth
Request
path Parameters
domain
required
string

The domain name

query Parameters
tag
string

The name of the tag

Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

Request samples
Response samples
application/json
{
  • "message": "Tag deleted"
}

Get aggregate stat types by tag

get/v3/{domain}/tag/stats/aggregates

Returns a list for a given domain for different event types

SecuritybasicAuth
Request
path Parameters
domain
required
string

The domain name

query Parameters
tag
required
string

The name of the tag

type
required
string

The type of aggregate (country, device, provider)

Responses
200

A 200 response

Response Schema: application/json
object
tag
string
object
object
400

A 400 response

Request samples
Response samples
application/json
{
  • "provider": {
    • "aol.com": {
      },
    • "gmail.com": {
      }
    },
  • "tag": "tag1"
}

Get stats by tag

get/v3/{domain}/tag/stats

Retrieve stats by tag

SecuritybasicAuth
Request
path Parameters
domain
required
string

The domain id

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

tag
required
string

The name of the tag

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

provider
string

The provider value; see GET /v3/domains/1/tag/providers for possible values

device
string

The device value; see GET /v3/domains/1/tag/devices for possible values

country
string

The country value; see GET /v3/domains/1/tag/providers for possible values

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

Get tag limits

get/v3/domains/{domain}/limits/tag

Get tag limits by domain

SecuritybasicAuth
Request
path Parameters
domain
required
string

The domain name

Responses
200

A 200 response

Response Schema: application/json
limit
required
integer <int32>
count
required
integer <int32>
id
string
400

A 400 response

Request samples
Response samples
application/json
{
  • "limit": 20000,
  • "count": 1500
}