Mailgun API (3.0.0)
Mailgun API defined by OpenAPI Specification (OAS) 3.1.0
https://api.mailgun.net/
https://api.eu.mailgun.net/
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'
Email address of the From
header. Can include a friendly name using the format "Friendly Name <email@domain.com>"
. Note: not required if sending with a template that has a pre-set From header, but will override the template's From header if provided.
Email address of the recipient(s). Supports friendly name format. Example: "Bob <bob@host.com>"
. Use commas to separate multiple recipients. Duplicate addresses are automatically ignored.
Message subject. Note: not required if sending with a template that has a pre-set Subject header, but it will override it if provided.
AMP part of the message. Please follow Google guidelines to compose and send AMP emails
File attachment. You can post multiple attachment
values. Important: You must use multipart/form-data
encoding for sending attachments
Attachment with inline
disposition. Can be used to send inline images (see example). You can post multiple inline
values
Name of a template stored via the Templates API to use to render the email body. See Templates for more information
Render a specific version of the given template instead of the latest version. template
option must also be provided.
Generates a plain text version of the template alongside the HTML version when sending templated emails. When set to 'yes', instructs Mailgun to create a text/plain MIME part based on the template content, ensuring compatibility with email clients that don't support HTML or have HTML rendering disabled. This improves email deliverability and accessibility by providing a fallback text version in multipart emails.
Value | Description |
---|---|
yes | Render template in the text part of the message |
A valid JSON-encoded dictionary used as the input for template variable expansion. See Templates for more information
Tag string. See Tagging for more information
Enables or disables DKIM signatures on a per-message basis. Overrides the domain-level DKIM setting for this specific message.
Enum Value | Description |
---|---|
yes | Enables DKIM signatures |
no | Disable DKIM signatures |
true | Enables DKIM signatures |
false | Disable DKIM signatures |
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.
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.
Specifies the scheduled delivery time in RFC-2822 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. Example: 'Fri, 14 Oct 2011 12:00:00 +0000'
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
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
Enables sending in test mode. Messages are processed normally but not actually delivered to recipients. Useful for testing without sending real emails. See Sending in Test Mode
Value | Description |
---|---|
yes | Send in test mode |
Toggles both click and open tracking on a per-message basis
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 |
Toggles click tracking on a per-message basis, see Tracking Clicks. This overrides the domain-level click tracking 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 |
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 |
When set to 'yes', requires the message to be sent only over a TLS connection to the Email Service Provider. If TLS cannot be established, the message will not be delivered. When set to 'no' (default), Mailgun attempts TLS but falls back to plaintext SMTP if needed.
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 |
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 |
If an IP Pool ID is provided, the email will be delivered with an IP that belongs in that pool
Places the tracking pixel at the top of emails instead of the bottom. Useful for long emails that may be truncated or have rendering issues, ensuring open tracking works accurately.
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 |
Sends a copy of successfully delivered messages to the specified URL via HTTP POST. The request uses Content-Type: application/mime and contains the exact message the recipient's SMTP server received. NOTE: These are accounted for and billed as delivered messages
Removes specified X-Mailgun headers from the delivered message. Provide header names separated by commas (e.g., 'X-Mailgun-Variables,X-Mailgun-Tag') or use 'all' to remove all X-Mailgun headers.Note: X-Mailgun-Sid header is currently used to process complains received via feedback loops.
Adds custom headers to the email. Use 'h:' prefix followed by header name and value. Example: 'h:X-Custom-Header=my-value'
Attaches custom data to the message using the 'v:' prefix followed by a variable name. When sending with templates, provides values for template variable substitution (overridden by 't:variables' if both are provided). When not using templates, treated as metadata and included in events/webhooks. Variables are visible in the delivered email's X-Mailgun-Variables header. Example: 'v:user-id=123'.
A JSON-encoded dictionary for batch sending with personalized variables per recipient. Each key is a recipient email address, each value is a dictionary of variables for that recipient. Variables can be referenced in the message using %recipient.variablename%. Example: '{"alice@example.com": {"name":"Alice", "id":1}, "bob@example.com": {"name":"Bob", "id":2}}'. Maximum 1,000 recipients per batch. See Batch Sending for more information
- US Mailgun
https://api.mailgun.net/v3/{domain_name}/messages
- EU Mailgun
https://api.eu.mailgun.net/v3/{domain_name}/messages
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://api.mailgun.net/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 o:archive-to=string \
-F o:suppress-headers=string \
-F h:X-My-Header=string \
-F v:my-var=string \
-F recipient-variables=string
{ "id": "message-id", "message": "Queued. Thank you." }
Email address of the recipient(s). Supports friendly name format. Example: "Bob <bob@host.com>"
. Use commas to separate multiple recipients. Duplicate addresses are automatically ignored.
MIME string of the message. Make sure to use multipart/form-data
content type to send this as a file upload
Name of a template stored via template API to use to render the email body. See Templates for more information
Render a specific version of the given template instead of the latest version. template
option must also be provided.
Generates a plain text version of the template alongside the HTML version when sending templated emails. When set to 'yes', instructs Mailgun to create a text/plain MIME part based on the template content, ensuring compatibility with email clients that don't support HTML or have HTML rendering disabled. This improves email deliverability and accessibility by providing a fallback text version in multipart emails.
Value | Description |
---|---|
yes | Render template in the text part of the message |
A valid JSON-encoded dictionary used as the input for template variable expansion. See Templates for more information
Tag string. See Tags for more information
Enables or disables DKIM signatures on a per-message basis. Overrides the domain-level DKIM setting for this specific message.
Enum Value | Description |
---|---|
yes | Enables DKIM signatures |
no | Disable DKIM signatures |
true | Enables DKIM signatures |
false | Disable DKIM signatures |
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.
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.
Specifies the scheduled delivery time in RFC-2822 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. Example: 'Fri, 14 Oct 2011 12:00:00 +0000'
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
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
Enables sending in test mode. Messages are processed normally but not actually delivered to recipients. Useful for testing without sending real emails. See Sending in Test Mode
Value | Description |
---|---|
yes | Send in test mode |
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 |
Toggles click tracking on a per-message basis, see Tracking Clicks. This overrides the domain-level click tracking 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 |
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 |
When set to 'yes', requires the message to be sent only over a TLS connection. If TLS cannot be established, the message will not be delivered. When set to 'no' (default), Mailgun attempts TLS but falls back to plaintext SMTP if needed.
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 |
When set to 'true', skips certificate and hostname verification for TLS connections. When 'false' (default), Mailgun verifies certificates and hostnames - if verification fails, TLS connection is not established.
Enum Value | Description |
---|---|
yes | Verification skipped |
no | Verification active |
true | Verification skipped |
false | Verification active |
If an IP Pool ID is provided, the email will be delivered with an IP that belongs in that pool
Places the tracking pixel at the top of emails instead of the bottom. Useful for long emails that may be truncated or have rendering issues, ensuring open tracking works accurately.
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 |
Sends a copy of successfully delivered messages to the specified URL via HTTP POST. The request uses Content-Type: application/mime and contains the exact message the recipient's SMTP server received. NOTE: These are accounted for and billed as delivered messages
Removes specified X-Mailgun headers from the delivered message. Provide header names separated by commas (e.g., 'X-Mailgun-Variables,X-Mailgun-Tag') or use 'all' to remove all X-Mailgun headers.Note: X-Mailgun-Sid header is currently used to process complains received via feedback loops.
Adds custom headers to the email. Use 'h:' prefix followed by header name and value. Example: 'h:X-Custom-Header=my-value'
Attaches custom data to the message using the 'v:' prefix followed by a variable name. When sending with templates, provides values for template variable substitution (overridden by 't:variables' if both are provided). When not using templates, treated as metadata and included in events/webhooks. Variables are visible in the delivered email's X-Mailgun-Variables header. Example: 'v:user-id=123'.
A JSON-encoded dictionary for batch sending with personalized variables per recipient. Each key is a recipient email address, each value is a dictionary of variables for that recipient. Variables can be referenced in the message using %recipient.variablename%. Example: '{"alice@example.com": {"name":"Alice", "id":1}, "bob@example.com": {"name":"Bob", "id":2}}'. Maximum 1,000 recipients per batch. See Batch Sending for more information.
- US Mailgun
https://api.mailgun.net/v3/{domain_name}/messages.mime
- EU Mailgun
https://api.eu.mailgun.net/v3/{domain_name}/messages.mime
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://api.mailgun.net/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 o:archive-to=string \
-F o:suppress-headers=string \
-F h:X-My-Header=string \
-F v:my-var=string \
-F recipient-variables=string
{ "id": "message-id", "message": "Queued. Thank you." }
- US Mailgun
https://api.mailgun.net/v3/domains/{domain_name}/messages/{storage_key}
- EU Mailgun
https://api.eu.mailgun.net/v3/domains/{domain_name}/messages/{storage_key}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://api.mailgun.net/v3/domains/{domain_name}/messages/{storage_key}'
{ "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\"}" }
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.
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.
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.
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.
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