Mailgun-Compatible Messages API

• Table of Contents
• Overview
• Authentication
• Requests and Responses
• Limits
• Send a Message
• The Message-ID
• Tags and Variables
• Batch Sending
• Unsupported Parameters
• Differences from Mailgun

Overview

The Mailgun-compatible Messages API lets software that was written for Mailgun’s message sending API send email through GreenArrow. GreenArrow translates each request and submits the message to the HTTP Submission API.

These endpoints are available:

This page documents /messages and the rules that apply to both endpoints. The Mailgun-Compatible MIME Messages API page documents what is different for /messages.mime.

A request that is not a batch sends one message to all of its recipients. A batch request (with recipient-variables or an X-Mailgun-Recipient-Variables header) sends one message to each to recipient, with the variables of that recipient. See Batch Sending.

Send each request to the hostname of the Mailgun compatibility API of your GreenArrow CloudMTA. The examples on this page use mg.api.example.com.

Read Differences from Mailgun before you move an integration from Mailgun. Some requests that Mailgun accepts are refused here.

The Mail Class

Each message uses the Mail Class that the mailclass option of the compatibility_api_mailgun directive names. The bounce address of this Mail Class is the envelope sender (MAIL FROM) of each message. The other settings of the Mail Class apply too, for example its click and open tracking settings when the request does not have o:tracking, o:tracking-clicks or o:tracking-opens.

GreenArrow records the IP address of your client as the source address of the message. When the http_submission_api_received_header directive is show_source, the Received header of the message shows it.

Authentication

Authenticate with HTTP Basic authentication. The username is api, and the password is a GreenArrow API key.

curl -s --user "api:$API_KEY" \
  https://mg.api.example.com/v3/mail.example.com/messages \
  -F from='[email protected]' \
  -F to='[email protected]' \
  -F subject='Hello' \
  -F text='Hello!'

GreenArrow checks the credentials first: before it reads the request body, and before it checks a parameter. A request with no credentials, with a username other than api, or with a key that is not valid gets the 401 response, also when the request has other errors.

The 401 response has the plain-text body Forbidden, with Content-Type: text/plain; charset=utf-8 and the header WWW-Authenticate: Basic realm="MG API", as on Mailgun.

Requests and Responses

Request format

• Send the parameters in a multipart/form-data body (curl -F) or in an application/x-www-form-urlencoded body. A request with an attachment must use multipart/form-data. A body of another type is refused with 400.
• The body can be compressed with gzip. Set the header Content-Encoding: gzip.
• GreenArrow does not read the query string. Send each parameter in the body.
• To give a parameter more than one value (for example two to addresses), send the parameter one time for each value.
• attachment and inline must be file parts of a multipart/form-data body. Each other parameter must be a plain value. A plain value of attachment or inline, and a file part of another parameter (for example html sent as a file), is refused with 400.
• The fixed values of the options (yes, no, true, false and htmlonly) are accepted in any letter case, for example YES or HtmlOnly.
• A parameter that this page does not list is refused with 400. See Unsupported Parameters.

The domain in the path

{domain_name} is the sending domain. The domain of the from address must be equal to it.

A {domain_name} that is not a valid domain name, or that has no dot (for example localhost or ip_pools), gets the 401 response. Mailgun gives the same answer for a domain that is not a domain of the account.

The answers for a domain that is not ready to send depend on how your GreenArrow CloudMTA uses Sending Domains:

• When GreenArrow uses Sending Domains, a Sending Domain whose DNS records are verified and whose sending is disabled (sending_enabled is false) gets the 403 response.
• When GreenArrow also requires that the From domain of each message is a verified Sending Domain, a {domain_name} that is not a Sending Domain gets the 401 response. A Sending Domain whose DNS records are not verified also gets the 401 response.

When GreenArrow does not use Sending Domains in these ways, it accepts a message from a domain that is not a Sending Domain.

Success

A message that GreenArrow queued gets a 200 response with Content-Type: application/json; charset=utf-8:

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

id is the Message-ID of the message. See The Message-ID.

Errors

The body of an error response is JSON with one field, message, except the plain-text 401 response:

{"message": "from parameter is missing"}

GreenArrow waits up to 60 seconds for the HTTP Submission API to queue the message. When this time passes, the answer is the 500 response, and the message can be queued or not.

When a request has more than one error, the response gives one of them.

Error Messages

These are the messages of the 400, 413 and 429 responses. When GreenArrow and Mailgun refuse a request for the same reason, the message is Mailgun’s. {name} is the name of the parameter as sent, and {value} is its value.

