Migrate from Mailgun

Why migrate

HIPAA requires a signed Business Associate Agreement (BAA) with any vendor that handles Protected Health Information (PHI) in transit, including transactional email providers. While Mailgun will sign a Business Associate Agreements (BAAs), itʻs essentially a server-side BAA only. Email in transit over the internet is explicitly excluded from protection obligations, TLS is opportunistic (not enforced), and the customer is held responsible for encrypting PHI. This is the exact gap Paubox closes, email encryption with no fallback to plaintext, regardless of what the recipient’s mail server supports. Paubox is purpose-built for HIPAA compliant email and signs a BAA with every customer. While Mailgun’s API differs from Paubox’s in a few key ways (notably request format and authentication), the concepts map cleanly and the migration is straightforward.

What stays the same

REST API over HTTPS
Domain authentication: SPF and DKIM records required
SMTP as an alternative to the HTTP API
Webhook-based event notifications for delivery status
Per-domain sending configuration

Key differences

Dimension	Mailgun	Paubox Email API
Base URL	`https://api.mailgun.net/v3/YOUR_DOMAIN/messages`	`https://api.paubox.com/v1/email/messages`
EU region URL	`https://api.eu.mailgun.net/v3/YOUR_DOMAIN/messages`	No region selection required
Auth method	HTTP Basic Auth (username `api`, password = API key)	Bearer token: `Authorization: Bearer $PAUBOX_API_KEY`
Request body format	`multipart/form-data` (`-F` flags in curl)	`application/json` (JSON body)
Request body shape	Flat fields: `from`, `to`, `subject`, `html`, `text`	`data.message` object with `headers` and `content` keys
SMTP host	`smtp.mailgun.org`	`smtp.paubox.com`
SMTP username	Per-domain login (e.g. `postmaster@yourdomain.com`)	`apikey` (literal)
SMTP password	Per-domain password from Mailgun Control Panel	Paubox API key
SMTP port	587 or 2525	587 (also supports 465, 25)
Webhook events	accepted, delivered, opened, clicked, unsubscribed, permanent_fail, temporary_fail, complained	delivered, opened, temporary_failure, permanent_failure
Batch send	Same endpoint with multiple `to` recipients or recipient variables	`/bulk_messages` endpoint, recommended max 50 per request
TLS enforcement	Optional	Always-on, cannot be disabled

Send a single email

curl -s --user 'api:$MAILGUN_API_KEY' \
  https://api.mailgun.net/v3/YOUR_DOMAIN/messages \
  -F from='provider@yourclinic.com' \
  -F to='patient@example.com' \
  -F subject='Your appointment summary' \
  --form-string html='<p>See attached.</p>'

curl -X POST https://api.paubox.com/v1/email/messages \
  -H "Authorization: Bearer $PAUBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "message": {
        "recipients": ["patient@example.com"],
        "headers": {
          "subject": "Your appointment summary",
          "from": "provider@yourclinic.com"
        },
        "content": {
          "text/html": "<p>See attached.</p>"
        }
      }
    }
  }'

Note:Mailgun uses multipart/form-data with HTTP Basic Auth. Paubox uses JSON with a Bearer token. Both the Content-Type header and the request body structure need to be updated.

SMTP configuration

const transporter = nodemailer.createTransport({
  host: 'smtp.mailgun.org',
  port: 587,
  auth: {
    user: 'postmaster@yourdomain.com', // per-domain SMTP login from Mailgun Control Panel
    pass: process.env.MAILGUN_SMTP_PASSWORD,
  },
});

const transporter = nodemailer.createTransport({
  host: 'smtp.paubox.com',
  port: 587,
  auth: {
    user: 'apikey',
    pass: process.env.PAUBOX_API_KEY,
  },
});

Tip:Mailgun SMTP credentials are per-domain and found under Sending → Domain Settings → SMTP credentials in the Mailgun Control Panel. Paubox uses the literal string apikey as username and your API key as password; no per-domain credential needed.

Webhook event mapping

Mailgun event	Paubox event key	Notes
`delivered`	`api_mail_log_delivered`
`opened`	`api_mail_log_opened`
`permanent_fail`	`api_mail_log_permanent_failure`
`temporary_fail`	`api_mail_log_temporary_failure`
`clicked`	No equivalent	Remove handler or no-op; poll click data via Get message receipt
`unsubscribed`	No equivalent	Manage unsubscribes in the Paubox dashboard
`complained`	No equivalent	Remove handler
`accepted`	No equivalent	Remove handler; `delivered` confirms acceptance

Note:Click tracking is available by polling GET /message_receipt?sourceTrackingId=...; it is not delivered as a push webhook event.

Note:Mailgun webhooks are configured per domain under Sending → Webhooks in the Control Panel, or via the Webhooks API. Paubox webhooks are configured in the Paubox dashboard under Email API → Webhooks.

Migration checklist

Sign a BAA with Paubox

Required before go-live. Contact Paubox to initiate the Business Associate Agreement.

Create an account and verify your sending domain

Add your domain on the Paubox Email API > Settings page and complete the TXT record verification. See the Quickstart guide for step-by-step instructions.

Generate a Paubox API key

From the Settings page, generate an API key. All requests use the base URL https://api.paubox.com/v1/email.

Update base URL and authentication

Replace the Mailgun domain-namespaced URL and Basic Auth header with the Paubox endpoint and Bearer token.

Convert request body from form-data to JSON

Change Content-Type from multipart/form-data to application/json and restructure the body to use the data.message shape shown above.

Update SMTP credentials

If you use the SMTP path, update host to smtp.paubox.com, set username to the literal string apikey, and password to your Paubox API key.

Remap or remove webhook handlers

Update your webhook endpoint using the event mapping table above. Remove handlers for clicked, unsubscribed, complained, and accepted.

Remove any EU region URL overrides

Paubox has a single global endpoint; api.eu.mailgun.net has no equivalent and should be removed.

Remove any code that disables TLS

Paubox enforces TLS on every message. Any allowNonTLS: true or equivalent settings should be removed.

Send a test message

Confirm delivery using the Get message receipt endpoint with the sourceTrackingId returned from your test send.

Swap DNS records

Replace Mailgun SPF/DKIM records with the Paubox records shown in your Settings page.

Revoke Mailgun API keys

Once traffic has fully moved to Paubox, revoke your Mailgun API keys and SMTP credentials.

Next steps

Quickstart guide

Full setup walkthrough from account creation to first send

Webhooks reference

Configure delivery event notifications

Batch send

Send up to 50 messages in a single request

SMTP API

Connect via SMTP instead of REST

Get started

Email API

Migrate to Paubox

Marketing API

MCP Server

SDKs

CLI

Forms API

Why migrate

What stays the same

Key differences

Send a single email

SMTP configuration

Webhook event mapping

Migration checklist

Next steps

Quickstart guide

Webhooks reference

Batch send

SMTP API

​Why migrate

​What stays the same

​Key differences

​Send a single email

​SMTP configuration

​Webhook event mapping

​Migration checklist

​Next steps

Quickstart guide

Webhooks reference

Batch send

SMTP API

Why migrate

What stays the same

Key differences

Send a single email

SMTP configuration

Webhook event mapping

Migration checklist

Next steps