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)

cc
string

Same as To but for Cc

bcc
string

Same as To but for Bcc

text
string

Body of the message (text version)

t:variables
string

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

amp-html
string

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

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

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

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.

template
string

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

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

attachment
string

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

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

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

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

inline
string

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

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
{
  • "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: 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


 
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:dkim
string
Enables/disables DKIM signatures on a per-message basis.  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


 
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: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: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
 
400
A 400 response


401
A 401 response


429
A 429 response


500
A 500 response


Request samples 
Response samples 
application/json
{
  • "message": "Queued. Thank you.",
  • "id": "message-id"
}
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
 
404
A 404 response


Request samples 
Response samples 
application/json
{
  • "content_transfer_encoding": "7bit",
  • "recipients": "cool.barr@cool.com, bar.baz@gmail.com",
  • "X-Mailgun-Tag": "earth",
  • "From": "foo.bar@my-domain.com",
  • "Mime-Version": "1.0",
  • "Body-Plain": "This is some html",
  • "content_type": "text/html; charset=ascii",
  • "Subject": "\"Mailgun is awesome\"",
  • "sender": "foo.bar@my-domain.com",
  • "subject": "\"Mailgun is awesome\"",
  • "stripped-html": "<html>This is some html</html>",
  • "Message-Id": "<xxxxxxxxxxxxx.111111111111111@my-domain.com>",
  • "To": "cool.barr@cool.com, bar.baz@gmail.com",
  • "from": "foo.bar@my-domain.com",
  • "stripped-text": "This is some html",
  • "Body-HTML": "<html>This is some html</html>",
  • "Message-Headers": [
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ],
    • [
      ]
    ]
}
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.