> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Mailgun

> Switch from Mailgun to the Paubox Email API for HIPAA-compliant transactional email.

## 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.net/v1/$PAUBOX_ENDPOINT/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

<CodeGroup>
  ```bash Mailgun (before) theme={null}
  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>'
  ```

  ```bash Paubox (after) theme={null}
  curl -X POST https://api.paubox.net/v1/$PAUBOX_ENDPOINT/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>"
          }
        }
      }
    }'
  ```
</CodeGroup>

<Note>
  **Note:**

  `$PAUBOX_ENDPOINT` is the username shown on your [Paubox Email API > Settings](https://next.paubox.com/emailapi/settings) page, not your email address.
</Note>

<Note>
  **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.
</Note>

## SMTP configuration

<CodeGroup>
  ```js Mailgun (before) theme={null}
  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,
    },
  });
  ```

  ```js Paubox (after) theme={null}
  const transporter = nodemailer.createTransport({
    host: 'smtp.paubox.com',
    port: 587,
    auth: {
      user: 'apikey',
      pass: process.env.PAUBOX_API_KEY,
    },
  });
  ```
</CodeGroup>

<Tip>
  **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.
</Tip>

## 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](/email-api/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>
  **Note:**

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

<Note>
  **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.
</Note>

## Migration checklist

<Steps>
  <Step title="Sign a BAA with Paubox">
    Required before go-live. Contact Paubox to initiate the Business Associate Agreement.
  </Step>

  <Step title="Create an account and verify your sending domain">
    Add your domain on the [Paubox Email API > Settings](https://next.paubox.com/emailapi/settings) page and complete the TXT record verification. See the [Quickstart guide](/email-api/quickstart) for step-by-step instructions.
  </Step>

  <Step title="Generate a Paubox API key">
    From the Settings page, generate an API key and note your customer endpoint (`https://api.paubox.net/v1/YOUR_USERNAME`).
  </Step>

  <Step title="Update base URL and authentication">
    Replace the Mailgun domain-namespaced URL and Basic Auth header with the Paubox endpoint and Bearer token.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Remap or remove webhook handlers">
    Update your webhook endpoint using the [event mapping table](#webhook-event-mapping) above. Remove handlers for `clicked`, `unsubscribed`, `complained`, and `accepted`.
  </Step>

  <Step title="Remove any EU region URL overrides">
    Paubox has a single global endpoint; `api.eu.mailgun.net` has no equivalent and should be removed.
  </Step>

  <Step title="Remove any code that disables TLS">
    Paubox enforces TLS on every message. Any `allowNonTLS: true` or equivalent settings should be removed.
  </Step>

  <Step title="Send a test message">
    Confirm delivery using the [Get message receipt](/email-api/message-receipt) endpoint with the `sourceTrackingId` returned from your test send.
  </Step>

  <Step title="Swap DNS records">
    Replace Mailgun SPF/DKIM records with the Paubox records shown in your Settings page.
  </Step>

  <Step title="Revoke Mailgun API keys">
    Once traffic has fully moved to Paubox, revoke your Mailgun API keys and SMTP credentials.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart guide" icon="rocket" href="/email-api/quickstart">
    Full setup walkthrough from account creation to first send
  </Card>

  <Card title="Webhooks reference" icon="webhook" href="/email-api/webhooks">
    Configure delivery event notifications
  </Card>

  <Card title="Batch send" icon="layer-group" href="/email-api/bulk-messages">
    Send up to 50 messages in a single request
  </Card>

  <Card title="SMTP API" icon="server" href="/email-api/smtp">
    Connect via SMTP instead of REST
  </Card>
</CardGroup>