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

Send an email

Request

Pass the components of the messages such as To, From, Subject, HTML and text parts, attachments, etc. Mailgun will build a MIME representation of the message and send it. Note: In order to send you must provide one of the following parameters: 'text', 'html', 'amp-html' or 'template'

Security

basicAuth

Path

domain_namestringrequired

Domain name used to send the message

Bodymultipart/form-datarequired

fromstringrequired

Email address for the From header. Note: not required if sending with a template that has a pre-set From header, but it will override it if provided.

toArray of stringsrequired

Email address of the recipient(s). Example: "Bob <bob@host.com>". You can use commas to separate multiple recipients

ccArray of strings

Same as To but for Cc

bccArray of strings

Same as To but for Bcc

subjectstringrequired

Message subject. Note: not required if sending with a template that has a pre-set Subject header, but it will override it if provided.

textstring

Body of the message (text version)

htmlstring

Body of the message (HTML version)

amp-htmlstring

AMP part of the message. Please follow Google guidelines to compose and send AMP emails

attachmentArray of strings(binary)

File attachment. You can post multiple attachment values. Important: You must use multipart/form-data encoding for sending attachments

inlineArray of strings(binary)

Attachment with inline disposition. Can be used to send inline images (see example). You can post multiple inline values

templatestring

Name of a template stored via template API to use to render the email body. See Templates for more information

t:versionstring

Render a specific version of the given template instead of the latest version. o:template option must also be provided.

t:textstring

Render template in case of template sending

Value	Description
yes	Render template in the text part of the message

t:variablesstring

A valid JSON-encoded dictionary used as the input for template variable expansion. See Templates for more information

o:tagArray of strings

Tag string. See Tagging for more information

o:dkimstring

Enables/disables DKIM signatures on a per-message basis

Enum Value	Description
yes	Enables DKIM signatures
no	Disable DKIM signatures
true	Enables DKIM signatures
false	Disable DKIM signatures

o:secondary-dkimstring

Specify a second domain key to sign the email with. The value is formatted as signing_domain/selector, e.g. example.com/s1. This tells Mailgun to sign the message with the signing domain example.com using the selector s1. Note: the domain key specified must have been previously created and activated.

o:secondary-dkim-publicstring

Specify an alias of the domain key specified in o:secondary-dkim. Also formatted as public_signing_domain/selector. o:secondary-dkim option must also be provided. Mailgun will sign the message with the provided key of the secondary DKIM, but use the public secondary DKIM name and selector. Note: We will perform a DNS check prior to signing the message to ensure the public keys matches the secondary DKIM.

o:deliverytimestring

