Skip to main content

Why migrate

SendGrid does not sign Business Associate Agreements (BAAs) for standard transactional email accounts. HIPAA requires a signed BAA with any vendor that handles Protected Health Information (PHI) in transit, including email providers. Paubox is purpose-built for HIPAA compliant email and signs a BAA with every customer. The API is REST-based and follows patterns SendGrid developers will recognize, so the switch is straightforward.

What stays the same

  • REST API over HTTPS with JSON request bodies
  • Domain authentication: Paubox verifies your sending domain with an SPF record
  • API key authentication via the Authorization header
  • SMTP as an alternative to the HTTP API (same apikey / API-key-as-password pattern)
  • Webhook-based event notifications for delivery status

Key differences

Send a single email

SMTP configuration

The only required change is host. The username/password pattern is identical.
Tip:port, user, and the auth pattern are unchanged. Only host needs to be updated.

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.

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 SendGrid 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, auth header, and request body

Apply the changes shown in the Key differences table and Send a single email section above.
5

Update SMTP credentials

If you use the SMTP path, update host to smtp.paubox.com. See SMTP configuration above.
6

Remap or remove webhook handlers

Update your webhook endpoint using the event mapping table above. Remove handlers for click, spam_report, processed, and unsubscribe.
7

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.
8

Send a test message

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

Remove SendGrid DNS records

Once traffic has fully moved to Paubox, remove SendGrid’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.
10

Revoke SendGrid API keys

Once traffic has fully moved to Paubox, revoke your SendGrid API keys.

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