Messages

Send email two ways via our REST API:

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

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

Send an email

post/v3/{domain_name}/messages

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'

SecuritybasicAuth
Request
path Parameters
domain_name
required
string

Domain name used to send the message

Request Body schema: multipart/form-data
required
from
required
string

Email address for From header

to
required
string

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

subject
required
string

Message subject

html
required
string

Body of the message (HTML version)

t:version
string

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

cc
string

Same as To but for Cc

bcc
string

Same as To but for Bcc

text
string

Body of the message (text version)

amp-html
string

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

attachment
string

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

inline
string

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

template
string

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

o:skip-verification
string

If set to true or yes, the certificate and hostname of the resolved MX Host will not be verified when trying to establish a TLS connection. If set to false or no, 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

t:text
string

Pass yes if you want to have a rendered template in the text part of the message in case of template sending

t:variables
string

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

o:tag
string

Tag string. See Tagging for more information

o:dkim
string

Enables/disables DKIM signatures on a per-message basis. Pass yes or no, true or false

o:secondary-dkim
string

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-public
string

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:deliverytime
string

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-period
string

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-localize
string

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:testmode
string

Enables sending in test mode. Pass yes if needed. See Sending in Test Mode

o:tracking
string

Toggles both click and open tracking on a per-message basis, see Tracking Messages for details. Pass yes or no, true or false, or htmlonly if you only want links rewritten in the HTML part of the message

o:tracking-clicks
string

Toggles click tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes or no, true or false, or htmlonly if you only want links rewritten in the HTML part of the message

o:tracking-opens
string

Toggles opens tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes or no, true or false

o:require-tls
string

If set to true or yes this requires the message only be sent over a TLS connection. 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

v:my-var
string

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

o:sending-ip-pool
string

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

o:sending-ip
string

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

o:tracking-pixel-location-top
string

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

recipient-variables
string

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

h:X-My-Header
string

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

Responses
200

A 200 response

Response Schema: application/json
id
required
string
message
required
string
400

A 400 response

401

A 401 response

429

A 429 response

500

A 500 response

Request samples 
Response samples 
application/json
{
  • "id": "message-id",
  • "message": "Queued. Thank you."
}
Send an email in MIME format
post/v3/{domain_name}/messages.mime
Build a MIME string yourself using a MIME library for your programming language and submit it to Mailgun.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name used to send the message


 
Request Body schema: multipart/form-data
required
to
required
string
Email address of the recipient(s).  Example: "Bob <bob@host.com>". You can use commas to separate multiple recipients


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


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


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


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


 
t:text
string
Pass yes if you want to have a rendered template in the text part of the message in case of template sending


 
o:tracking
string
Toggles both click and open tracking on a per-message basis, see Tracking Messages for details.  Pass yes or no, true or false, or htmlonly if you only want links rewritten in the HTML part of the message


 
o:tag
string
Tag string.  See Tagging for more information


 
o:dkim
string
Enables/disables DKIM signatures on a per-message basis.  Pass yes or no, true or false


 
o:secondary-dkim
string
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-public
string
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:deliverytime
string
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-period
string
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-localize
string
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:testmode
string
Enables sending in test mode. Pass yes if needed.  See Sending in Test Mode


 
o:sending-ip
string
Used to specify an IP Address to send an email that is owned by your account


 
o:tracking-clicks
string
Toggles click tracking on a per-message basis.  Has higher priority than domain-level setting.  Pass yes or no, true or false, or htmlonly if you only want links rewritten in the HTML part of the message


 
o:tracking-opens
string
Toggles opens tracking on a per-message basis.  Has higher priority than domain-level setting.  Pass yes or no, true or false


 
o:require-tls
string
If set to true or yes this requires the message only be sent over a TLS connection.  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


 
o:skip-verification
string
If set to true or yes, the certificate and hostname of the resolved MX Host will not be verified when trying to establish a TLS connection. If set to false or no, 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


 
v:my-var
string
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


 
o:sending-ip-pool
string
If an IP Pool ID is provided, the email will be delivered with an IP that belongs in that pool


 
o:tracking-pixel-location-top
string
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


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


 
recipient-variables
string
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


 
Responses 
200
A 200 response


Response Schema: application/json
id
required
string
 
message
required
string
 
400
A 400 response


401
A 401 response


429
A 429 response


500
A 500 response


Request samples 
Response samples 
application/json
{
  • "id": "message-id",
  • "message": "Queued. Thank you."
}
Retrieve a stored email
get/v3/domains/{domain_name}/messages/{storage_key}
Event(s) created from sending an email with Mailgun will contain a storage.key to use to retrieve the email.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name that was used to send the email


 
storage_key
required
string
Storage key from the emails associated events


 
Responses 
200
A 200 response


Response Schema: application/json
Content-Transfer-Encoding
required
string
 
Content-Type
required
string
 
From
required
string
 
Message-Id
required
string
 
Mime-Version
required
string
 
Subject
required
string
 
To
required
string
 
X-Mailgun-Tag
required
string
 
sender
required
string
 
recipients
required
string
 
from
required
string
 
subject
required
string
 
body-html
required
string
 
body-plain
required
string
 
stripped-html
required
string
 
stripped-text
required
string
 
stripped-signature
required
string
 
message-headers
required
Array of strings
 
X-Mailgun-Template-Name
required
string
 
X-Mailgun-Template-Variables
required
string
 
400
A 400 response


404
A 404 response


Request samples 
Response samples 
application/json
{
  • "stripped-html": "<html>This is some html</html>",
  • "To": "cool.barr@cool.com, bar.baz@gmail.com",
  • "Mime-Version": "1.0",
  • "From": "foo.bar@my-domain.com",
  • "body-plain": "This is some html",
  • "X-Mailgun-Template-Variables": "{\"name\":\"Foo\",\"phrase\":\"Bar\"}",
  • "stripped-text": "This is some html",
  • "from": "foo.bar@my-domain.com",
  • "message-headers": [
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ]
    ],
  • "Subject": "\"Mailgun is awesome\"",
  • "Message-Id": "<xxxxxxxxxxxxx.111111111111111@my-domain.com>",
  • "Content-Transfer-Encoding": "7bit",
  • "X-Mailgun-Tag": "earth",
  • "Content-Type": "text/html; charset=ascii",
  • "subject": "\"Mailgun is awesome\"",
  • "sender": "foo.bar@my-domain.com",
  • "recipients": "cool.barr@cool.com, bar.baz@gmail.com",
  • "body-html": "<html>This is some html</html>",
  • "X-Mailgun-Template-Name": "my-awesome-template"
}
Get messages queue status
get/v3/domains/{name}/sending_queues
Provides default and scheduled message queue information.


SecuritybasicAuth 
Request 
path Parameters
name
required
string
The name of the domain you want get sending queues from


 
Responses 
200
A 200 response


Response Schema: application/json
required
object
 
required
object
 
401
A 401 response


404
A 404 response


Request samples 
Response samples 
application/json
{
  • "regular": {
    • "is_disabled": true,
    • "disabled": {
      }
    }
}
Delete scheduled and undelivered mail
delete/v3/{domain_name}/envelopes
Deletes all scheduled and undelivered mail from the domain queue.  This endpoint must be called on the storage API host and in the domain's region.  e.g. https://storage-us-east4.api.mailgun.net/v3/example.com/envelopes


The storage hosts are storage-us-east4.api.mailgun.net, storage-us-west1.api.mailgun.net, and storage-europe-west1.api.mailgun.net.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
The name of the domain you want to delete envelope from


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
401
A 401 response


404
A 404 response


Request samples 
Response samples 
application/json
{
  • "message": "done"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.