Specifies the scheduled delivery time in RFC-2822 format (https://documentation.mailgun.com/docs/mailgun/user-manual/get-started/#date-format). Depending on your plan, you can schedule messages up to 3 or 7 days in advance. If your domain has a custom message_ttl (time-to-live) setting, this value determines the maximum scheduling duration.

o:deliverytime-optimize-periodstring

Toggles Send Time Optimization (STO) on a per-message basis. String should be set to the number of hours in [0-9]+h format, with the minimum being 24h and the maximum being 72h. This value defines the time window in which Mailgun will run the optimization algorithm based on prior engagement data of a given recipient. See Sending a Message with STO for details. Please note that STO is only available on certain plans. See www.mailgun.com/pricing for more info

o:time-zone-localizestring

Toggles Timezone Optimization (TZO) on a per message basis. String should be set to preferred delivery time in HH:mm or hh:mmaa format, where HH:mm is used for 24 hour format without AM/PM and hh:mmaa is used for 12 hour format with AM/PM. See Sending a Message with TZO for details. Please note that TZO is only available on certain plans. See www.mailgun.com/pricing for more info

o:testmodestring

Enables sending in test mode. See Sending in Test Mode

Value	Description
yes	Send in test mode

o:trackingstring

Toggles both click and open tracking on a per-message basis, see Tracking Messages for details.

Enum Value	Description
yes	Enable tracking on a per-message basis
no	Disable tracking on a per-message basis
true	Enable tracking on a per-message basis
false	Disable tracking on a per-message basis
htmlonly	Use if you only want links rewritten in the HTML part of the message

o:tracking-clicksstring

Toggles click tracking on a per-message basis, see Tracking Clicks. Has higher priority than domain-level setting.

Enum Value	Description
yes	Enable tracking on a per-message basis
no	Disable tracking on a per-message basis
true	Enable tracking on a per-message basis
false	Disable tracking on a per-message basis
htmlonly	Use if you only want links rewritten in the HTML part of the message

o:tracking-opensstring

Toggles opens tracking on a per-message basis, see Tracking Opens. Has higher priority than domain-level setting.

Enum Value	Description
yes	Enables opens tracking
no	Disable opens tracking
true	Enables opens tracking
false	Disable opens tracking

o:require-tlsstring

Requires the message only be sent over a TLS connection, see TLS Sending Connection Settings. If a TLS connection can not be established, Mailgun will not deliver the message. If set to false or no, Mailgun will still try and upgrade the connection, but if Mailgun cannot, the message will be delivered over a plaintext SMTP connection. The default is false

Enum Value	Description
yes	Message only be sent over a TLS connection
no	Message do not require to be sent over a TLS connection
true	Message only be sent over a TLS connection
false	Message do not require to be sent over a TLS connection

o:skip-verificationstring

If true, the certificate and hostname of the resolved MX Host will not be verified when trying to establish a TLS connection. If false, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection will not be established. The default is false

Enum Value	Description
yes	Verification skipped
no	Verification active
true	Verification skipped
false	Verification active

o:sending-ipstring

Used to specify an IP Address to send an email that is owned by your account

o:sending-ip-poolstring

If an IP Pool ID is provided, the email will be delivered with an IP that belongs in that pool

o:tracking-pixel-location-topstring

If you send long emails that experience truncation or other rendering issues at the recipient, you can ensure opens are being tracked accurately with placement of the tracking pixel at the top of your emails

Enum Value	Description
yes	Enables tracking
no	Disable tracking
true	Enables tracking
false	Disable tracking
htmlonly	Use if you only want links rewritten in the HTML part of the message

h:X-My-Headerstring

h: prefix followed by a Header/Value pair. For example: h:X-Mailgun-Sending-Ip-Pool=xx.xx.xxx.x.

v:my-varstring

v: prefix followed by an arbitrary name allows to attach a custom JSON data to the message. See Attaching Data to Messages for more information

recipient-variablesstring

A valid JSON-encoded dictionary, where key is a plain recipient address and value is a dictionary with variables that can be referenced in the message body. See Batch Sending for more information

property name*anyadditional property

curl -i -X POST \
  -u <username>:<password> \
  'https://documentation.mailgun.com/_mock/docs/mailgun/api-reference/openapi-final/v3/{domain_name}/messages' \
  -H 'Content-Type: multipart/form-data' \
  -F from=string \
  -F to=string \
  -F cc=string \
  -F bcc=string \
  -F subject=string \
  -F text=string \
  -F html=string \
  -F amp-html=string \
  -F attachment=string \
  -F inline=string \
  -F template=string \
  -F t:version=string \
  -F t:text=yes \
  -F t:variables=string \
  -F o:tag=string \
  -F o:dkim=yes \
  -F o:secondary-dkim=string \
  -F o:secondary-dkim-public=string \
  -F o:deliverytime=string \
  -F o:deliverytime-optimize-period=string \
  -F o:time-zone-localize=string \
  -F o:testmode=yes \
  -F o:tracking=yes \
  -F o:tracking-clicks=yes \
  -F o:tracking-opens=yes \
  -F o:require-tls=yes \
  -F o:skip-verification=yes \
  -F o:sending-ip=string \
  -F o:sending-ip-pool=string \
  -F o:tracking-pixel-location-top=yes \
  -F h:X-My-Header=string \
  -F v:my-var=string \
  -F recipient-variables=string

Responses

A 200 response

Bodyapplication/json

idstringrequired

The unique identifier of the message as defined by RFC-2392.

messagestringrequired

A success message

Response

application/json

{
  "id": "message-id",
  "message": "Queued. Thank you."
}

Send an email in MIME format

Request

Build a MIME string yourself using a MIME library for your programming language and submit it to Mailgun.

Security

basicAuth

Path

domain_namestringrequired

Domain name used to send the message

Bodymultipart/form-datarequired

toArray of stringsrequired

Email address of the recipient(s). Example: "Bob <bob@host.com>". You can use commas to separate multiple recipients

messagestring(binary)required

MIME string of the message. Make sure to use multipart/form-data content type to send this as a file upload

templatestring

Name of a template stored via template API to use to render the email body. See Templates for more information

t:versionstring

Render a specific version of the given template instead of the latest version. o:template option must also be provided.

t:textstring

Render template in the text part of the message in case of template sending

Value	Description
yes	Render template in the text part of the message

t:variablesstring

A valid JSON-encoded dictionary used as the input for template variable expansion. See Templates for more information

o:tagArray of strings

Tag string. See Tagging for more information

o:dkimstring

Enables/disables DKIM signatures on a per-message basis

Enum Value	Description
yes	Enables DKIM signatures
no	Disable DKIM signatures
true	Enables DKIM signatures
false	Disable DKIM signatures

o:secondary-dkimstring

Specify a second domain key to sign the email with. The value is formatted as signing_domain/selector, e.g. example.com/s1. This tells Mailgun to sign the message with the signing domain example.com using the selector s1. Note: the domain key specified must have been previously created and activated.

o:secondary-dkim-publicstring

Specify an alias of the domain key specified in o:secondary-dkim. Also formatted as public_signing_domain/selector. o:secondary-dkim option must also be provided. Mailgun will sign the message with the provided key of the secondary DKIM, but use the public secondary DKIM name and selector. Note: We will perform a DNS check prior to singing the message to ensure the public keys matches the secondary DKIM.

o:deliverytimestring

Specifies the scheduled delivery time in RFC-2822 format (https://mailgun-docs.redoc.ly/docs/mailgun/api-reference/intro/#date-format). Depending on your plan, you can schedule messages up to 3 or 7 days in advance. If your domain has a custom message_ttl (time-to-live) setting, this value determines the maximum scheduling duration.

o:deliverytime-optimize-periodstring

Toggles Send Time Optimization (STO) on a per-message basis. String should be set to the number of hours in [0-9]+h format, with the minimum being 24h and the maximum being 72h. This value defines the time window in which Mailgun will run the optimization algorithm based on prior engagement data of a given recipient. See Sending a Message with STO for details. Please note that STO is only available on certain plans. See www.mailgun.com/pricing for more info

o:time-zone-localizestring

Toggles Timezone Optimization (TZO) on a per message basis. String should be set to preferred delivery time in HH:mm or hh:mmaa format, where HH:mm is used for 24 hour format without AM/PM and hh:mmaa is used for 12 hour format with AM/PM. See Sending a Message with TZO for details. Please note that TZO is only available on certain plans. See www.mailgun.com/pricing for more info

o:testmodestring

Enables sending in test mode. See Sending in Test Mode

Value	Description
yes	Send in test mode

o:trackingstring

Toggles both click and open tracking on a per-message basis, see Tracking Messages for details.

Enum Value	Description
yes	Enable tracking on a per-message basis
no	Disable tracking on a per-message basis
true	Enable tracking on a per-message basis
false	Disable tracking on a per-message basis
htmlonly	Use if you only want links rewritten in the HTML part of the message

o:tracking-clicksstring

Toggles click tracking on a per-message basis, see Tracking Clicks. Has higher priority than domain-level setting.

Enum Value	Description
yes	Enable tracking on a per-message basis
no	Disable tracking on a per-message basis
true	Enable tracking on a per-message basis
false	Disable tracking on a per-message basis
htmlonly	Use if you only want links rewritten in the HTML part of the message

o:tracking-opensstring

Toggles opens tracking on a per-message basis, see Tracking Opens. Has higher priority than domain-level setting.

Enum Value	Description
yes	Enables opens tracking
no	Disable opens tracking
true	Enables opens tracking
false	Disable opens tracking

o:require-tlsstring

Requires the message only be sent over a TLS connection, see TLS Sending Connection Settings. If a TLS connection can not be established, Mailgun will not deliver the message. If set to false or no, Mailgun will still try and upgrade the connection, but if Mailgun cannot, the message will be delivered over a plaintext SMTP connection. The default is false

Enum Value	Description
yes	Message only be sent over a TLS connection
no	Message do not require to be sent over a TLS connection
true	Message only be sent over a TLS connection
false	Message do not require to be sent over a TLS connection

o:skip-verificationstring

If true, the certificate and hostname of the resolved MX Host will not be verified when trying to establish a TLS connection. If false, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection will not be established. The default is false

Enum Value	Description
yes	Verification skipped
no	Verification active
true	Verification skipped
false	Verification active

o:sending-ipstring

Used to specify an IP Address to send an email that is owned by your account

o:sending-ip-poolstring

If an IP Pool ID is provided, the email will be delivered with an IP that belongs in that pool

o:tracking-pixel-location-topstring

If you send long emails that experience truncation or other rendering issues at the recipient, you can ensure opens are being tracked accurately with placement of the tracking pixel at the top of your emails

Enum Value	Description
yes	Enables tracking
no	Disable tracking
true	Enables tracking
false	Disable tracking
htmlonly	Use if you only want links rewritten in the HTML part of the message

h:X-My-Headerstring

h: prefix followed by a Header/Value pair. For example: h:X-Mailgun-Sending-Ip-Pool=xx.xx.xxx.x.

v:my-varstring

v: prefix followed by an arbitrary name allows to attach a custom JSON data to the message. See Attaching Data to Messages for more information

recipient-variablesstring

A valid JSON-encoded dictionary, where key is a plain recipient address and value is a dictionary with variables that can be referenced in the message body. See Batch Sending for more information

property name*anyadditional property

curl -i -X POST \
  -u <username>:<password> \
  'https://documentation.mailgun.com/_mock/docs/mailgun/api-reference/openapi-final/v3/{domain_name}/messages.mime' \
  -H 'Content-Type: multipart/form-data' \
  -F to=string \
  -F message=string \
  -F template=string \
  -F t:version=string \
  -F t:text=yes \
  -F t:variables=string \
  -F o:tag=string \
  -F o:dkim=yes \
  -F o:secondary-dkim=string \
  -F o:secondary-dkim-public=string \
  -F o:deliverytime=string \
  -F o:deliverytime-optimize-period=string \
  -F o:time-zone-localize=string \
  -F o:testmode=yes \
  -F o:tracking=yes \
  -F o:tracking-clicks=yes \
  -F o:tracking-opens=yes \
  -F o:require-tls=yes \
  -F o:skip-verification=yes \
  -F o:sending-ip=string \
  -F o:sending-ip-pool=string \
  -F o:tracking-pixel-location-top=yes \
  -F h:X-My-Header=string \
  -F v:my-var=string \
  -F recipient-variables=string

Responses

A 200 response

Bodyapplication/json

idstringrequired

The unique identifier of the message as defined by RFC-2392.

messagestringrequired

A success message

Response

application/json

{
  "id": "message-id",
  "message": "Queued. Thank you."
}

Retrieve a stored email

Request

Event(s) created from sending an email with Mailgun will contain a storage.key to use to retrieve the email.

Security

basicAuth

Path

domain_namestringrequired

Domain name that was used to send the email

storage_keystringrequired

Storage key from the emails associated events

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

Responses

A 200 response

Bodyapplication/json

Content-Transfer-Encodingstringrequired

The content transfer encoding if enabled

Content-Typestringrequired

The content type sent with the message with a possible boundary

Fromstringrequired

The full 'From' email address entry of the email

Message-Idstringrequired

The unique identifier of the message as defined by RFC-2392

Mime-Versionstringrequired

The MIME version of the email

Subjectstringrequired

Subject of the email

Tostringrequired

The full 'To' email address entries

X-Mailgun-Tagstringrequired

The raw tags of the message if provided

senderstringrequired

Just the email address from the provided 'From'' field

recipientsstringrequired

A list of email addresses from the 'To'' field

body-htmlstringrequired

The full HTML body of the full message

body-plainstringrequired

The plain text body of the full message

stripped-htmlstringrequired

Only the body of the email in HTML

stripped-textstringrequired

Only the body of the email in plain text

stripped-signaturestringrequired

The signature stripped from the body

message-headersArray of stringsrequired

The full list of headers of the MIME upon send

X-Mailgun-Template-Namestringrequired

The name of the template if one was used

X-Mailgun-Template-Variablesstringrequired

The variables used in the template if one was used

Response

application/json

{
  "Content-Transfer-Encoding": "7bit",
  "Content-Type": "multipart/form-data; boundary=----SomeFormBoundaryABC123",
  "From": "foo.bar@my-domain.com",
  "Message-Id": "<xxxxxxxxxxxxx.111111111111111@my-domain.com>",
  "Mime-Version": "1.0",
  "Subject": "\"Mailgun is awesome\"",
  "To": "Cool Bar <cool.barr@cool.com>, bar.baz@gmail.com",
  "X-Mailgun-Tag": "Earth",
  "sender": "foo.bar@my-domain.com",
  "recipients": "cool.barr@cool.com, bar.baz@gmail.com",
  "body-html": "<html>This is some html</html>",
  "body-plain": "This is some html",
  "stripped-html": "<html>This is some html</html>",
  "stripped-text": "This is some html",
  "stripped-signature": "the signature block stripped from the plain text message (if found)",
  "message-headers": [
    [ … ],
    [ … ],
    [ … ],
    [ … ],
    [ … ],
    [ … ],
    [ … ],
    [ … ]
  ],
  "X-Mailgun-Template-Name": "my-awesome-template",
  "X-Mailgun-Template-Variables": "{\"name\":\"Foo\",\"phrase\":\"Bar\"}"
}

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

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

Send an email

Request

Responses

Was this helpful?

Send an email in MIME format

Request

Responses

Was this helpful?

Retrieve a stored email

Request

Responses

Was this helpful?

Domains

Domain Keys

Domain Tracking

DKIM Security

Webhooks

Metrics

Logs

Tags New

Stats

Tags

Events

Unsubscribe

Complaints

Bounces

Allowlist

Routes

Mailing Lists

Templates

IP Pools

Dynamic IP Pools

IPs

IP Address Warmup

Subaccounts

Custom Message Limit

Account Management

Keys

Credentials

IP Allowlist

Users