From Mailgun to Postal, field by field

Add the domain in the dashboard (or with POST /domains), create the records Postal shows in your DNS and ask for verification. The records use their own names, postal._domainkey and the postal subdomain, so you can publish them next to Mailgun's and only remove the old ones after the cutover. Before that, check that none of your records already uses those names.

• Region: Mailgun has two URLs, US and EU. In Postal there is a single URL and the region is chosen per domain: São Paulo (default), us-east-1, us-east-2, eu-west-1 or ap-northeast-1.
• For systems that only send, create a send-only key, restricted to the domain. The full token appears only once, at creation.
• If your main domain already sends through Mailgun, use a dedicated subdomain in Postal.

In Mailgun the domain goes in the URL and the fields go in form-data. In Postal the domain comes from from and the body is JSON. The response is {"id": "…"}: keep the ID, which comes back in webhooks as data.email_id and lets you look up the email at GET /emails/{id}. With the Idempotency-Key header, repeating a request does not duplicate the send.

- curl -s --user 'api:$MAILGUN_API_KEY' \-   https://api.mailgun.net/v3/mg.exemplo.com.br/messages \-   -F from='Aurora Cosméticos <[email protected]>' \-   -F [email protected] \-   -F subject='Your order #10482 is out for delivery' \-   --form-string html='<p>Order <b>#10482</b> is on its way.</p>' \-   -F o:tag='shipping'+ curl -X POST https://api.postal.so/emails \+   -H "Authorization: Bearer $POSTAL_API_KEY" \+   -H "Content-Type: application/json" \+   -d '{+     "from": "Aurora Cosméticos <[email protected]>",+     "to": ["[email protected]"],+     "subject": "Your order #10482 is out for delivery",+     "html": "<p>Order <b>#10482</b> is on its way.</p>",+     "tags": [{"name": "category", "value": "shipping"}]+   }'

- const form = new FormData();- form.append('from', 'Aurora Cosméticos <[email protected]>');- form.append('to', '[email protected]');- form.append('subject', 'Your order #10482 is out for delivery');- form.append('html', '<p>Order <b>#10482</b> is on its way.</p>');- form.append('o:tag', 'shipping');- const auth = Buffer.from('api:' + process.env.MAILGUN_API_KEY).toString('base64');- await fetch('https://api.mailgun.net/v3/mg.exemplo.com.br/messages', {-   method: 'POST',-   headers: { Authorization: `Basic ${auth}` },-   body: form,- });+ const response = await fetch('https://api.postal.so/emails', {+   method: 'POST',+   headers: {+     Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,+     'Content-Type': 'application/json',+     'Idempotency-Key': 'order-10482-shipped',+   },+   body: JSON.stringify({+     from: 'Aurora Cosméticos <[email protected]>',+     to: ['[email protected]'],+     subject: 'Your order #10482 is out for delivery',+     html: '<p>Order <b>#10482</b> is on its way.</p>',+     tags: [{ name: 'category', value: 'shipping' }],+   }),+ });+ const { id } = await response.json();

Mailgun templates use a version of Handlebars, with conditions (if, unless), loops (each), with and equal. Postal's only substitute variables: {{{NOME}}}, with three braces, and the value must be text or a number. There are no conditions, loops or nested objects. When your template depends on logic, move the logic into code: pick between two templates or build the HTML yourself and send it in html.

• In Postal you edit a draft and publish; sends always use the latest published version, and old versions can be restored.
• In the HTML, values are escaped. A variable with no value and no default value (fallback_value) returns a 422 error.
• Declare the variables when you create the template: up to 50, with a text or number type.

- <h1>Hello, {{name}}!</h1>- <p>Your order: {{order}}</p>+ <h1>Hello, {{{NAME}}}!</h1>+ <p>Your order: {{{ORDER}}}</p>

- -F template='order-shipped' \- -F t:variables='{"name": "Ana", "order": "10482"}'+ "template": {+   "id": "order-shipped",+   "variables": {"NAME": "Ana", "ORDER": "10482"}+ }

If any system sends over SMTP, change the server, user and password. SMTP is part of the plan. Messages go through the same rules as the API (verified domain, quotas, suppression list) and show up in Emails and Logs.

• Postal's limits per message: 40 MB and 50 recipients. Anything over that gets an error; split the send.

- host: 'smtp.mailgun.org',- port: 587,- secure: false,- auth: { user: '[email protected]',-   pass: process.env.MAILGUN_SMTP_PASSWORD },+ host: 'smtp.postal.so',+ port: 465,+ secure: true,+ auth: { user: 'postal', pass: process.env.POSTAL_API_KEY },

Create the endpoint in Postal and keep the signing_secret. The signature changes completely: in Mailgun it comes in the body and uses a webhook signing key; in Postal it comes in headers and uses each endpoint's secret. Calculate it over the body exactly as it arrived, without parsing and rewriting the JSON.

• The webhook-id is the same on every attempt: store the ones you have processed to discard duplicates.
• Respond 2xx right away and process later, in a queue.
• To test without really sending, send emails to the test addresses or use "Send test event" in the dashboard.

- const expected = crypto.createHmac('sha256', process.env.MAILGUN_SIGNING_KEY)-   .update(timestamp + token).digest('hex');- if (expected !== signature) return res.sendStatus(401);+ import { verifyWebhook } from 'postal-so';+ const event = verifyWebhook(req.body, req.headers, process.env.POSTAL_WEBHOOK_SECRET);

{
  "type": "email.delivered",
  "created_at": "2026-10-24T13:02:14.120Z",
  "data": {
    "email_id": "019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b",
    "from": "Aurora Cosméticos <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your order #10482 is out for delivery",
    "tags": { "category": "shipping" }
  }
}

Do this before the first real send, so you do not write to people who already opted out or repeat bounces. Postal pauses the team's sending if permanent bounces go over the limit of the account reputation level (3% for a new account) or complaints go over 0.3%; that is why a clean list matters.

The IDs are different: a Mailgun email ID does not exist in Postal. During the cutover, record which provider each email came from and keep receiving Mailgun webhooks for what went out through it. Send each flow through a single provider, so you do not duplicate sends or pause everything because of the wrong emails.