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: Paubox verifies your sending domain with an SPF record
- SMTP as an alternative to the HTTP API
- Webhook-based event notifications for delivery status
- Per-domain sending configuration
Key differences
Send a single email
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
Webhook event mapping
Note:Click counts are available by polling
GET /message_receipt?sourceTrackingId=...; they are not delivered as a push webhook event. The receipt includes them only when Click Tracking is turned on in Settings > Email API. It is off by default.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 Settings → Webhooks.
Migration checklist
1
Sign a BAA with Paubox
Required before go-live. Contact Paubox to initiate the Business Associate Agreement.
2
Create an account and verify your sending domain
Add your domain on the Settings > Domains page, add
include:_spf.paubox.com to your domain’s SPF record as shown on the domain’s page, then click Verify. The record shown adds the Paubox include to your existing SPF entries rather than replacing them, so Mailgun keeps working while you migrate. See the Quickstart guide for step-by-step instructions.3
Generate a Paubox API key
From the Settings > API Keys page, generate an API key with the Paubox Email API scope for your verified domain. All requests use the base URL
https://api.paubox.com/v1/email.4
Update base URL and authentication
Replace the Mailgun domain-namespaced URL and Basic Auth header with the Paubox endpoint and Bearer token.
5
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.6
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.7
Remap or remove webhook handlers
Update your webhook endpoint using the event mapping table above. Remove handlers for
clicked, unsubscribed, complained, and accepted.8
Remove any EU region URL overrides
Paubox has a single global endpoint;
api.eu.mailgun.net has no equivalent and should be removed.9
Remove any code that disables TLS
Paubox sends every message over TLS by default and falls back to a Secure Portal message when the recipient server cannot accept TLS. Remove any
allowNonTLS: true or equivalent settings unless you intend to allow non-TLS delivery, which is not HIPAA compliant for messages containing PHI.10
Send a test message
Confirm delivery using the Get message receipt endpoint with the
sourceTrackingId returned from your test send.11
Remove Mailgun DNS records
Once traffic has fully moved to Paubox, remove Mailgun’s SPF entries and DKIM records from your DNS. Keep
include:_spf.paubox.com. Paubox Email API domains need no DKIM record of their own.12
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 multiple messages in one request (recommended max 50)
SMTP API
Connect via SMTP instead of REST