Receiving Messages via HTTP through a forward() action
When a URL is specified as a route destination through a forward() action, Mailgun will perform an HTTP POST request into the URL using one of the two formats:
- Fully parsed : Mailgun will parse the message, encode it into UTF-8, process the attachments, and attempt to separate quoted parts from the actual message. *Preferred Option.
- Raw MIME : The message will be posted as-is. You are responsible for parsing MIME. To receive raw MIME message, the destination URL must end with mime.
For Route POSTs, Mailgun listens to codes from your server and reacts accordingly:
| Received by Mailgun | Code description |
|---|---|
200 (Success) | When Mailgun receives this code, it will determine the webhook POST is successful and will not be retried. |
406 (Not Applicable) | When this code is received, Mailgun will determine the POST is rejected and it will not be retried. |
Any other code | Mailgun will try POSTing according to the schedule (below) for webhooks other than the delivery notification. |
If a 406 error code is not returned and your application is unable to process the webhook request, Mailgun will attempt to retry (other than for delivery notification) in intervals for 8 hours before stopping to try. The intervals are 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hours, and 4 hours.
You can use these two tables of HTTP parameters to determine what you can expect to be posted into your applications through a forward() action.
Parsed Messages Parameters
| Parameter | Type | Description |
|---|---|---|
recipient | string | The recipient of the message as reported by MAIL TO during SMTP chat |
sender | string | The sender of the message as reported by MAIL FROM during SMTP chat. Note: this value may differ from From MIME header |
from | string | The sender of the message as reported by from message header, for example "Bob <bob@example.com>" |
subject | string | Subject string |
Body-plain | string | The text version of the email. This field is always present. If the incoming message only has HTML body, Mailgun will create a text representation for you. |
stripped-text | string | The text version of the message without quoted parts and signature block (if found) |
stripped-signature | string | The signature block stripped from the plain text message (if found) |
body-html | string | The HTML version of the message, if message was multipart. Note that all parts of the message will be posted, not just text/html. For instance, if a message arrives with "foo" part it will be posted as "body-foo" |
stripped-html | string | The HTML version of the message, without quoted parts. |
Attachment-count | int | The number of attachments the message has. |
Attachment-x | string | The attached file ('x' stands for number of the attachment). Attachments are handled as file uploads, encoded as multipart/form-data. |
timestamp | int | The number of seconds passed since January 1, 1970 (see securing web hooks) |
token | string | A randomly generated string with a length of 50 (See securing webhooks) |
signature | string | A string with hexadecimal digits generated by HMAC algorithm (see securing webhooks). |
message-headers | string | A list of MIME headers dumped to a JSON string (order of headers is preserved) |
Content-id-map | string | JSON-encoded dictionary which maps Content-ID (CID) of each attachment to the corresponding attachment-x parameter. This allows you to map posted attachments to tags like <img src='cid'> in the message body. |
Not all web frameworks support multi-valued keys parameters, so the message-headers parameter was added.
Example: Ruby on Rails requires a special syntax to post params like that: you need to add [] to a key to collect its values on the server side as an array.
Below is a Ruby on Rails example of obtaining MIME headers via message-headers parameter:
MIME Messages Parameters
| Parameter | Type | Description |
|---|---|---|
recipient | string | The recipient of the message |
sender | string | The sender of the message as reported by SMTP MAIL FROM |
from | string | The sender of the message as reported by from message header, for example "Bob <bob@example.com>". |
subject | string | The subject string |
Body-mime | string | The full MIME envelope. You will need a MIME parsing library to process this data. |
timestamp | int | The number of seconds passed since January 1, 1970 (See Securing Webhooks) |
token | string | A randomly generated string with a length of 50 (See Securing Webhooks) |
signature | string | A string with hexadecimal digits generated by HMAC algorithm (S_ee securing webhooks_). |
To receive raw MIME messages and perform your own parsing, you must configure a route with a URL ending with "mime". Example: http://myhost/post_mime
*Consider using http:/bin.mailgun.net to debug and play with your routes. This tool allows you to forward incoming messages to a temporary URL and inspect the posted data.