The /messages.mime endpoint has more messages for its message parameter. See The Document.

The HTTP Submission API also checks each message. When it refuses a message, the response is a 400 with the message of the HTTP Submission API.

Limits

Send a Message

POST /v3/{domain_name}/messages

GreenArrow builds the message from the parameters, and submits it to the HTTP Submission API. All of its recipients get one message, except in a batch.

Parameters

template, t:version, t:text, t:variables and some o: options are not supported. See Unsupported Parameters.

Repeated and Empty Values

When a parameter that has one value is sent more than one time, GreenArrow does this:

An empty text, html or amp-html value counts as absent. An empty subject gives an empty subject, an empty ordinary h: value gives an empty header, an empty v: value gives the value "", and an empty o:tag gives the tag "". An empty recipient-variables or h:X-Mailgun-Recipient-Variables value is refused because it is not valid JSON.

Attachments and Inline Images

Send each attachment and inline file as a file part of a multipart/form-data body, for example -F [email protected] with curl.

• Content type. GreenArrow uses the Content-Type of the part. When the part has no type, a type that is not valid, or application/octet-stream, GreenArrow uses the type of the filename’s extension, or application/octet-stream when the extension is not known.
• Filenames. A filename cannot be blank, and cannot contain ", ', CR or LF.
• Inline filenames. The filename of an inline part is its Content-ID, so it must also be an RFC 5322 dot-atom-text, with or without an @ and a dot-atom-text domain. Thus photo.jpg and [email protected] are accepted, and my photo.jpg and a name with characters that are not ASCII are refused.
• Content. A file cannot be empty, and cannot be the one character 0.

The message has the attachment files first, then the inline files, each in request order.

Examples

A message with two recipients

curl -s --user "api:$API_KEY" \
  https://mg.api.example.com/v3/mail.example.com/messages \
  -F from='Example Team <[email protected]>' \
  -F to='Alice Adams <[email protected]>' \
  -F to='[email protected]' \
  -F subject='September update' \
  --form-string html='<html><body><p>Hello!</p></body></html>' \
  --form-string text='Hello!' \
  -F o:tag=september-update \
  -F o:tracking=false \
  -F h:Reply-To='[email protected]' \
  -F v:campaign_id=2026-09-update

200 OK:

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

The message has one To header with both recipients.

A message with an attachment and an inline image

curl -s --user "api:$API_KEY" \
  https://mg.api.example.com/v3/mail.example.com/messages \
  -F from='[email protected]' \
  -F to='[email protected]' \
  -F subject='Your report' \
  --form-string html='<p>Your report is attached.</p><img src="cid:logo.png">' \
  -F text='Your report is attached.' \
  -F [email protected] \
  -F [email protected]

A scheduled message

This message is delivered on 18 September 2026 from 09:00 to 11:00 UTC:

curl -s --user "api:$API_KEY" \
  https://mg.api.example.com/v3/mail.example.com/messages \
  -F from='[email protected]' \
  -F to='[email protected]' \
  -F subject='Good morning' \
  -F text='Good morning!' \
  -F o:deliverytime='Fri, 18 Sep 2026 09:00:00 +0000' \
  -F o:deliver-within=2h

The Message-ID

The id of a 200 response is the Message-ID of the message, with angle brackets.

• With h:Message-ID, the Message-ID is that value. GreenArrow adds the angle brackets when they are missing. The value must be a valid msg-id (RFC 5322): a dot-atom-text, @, and a dot-atom-text or a domain literal ([192.0.2.1]). Another value, for example hello, is refused with 400.
• Without h:Message-ID, GreenArrow makes a Message-ID in Mailgun’s form: <{time}.{random}@{domain_name}>. {time} is the time of the request in UTC as YYYYMMDDhhmmss, and {random} is 16 lower-case hexadecimal digits. For example: <[email protected]>.

For /messages.mime, the Message-ID of the document comes first. See The Message-ID on that page.

Tags and Variables

The Click Tracking ID

GreenArrow writes the tags, the variables and the identity of each message as a JSON document in its X-GreenArrow-Click-Tracking-ID header. The events of the message have this document in their click_tracking_id field.

{"m":"3f2b8c1e-9d4a-4e6f-8a17-5c0d2e9b7a41","M":"<[email protected]>","t":["september-update"],"v":{"campaign_id":"2026-09-update"}}

