JSON payload delivery for Route forwards is now available for all Mailgun accounts
Many customers use Mailgun Routes to bring inbound email into systems built around JSON, from support platforms to custom applications. Until now, every Route notification was delivered as form-encoded data, so teams whose endpoints were built for JSON needed to introduce an extra translation step, such as a middleware service, before that data could reach their system. Mailgun Routes now support JSON payloads natively. Add json to the end of a route’s destination URL, and Mailgun delivers the parsed message directly as application/json, ready for your endpoint to use as it arrives.
Why should you care?
Native JSON delivery gives your team more flexibility in how Routes fit into your existing systems, while every current integration continues to operate exactly as it does today.
- Send Route notifications directly into JSON-based systems. When your destination URL ends in json, Mailgun delivers the parsed message as application/json, in the format your endpoint expects.
- Adopt the new format on your own timeline. JSON delivery is configured per route, so you can move individual integrations over when it suits your team, without affecting how any other route behaves.
- Keep every existing integration exactly as it is. Routes that do not include the json suffix continue to receive application/x-www-form-urlencoded, exactly as they always have.
- Build on a familiar payload structure. The JSON payload uses the same field names as the form-based payload, so adapting an existing integration typically means updating a parser, not rebuilding it.
What you need to do
To receive the new format, add json to the end of your route’s destination URL. The JSON payload differs from the form-based payload in a few respects: signature verification is provided through the X-Mailgun-Signature, X-Mailgun-Parent-Signature, and X-Mailgun-Timestamp headers rather than form fields; message-headers is delivered as a native JSON array; and attachments are consolidated into a single attachments array, with each entry providing filename, content-type, and base64-encoded content. Routes that do not include the json suffix are unaffected and continue to receive the existing format.
