Mailgun-Compatible MIME Messages API

Table of Contents
Overview
Send a MIME Message
Differences from Mailgun

GreenArrow CloudMTA

This feature is only available on GreenArrow CloudMTA.

Overview

The /messages.mime endpoint lets software that was written for Mailgun send a MIME message that it builds itself. GreenArrow adds its headers to the front of the message and submits it to the HTTP Submission API. In a batch, it removes the document’s X-Mailgun-Recipient-Variables headers before submission; each recipient’s message also has its placeholders replaced.

This endpoint is part of the Mailgun-Compatible Messages API. The rules of that page apply here too:

This page gives what is different for /messages.mime.

Send a MIME Message

POST /v3/{domain_name}/messages.mime

The request must use a multipart/form-data body, because message is a file.

Parameters

to string / required / may be repeated	The envelope recipients: the addresses that GreenArrow delivers the message to. The values have the same form as `to` on /messages: an address, an address with a name, or a list of these with commas between them. GreenArrow uses only the addresses. GreenArrow does not use the `To` and `Cc` headers of the document to choose the envelope recipients. Each recipient must be in `to`. GreenArrow removes duplicate addresses, and the limit of 1,000 recipients applies. GreenArrow gives the addresses to the HTTP Submission API as `envelope_recipients`, or as `to` in a batch. See Batch Sending.
message file / required	The complete MIME message, as a file part. GreenArrow does not use the filename of the part. See The Document. A plain value is refused with `400` and the message `'message' parameter is not a file`. A request without `message` is refused with `400` and the message `message parameter is missing`, and a request with two `message` parts is refused with `400` and the message `message parameter must have one value`.
o:{option} string / optional	The same options as on /messages, with the same values. GreenArrow adds the headers of the options to the front of the document. `o:sending-ip-pool` goes to the HTTP Submission API as `route`.
h:{header} string / optional	A header to add to the front of the document. The same headers are refused as on /messages. GreenArrow adds this header, even if the MIME document also contains a header of the same name. This can cause duplicate headers to exist in the final message. The exceptions to this are `h:Message-ID`, which sets Message-ID. In a batch, if the recipient has variables, those will override what is provided in `h:X-Mailgun-Variables`.
v:{name} string / optional	A variable of the message, as on /messages.

These parameters of /messages are not allowed, because the document has them: from, cc, bcc, subject, text, html, amp-html, attachment and inline. Each one is refused with 400 and the message {name} parameter is not allowed with messages.mime.

The Document

To validate the document, GreenArrow examines its header block: the lines before the first empty line. A line break can be CR LF, LF or CR. GreenArrow refuses the request with 400 when:

Case	Message
The document is not valid UTF-8.	`message parameter is not valid UTF-8`
A line of the header block is not a header field (a name, a colon and a value) and is not a continuation line (a line that starts with a space or a tab). A continuation line in front of the first header field.	`message parameter has a header line that is not valid`
The header block has a header that controls GreenArrow (`X-GreenArrow-*`, `X-Virtual-MTA`, `X-Schedule`, `X-Job`, `X-CampaignID` or `X-Mailer-Info`), or a `Bcc` header.	`message parameter has the header {header}, which is not allowed`
The header block has no `From` header or two of them, or an address of the `From` header has a domain other than `{domain_name}`. The letter case of the domain does not matter.	`message parameter must have a From header with the domain {domain_name}`

UTF-8. The HTTP Submission API takes the document as a JSON string, so the document must be valid UTF-8. A part with 8-bit text in another charset is refused. Encode such a part with quoted-printable or base64.

Control headers. Use the o: options to set what the control headers set. A Return-Path, Authentication-Results or Sender header in the document is accepted.

The Added Headers

GreenArrow adds these headers to the front of the document, in this order. Each one is present only when it applies:

Message-ID, when the document has none. See The Message-ID.
X-GreenArrow-Click-Tracking-ID, outside a batch. See The Click Tracking ID.
X-Mailgun-Variables, with the v: variables, outside a batch.
X-GreenArrow-Disable-Auto-List-Unsubscribe-Header: yes. See “No unsubscribe tracking” in Differences from Mailgun.
The headers of the o: options, in the order of the parameter list of /messages.
The h: headers, in request order. This includes h:X-Mailgun-Variables, which GreenArrow adds as given.

The lines of the added headers end as the first line of the document ends. Outside a batch, a message with both h:X-Mailgun-Variables and v: parameters has two X-Mailgun-Variables headers, as on Mailgun.

The Message-ID

The id of a 200 response is the Message-ID of the message:

When the document has a Message-ID header, id is its value as the document writes it. GreenArrow does not add angle brackets to it. It does not use h:Message-ID.
When the document has no Message-ID, GreenArrow adds one: the h:Message-ID value, or one that GreenArrow makes. The rules are those of /messages.

A Message-ID header with an empty value counts as no Message-ID. The document keeps the empty header.

Batch Sending

A request with recipient-variables, h:X-Mailgun-Recipient-Variables, or an X-Mailgun-Recipient-Variables header in the document is a batch. The rules of Batch Sending apply. On /messages.mime, also:

GreenArrow sends one message to each to address. The document keeps its own To header, with its placeholders replaced. Write To: %recipient% to address each message to its recipient.
GreenArrow replaces the placeholders also in quoted-printable and base64 text parts, and in RFC 2047 encoded words of the headers. It does not replace them in a part whose Content-Disposition is attachment, or in MIME parameters such as filename.
GreenArrow removes each X-Mailgun-Recipient-Variables header from the document.
The Message-ID of the document must be a valid msg-id in angle brackets, such as <[email protected]>. Another value is refused with 400 and the message message parameter has a Message-ID that is not a valid Message-ID.
GreenArrow does not add the X-GreenArrow-Click-Tracking-ID and X-Mailgun-Variables headers of The Added Headers to the document. Each recipient gets its own Click Tracking ID. When the request has v: variables or members of h:X-Mailgun-Variables, the recipient also gets an X-Mailgun-Variables header with their merged values. That header replaces h:X-Mailgun-Variables.

Example

The file newsletter.eml:

From: Example Team <[email protected]>
To: Alice Adams <[email protected]>
Subject: September update
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8

Hello!

The request:

curl -s --user "api:$API_KEY" \
  https://mg.api.example.com/v3/mail.example.com/messages.mime \
  -F to='[email protected]' \
  -F [email protected] \
  -F o:tag=september-update

200 OK:

{"id": "<[email protected]>", "message": "Queued. Thank you."}

The document has no Message-ID, so GreenArrow adds one. The message that GreenArrow submits starts with these headers:

Message-ID: <[email protected]>
X-GreenArrow-Click-Tracking-ID: {"m":"3f2b8c1e-9d4a-4e6f-8a17-5c0d2e9b7a41","M":"<[email protected]>","t":["september-update"]}
X-GreenArrow-Disable-Auto-List-Unsubscribe-Header: yes
From: Example Team <[email protected]>
To: Alice Adams <[email protected]>

Differences from Mailgun

The differences of /messages apply, where the parameter exists on /messages.mime. These differences are for /messages.mime only:

The From domain. Each address of the From header of the document must have the domain {domain_name}.

UTF-8. The document must be valid UTF-8.

Refused headers in the document. A document with a header that controls GreenArrow (X-GreenArrow-*, X-Virtual-MTA, X-Schedule, X-Job, X-CampaignID or X-Mailer-Info) or with a Bcc header is refused.

Added h: headers. GreenArrow adds an h: header also when the document has a header of the same name. Outside a batch, the message can have both; in a batch, a per-recipient X-Mailgun-Variables header replaces the h: header when that per-recipient header exists.

message is sent one time. A request with two message parts is refused.

An X-Mailgun-Recipient-Variables header that is not valid. A document whose X-Mailgun-Recipient-Variables header is not a JSON object or null is refused with 400. Mailgun answers 500.