Get templates

Messages

Send email two ways via our REST API:

Send emails using MIME format using a MIME building library
Submit the individual parts (Text, html, attachments, etc.)

Reminder: You can also send email via SMTP with Mailgun. Please reference the user manual.

Operations

Domains

Domains API manages domains, domain keys and DNS verification.

Operations

Domain Keys

An authentication standard used to prevent email spoofing.

Operations

Domain Tracking

Mailgun offers tracking for clicks, unsubscribes, and opens, with optional HTTPS protocol support on tracking URLs. To enable HTTPS, Mailgun uses Let’s Encrypt with HTTP-01 challenges through your existing tracking CNAME record to issue a TLS certificate. This setup also includes support for HTTP Strict Transport Security (HSTS) for enhanced security.

Operations

DKIM Security

Automatic Sender Security DKIM Key APIs. To enable this feature please see 'Update a domain' API docs.

Operations

Webhooks

Webhooks API manages domain's webhooks. You can create, access and delete webhooks programmatically.

Operations

Metrics

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

Operations

Logs

Mailgun keeps track of every inbound and outbound message event and stores this log data. This data can be queried and filtered to provide insights into the health of your email infrastructure.

Operations

Tags New

Mailgun allows you to tag your email with unique identifiers. Tags are visible via our analytics tags API endpoint.

Operations

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.

Operations

Events

Mailgun keeps track of every inbound and outbound message event and stores this data for at least 3 days.

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

Operations

Unsubscribe

Unsubscribe list stores email addresses of recipients who unsubscribed from your mailings by clicking a Mailgun generated unsubscribe link.

Operations

Complaints

Email addresses of recipients who marked your messages as a spam (for ESPs that support FBL).

Operations

Bounces

Bounces - Bounce list stores events of delivery failures due to permanent recipient mailbox errors such as non-existent mailbox. Soft bounces (for example, mailbox is full) and other failures (for example, ESP rejects an email because it thinks it is spam) are not added to the list.

Operations

Allowlist

The allowlist API provides the ability to allowlist specific addresses from being added to bounce list. You can allowlist by domain name (i.e example.com) or by specific address (i.e. alice@example.com). Mailgun doesn’t add an address to bounce list if the address is allowlisted. This API is very useful if you test against your private services and don’t want to constantly clean up bounce lists

Operations

Routes

Define a list of routes to handle incoming emails. When a message matches a route expression, Mailgun can forward it on to your application via HTTP or another email address, or store the message temporarily (3 days) for subsequent retrieval.

Operations

Mailing Lists

Programatically create mailing lists.

Operations

Templates

This API allows you to store predefined templates and use them to send messages using the Sending API.

Operations

Get templates

Request

Returns a list of templates for the domain.

Security

basicAuth

Path

domain_namestringrequired

Domain name to fetch the templates for.

Query

pagestring

Name of the page to retrieve. Value can be first, last, next, or previous. Defaults to first.

Enum Value	Description
first	Get the first list's page
last	Get the last list's page
next	Get the next list's page
previous	Get the previous list's page

limitinteger

Number of templates to retrieve. Default and max limit is 100.

pstring

Pivot used to retrieve the next page of templates.

curl -i -X GET \
  -u <username>:<password> \
  'https://documentation.mailgun.com/_mock/docs/mailgun/api-reference/openapi-final/v3/{domain_name}/templates?page=first&limit=0&p=string'

Responses

A 200 response

Bodyapplication/json

itemsArray of objects or null(github.com-mailgun-temple-model-Template)required

List of items

items[].namestringrequired

Name of the template

items[].descriptionstring

Description of the template

items[].createdAtstringread-only

Creation date in RFC822 format

items[].createdBystring

Indicate who created the template

items[].idstringread-only

Template ID

items[].versionnull or github.com-mailgun-temple-model-Version (object)read-only

Active version information

Any of:

Active version information

nullread-only

Active version information

items[].versionsArray of objects or null(github.com-mailgun-temple-model-Version)read-only

List of template's versions

pagingobjectrequired

Pagination details

paging.previousstringrequired

Previous page URL

paging.firststringrequired

First page URL

paging.nextstringrequired

Next page URL

paging.laststringrequired

Last page URL

Response

application/json

{
  "items": [
    { … },
    { … }
  ],
  "paging": {
    "previous": "https://api.mailgun.net/v3/{domain}/templates?page=prev&p=template.0&limit=10",
    "first": "https://api.mailgun.net/v3/{domain}/templates?limit=10",
    "next": "https://api.mailgun.net/v3/{domain}/templates?page=next&p=template.2&limit=10",
    "last": "https://api.mailgun.net/v3/{domain}/templates?page=last&limit=10"
  }
}

