Migrate from SendGrid

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: SPF and DKIM records required
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

Dimension	SendGrid v3	Paubox Email API
Base URL	`https://api.sendgrid.com/v3/mail/send`	`https://api.paubox.com/v1/email`
Auth header	`Authorization: Bearer $SENDGRID_API_KEY`	`Authorization: Bearer $PAUBOX_API_KEY`
Request body shape	`personalizations` array with nested `to`/`subject`	`data.message` object with `headers` and `content` keys
SMTP host	`smtp.sendgrid.net`	`smtp.paubox.com`
SMTP username	`apikey` (literal)	`apikey` (literal, same pattern)
SMTP port	587	587 (also supports 465, 25)
Webhook events	processed, delivered, open, click, bounce, spam_report, unsubscribe	delivered, opened, temporary_failure, permanent_failure
Batch send	up to 1,000 personalizations per request	`/bulk_messages` endpoint, recommended max 50 per request
TLS enforcement	optional (can be disabled)	always-on, cannot be disabled

Send a single email

curl -X POST https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{"to": [{"email": "patient@example.com"}]}],
    "from": {"email": "provider@yourclinic.com"},
    "subject": "Your appointment summary",
    "content": [{"type": "text/html", "value": "<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>"
        }
      }
    }
  }'

SMTP configuration

The only required change is host. The username/password pattern is identical.

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

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

Tip:port, user, and the auth pattern are unchanged. Only host needs to be updated.

Webhook event mapping

SendGrid event	Paubox event key	Notes
`delivered`	`api_mail_log_delivered`
`open`	`api_mail_log_opened`
`bounce` (hard)	`api_mail_log_permanent_failure`
`bounce` (soft) / `deferred`	`api_mail_log_temporary_failure`
`click`	No equivalent	Remove handler or no-op; poll click data via Get message receipt
`spam_report`	No equivalent	Remove handler
`processed`	No equivalent	Remove handler; `delivered` confirms acceptance
`unsubscribe`	No equivalent	Manage unsubscribes in the Paubox dashboard

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

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

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

Update SMTP credentials

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

Remap or remove webhook handlers

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

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 SendGrid SPF/DKIM records with the Paubox records shown in your Settings page.

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