The document is compact JSON, with no spaces between tokens. Each character that is not ASCII is written as a \uXXXX escape. <, > and & are not escaped. A control character (U+0000 to U+001F, and U+007F) in a tag, in a v: value, or in a string of h:X-Mailgun-Variables is refused with 400.

The document must fit in 300 characters. GreenArrow refuses a request whose document is longer with 400. GreenArrow does not cut the variables, so the events always have all of them. The m and M values count toward the 300 characters. With a Message-ID that GreenArrow makes, the document without tags and variables is 85 characters plus the length of the domain name. The escapes of the JSON encoding count too.

The X-Mailgun-Variables Header

When a request has v: parameters, the message has an X-Mailgun-Variables header with the variables as a JSON object, in the form that Mailgun writes: with a space after each , and : between tokens, and the names in byte order. For example:

X-Mailgun-Variables: {"C": "3", "a": "1", "b": "2"}

As in the Click Tracking ID, each character that is not ASCII is written as a \uXXXX escape.

h:X-Mailgun-Variables. Without v: parameters, an h:X-Mailgun-Variables header is written as given. When its value is a JSON object, its members are also variables of the message, with their JSON types. A name that is in the header and in a v: parameter gets a JSON array of the two values, the value of the header first: {"a": ["from-header", "from-v"]}. A value that is not a JSON object gives no variables, and it is not an error.

When a /messages request has both h:X-Mailgun-Variables and v: parameters, the message has one X-Mailgun-Variables header with the merged variables. A value of h:X-Mailgun-Variables that is not a JSON object is then lost. Outside a batch, /messages.mime writes both headers, as Mailgun does.

Unfold the header before you parse it. GreenArrow folds each header that is too long for one line (998 bytes):

• It folds the X-Mailgun-Variables header that it writes at the spaces between the JSON tokens. Only when one name or one string value is too long for a line does it fold at a space inside that string.
• It folds an h:X-Mailgun-Variables header that it writes as given at any of its spaces, also inside a string value.

A fold puts a line break in front of a space. Thus the JSON is correct only when you unfold the header (RFC 5322) before you parse it. A reader that does not unfold the header can get a string value with a line break in it, or JSON that is not valid.

Batch Sending

A request with recipient-variables is a batch. GreenArrow sends one message to each to recipient. On /messages, the To header of each message has only that recipient. (On /messages.mime, the document keeps its own To header. See Batch Sending.) Each message has the variables of its recipient in place of its placeholders. GreenArrow submits a batch to the HTTP Submission API as one template. See Individualized Messages.

curl -s --user "api:$API_KEY" \
  https://mg.api.example.com/v3/mail.example.com/messages \
  -F from='Example Team <[email protected]>' \
  -F to='Alice Adams <[email protected]>' \
  -F to='[email protected]' \
  -F subject='Hey %recipient.first_name%, your plan renews soon' \
  --form-string text='Hi %recipient.first_name%, your plan renews on %recipient.renews_on%.' \
  -F recipient-variables='{"[email protected]": {"first_name": "Alice", "renews_on": "12 Oct 2026"}, "[email protected]": {"first_name": "Bob", "renews_on": "19 Oct 2026"}}' \
  -F v:campaign_id=2026-10-renewals

Each valid value of recipient-variables makes a batch, also {} and null. With {}, each recipient gets its own copy of the same message. On /messages, the recipients do not see each other’s addresses.

Placeholders. %recipient.{name}% is replaced with the value of the recipient’s variable {name}, and %recipient% with the address of the recipient. GreenArrow replaces the placeholders in the headers of the message (also From, Subject and the h: headers), in its text and HTML parts, and in the v: values. It does not replace them in attachments, in the name of an attachment, or in the variables of h:X-Mailgun-Variables. A placeholder whose variable the recipient does not have stays as it is. The simplemh_batch_unresolved_placeholders_total metric counts these placeholders. For the placeholders in the v: values, GreenArrow also logs the names, with the addresses of up to 10 recipients.

A value is written as Mailgun writes it:

%recipient.address.city% is not a nested name: it is replaced only by a variable called address.city.

The recipients. A key of recipient-variables matches a to address when the two addresses are equal. The letter case does not matter. A key that matches no to address is not used. A to address that has no key gets the message with its placeholders as they are. A key whose value is not an object gives no variables.

