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.

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)

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

template
string

Name of a template stored via template API. See Templates for more information

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

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

t:version
string

Use this parameter to send a message to specific version of a template

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

Desired time of delivery. See Date Format. Note: Messages can be scheduled for a maximum of 3 or 7 days in the future based on your plan

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 tracking on a per-message basis, see Tracking Messages for details. Pass yes or no, true or false

o:tracking-clicks
string

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

h:X-My-Header
string

h: prefix followed by an arbitrary value allows to append a custom MIME header to the message (X-My-Header in this case). For example, h:Reply-To to specify Reply-To address, h:X-Mailgun-Sending-Ip-Pool=123 to deliver the message with an IP address that is part of the IP pool identified by ID 123, or h:X-Mailgun-Sending-Ip-Pool=xx.xx.xxx.x to deliver the message with a specified IP address

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 will not be verified when trying to establish a TLS connection and Mailgun will accept any certificate during delivery. 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

Responses
200

A 200 response

Response Schema: application/json
id
required
string
message
required
string
Request samples
Response samples
application/json
{
  • "message": "Queued. Thank you.",
  • "id": "message-id"
}

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: application/json
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

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

Tag string. See Tagging for more information

o:tracking-clicks
string

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

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

h:X-My-Header
string

h: prefix followed by an arbitrary value allows to append a custom MIME header to the message (X-My-Header in this case). For example, h:Reply-To to specify Reply-To address, h:X-Mailgun-Sending-Ip-Pool=123 to deliver the message with an IP address that is part of the IP pool identified by ID 123, or h:X-Mailgun-Sending-Ip-Pool=xx.xx.xxx.x to deliver the message with a specified IP address

o:tracking
string

Toggles tracking on a per-message basis, see Tracking Messages for details. Pass yes or no, true or false

o:dkim
string

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

o:deliverytime
string

Desired time of delivery. See Date Format. Note: Messages can be scheduled for a maximum of 3 or 7 days in the future based on your plan

o:testmode
string

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

Responses
200

A 200 response

Response Schema: application/json
id
required
string
message
required
string
Request samples
application/json
{
  • "to": "string",
  • "message": "string"
}
Response samples
application/json
{
  • "id": "message-id",
  • "message": "Queued. Thank you."
}

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"
}