Create a template

Request

Store a new template, including its name, description and (optionally) the template content. If the template content is provided, a new version is automatically created and becomes the active version.

Security

basicAuth

Path

domain_namestringrequired

Domain name the template is associated with.

Bodymultipart/form-datarequired

namestringrequired

Name of the template being stored. Supports utf-8 characters and name will be down cased.

descriptionstring

Description of the template being stored

createdBystring

Optional metadata field api user can indicate who created the template.

templatestring

Content of the template.

tagstring

Initial tag of the created version. If the template parameter is provided and the tag is missing, the default value initial is used.

commentstring

Version comment. This is valid only if a new version is being created. (template parameter is provided.)

headersstring

Key value JSON object of headers to be stored with the template. Where key is the header name and value is the header value. The header names From, Subject, and Reply-To are the only ones currently supported. These headers will be inserted into the MIME at the time we attempt delivery.

Headers set at the message level will override headers set on the template. e.g. Setting the From header at the time of sending will override the From header saved on the template. Additionally, headers generated by templates are not reflected on the accepted event as they are not prepended to the message until the message is prepped for delivery. if a From header is not provided either in the message or template, we will default to postmaster@your-sending-domain.tld

curl -i -X POST \
  -u <username>:<password> \
  'https://documentation.mailgun.com/_mock/docs/mailgun/api-reference/openapi-final/v3/{domain_name}/templates' \
  -H 'Content-Type: multipart/form-data' \
  -F name=string \
  -F description=string \
  -F createdBy=string \
  -F template=string \
  -F tag=string \
  -F comment=string \
  -F headers=string

Responses

A 200 response

Bodyapplication/json

messagestringrequired

Response message

templatenull or github.com-mailgun-temple-model-Template (object)required

Template details

Any of:

Template details

null

Template details

Response

application/json

{
  "message": "template has been stored",
  "template": {
    "name": "template_name",
    "description": "This is the description of the template",
    "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC",
    "createdBy": "user-supplied-value",
    "id": "46565d87-68b6-4edb-8b3c-34554af4bb77",
    "version": { … }
  }
}

Delete all templates

Request

Delete all templates and their versions for the domain.

Security

basicAuth

Path

domain_namestringrequired

Domain name the template is associated with.

curl -i -X DELETE \
  -u <username>:<password> \
  'https://documentation.mailgun.com/_mock/docs/mailgun/api-reference/openapi-final/v3/{domain_name}/templates'

Responses

A 200 response

Bodyapplication/json

messagestringrequired

Response message

Response

application/json

{
  "message": "templates have been deleted"
}

IP Pools

IP Pools allow you to group your dedicated IPs into customized "pools" to help manage your sending reputation for different mail sending streams.

Operations

Dynamic IP Pools

Dynamic IP Pools allow you to group your dedicated IPs into customized "pools" based on sender reputation. Health checks are performed on domains and assigned to the appropriate Dynamic Pool.

Operations

IPs

The IP API endpoint allows you to access information regarding the IPs allocated to your Mailgun account that are used for outbound sending.

Operations

IP Address Warmup

Operations

Subaccounts

Mailgun supports the creation, modification, and deletion of subaccounts. A subaccount is a child account of a parent account. The parent account can have multiple subaccounts. The subaccounts are created and managed by the parent account.

Operations

Custom Message Limit

The custom message limit imposes a hard limit on how many messages your account can send during a calendar month.

Operations

Account Management

Perform account-level CRUD operations.

Operations

Keys

The Keys API lets you view and manage api keys.

Operations

Credentials

The Credentials API lets you view and manage SMTP credentials.

Operations

IP Allowlist

The IP Allowlist API lets you view and manage allowlisted IP addresses to which api key and SMTP credential usage is restricted.

Operations

Users

Mailgun API supports viewing user entities.

Operations

Mailgun API (0.0.0)

Messages

Domains

Domain Keys

Domain Tracking

DKIM Security

Webhooks

Metrics

Logs

Tags New

Stats

Tags

Events

Unsubscribe

Complaints

Bounces

Allowlist

Routes

Mailing Lists

Templates

Get templates

Request

Responses

Was this helpful?

Create a template

Request

Responses

Was this helpful?

Delete all templates

Request

Responses

Was this helpful?

IP Pools

Dynamic IP Pools

IPs

IP Address Warmup

Subaccounts

Custom Message Limit

Account Management

Keys

Credentials

IP Allowlist

Users