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

200
400

application/json

{"paging": {"first": "https://api.mailgun.net/v3/example.com/tags?limit=1000&page=first&tag=",
"next": "https://api.mailgun.net/v3/example.com/tags?limit=1000&page=next&tag=",
"last": "https://api.mailgun.net/v3/example.com/tags?limit=1000&page=last&tag=",
"previous": "https://api.mailgun.net/v3/example.com/tags?limit=1000&page=prev&tag="
},
"items": [{"description": "Optional description",
"first-seen": "2023-01-02 02:14:27 +0000 UTC",
"last-seen": "2023-09-06 18:45:51 +0000 UTC",
"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",
"tag": "my-tag-2"
}
]
}

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

200
400

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

200
400

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

200
400

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

200
400

application/json

{"provider": {"aol.com": {"opened": 1,
"unique_clicked": 1,
"unsubscribed": 0,
"accepted": 0,
"clicked": 1
},
"gmail.com": {"unsubscribed": 0,
"accepted": 0,
"clicked": 2,
"opened": 1,
"unique_clicked": 1
}
},
"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

200
400

application/json

{"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"
}
],
"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

200
400

application/json

{"limit": 20000,
"count": 1500
}