The X-Mailgun-Recipient-Variables header. h:X-Mailgun-Recipient-Variables, or an X-Mailgun-Recipient-Variables header in a /messages.mime document, also makes a batch. Its value has the same JSON form as recipient-variables. GreenArrow unfolds the header before it reads it. When a request gives more than one of these, the variables of each recipient merge name by name. For a name in more than one, recipient-variables wins over the headers of the document, and the headers of the document win over h:X-Mailgun-Recipient-Variables. A later header of the document wins over an earlier one. GreenArrow does not deliver the header, because the header has the variables of all of the recipients. h:X-Mailgun-Recipient-Variables counts toward the 16 KB limit of the options. recipient-variables does not.

The response, the Message-ID and the variables. The response is one 200, as for one message. Each message of the batch has the same Message-ID: the id of the response. Each recipient has its own Click Tracking ID: m is a unique ID of the recipient’s message, and v has the v: values with the recipient’s placeholders replaced. v also has the variables of h:X-Mailgun-Variables, with their placeholders as they are. When these sources supply variables, the recipient’s X-Mailgun-Variables header has the same variables as v. On /messages.mime too, that header replaces the message-level h:X-Mailgun-Variables header.

Refused batches. A batch is refused with 400 when:

• It has cc or bcc. Mailgun sends each cc and bcc recipient one copy of the message for each to recipient.
• A variable of a to recipient has a line break (CR or LF).
• The Click Tracking ID of one recipient is longer than 300 characters. The message names the recipient.
• The value of recipient-variables or of the header is not a JSON object or null.

See Error Messages for the messages.

Unsupported Parameters

GreenArrow refuses these parameters with 400:

Differences from Mailgun

The From domain. The domain of from must be equal to {domain_name}. Mailgun accepts a From address of another domain.

Unknown parameters are refused. A parameter that this page does not list is refused with 400.

Refused headers. The h: headers that control GreenArrow (X-GreenArrow-*, X-Virtual-MTA, X-Schedule, X-Job, X-CampaignID and X-Mailer-Info), the headers that GreenArrow builds (From, To, Cc, Subject, Date, MIME-Version, Content-Type and Content-Transfer-Encoding), h:Bcc, h:Return-Path, h:Authentication-Results and h:Sender are refused.

Repeated values. A request with from or an h: header sent more than one time is refused. Mailgun writes both values.

subject is required. Mailgun accepts a request with no subject.

amp-html needs text or html. Mailgun accepts amp-html alone.

Attachments. An attachment or inline filename cannot contain " or '. An inline filename must be an RFC 5322 dot-atom-text, with or without an @ and a dot-atom-text domain: no spaces, and ASCII only. A file cannot be empty, and cannot be the one character 0.

Tags. When a request has more than 10 tags, GreenArrow keeps the first 10 in request order. Mailgun keeps 10, not in request order. A tag cannot contain a control character.

Variables. A v: value cannot contain a control character. The tags and the variables must fit in the 300-character Click Tracking ID. Mailgun cuts variables over 4 KB in its events. GreenArrow does not cut them.

X-Mailgun-Variables. A /messages request with both h:X-Mailgun-Variables and v: parameters gives one X-Mailgun-Variables header with the merged variables. Mailgun writes two headers.

The username. A username other than api is refused with 401. Mailgun accepts any username.

h:Message-ID. The value must be a valid msg-id. Mailgun accepts any value, for example hello.

o:deliverytime. It can be up to 7 days after the request. Mailgun allows 72 hours.

o:dkim. no and false are refused, because GreenArrow always signs.

o:secondary-dkim. A key that does not exist gives no second signature. It is not an error.

The 401 and 403 domain responses. These responses need GreenArrow’s Sending Domains to be in use. See “The domain in the path” in Requests and Responses. Mailgun answers 403 for a domain of the account that is not verified. GreenArrow answers 401 for a Sending Domain whose DNS records are not verified, and 403 for a verified Sending Domain whose sending is disabled.

No unsubscribe tracking. GreenArrow does not add a List-Unsubscribe header, and does not add an unsubscribe footer. It does not replace %unsubscribe_url%, %tag_unsubscribe_url% or %mailing_list_unsubscribe_url%. A List-Unsubscribe header that you send with h:List-Unsubscribe is delivered as given. A Mail Class that forces the automatic List-Unsubscribe header on adds one.

Encoded names. GreenArrow decodes the encoded-words of the charsets UTF-8, ISO-8859-1 and US-ASCII in from, to and cc. It refuses an encoded-word in another charset.

Batch sending. A batch with cc or bcc is refused. A recipient variable with a line break is refused. Mailgun accepts both. The multipart/mailgun-variables part is not supported.

Templates. template and the t: parameters are refused.