Skip to main content

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.

​
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

DimensionSendGrid v3Paubox Email API
Base URLhttps://api.sendgrid.com/v3/mail/sendhttps://api.paubox.net/v1/$PAUBOX_ENDPOINT
Auth headerAuthorization: Bearer $SENDGRID_API_KEYAuthorization: Bearer $PAUBOX_API_KEY
Request body shapepersonalizations array with nested to/subjectdata.message object with headers and content keys
SMTP hostsmtp.sendgrid.netsmtp.paubox.com
SMTP usernameapikey (literal)apikey (literal) — same pattern
SMTP port587587 (also supports 465, 25)
Webhook eventsprocessed, delivered, open, click, bounce, spam_report, unsubscribedelivered, opened, temporary_failure, permanent_failure
Batch sendup to 1,000 personalizations per request/bulk_messages endpoint, recommended max 50 per request
TLS enforcementoptional (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>"}]
  }'
Note:$PAUBOX_ENDPOINT is the username shown on your Paubox Email API > Settings page — not your email address.

​
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,
  },
});
Tip:port, user, and the auth pattern are unchanged. Only host needs to be updated.

​
Webhook event mapping

SendGrid eventPaubox event keyNotes
deliveredapi_mail_log_delivered
openapi_mail_log_opened
bounce (hard)api_mail_log_permanent_failure
bounce (soft) / deferredapi_mail_log_temporary_failure
click— no equivalentRemove handler or no-op; poll click data via Get message receipt
spam_report— no equivalentRemove handler
processed— no equivalentRemove handler; delivered confirms acceptance
unsubscribe— no equivalentManage 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

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 Paubox Email API > Settings page and complete the TXT record verification. See the Quickstart guide for step-by-step instructions.
3

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).
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 enforces TLS on every message. Any allowNonTLS: true or equivalent settings should be removed.
8

Send a test message

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

Swap DNS records

Replace SendGrid SPF/DKIM records with the Paubox records shown in your Settings page.
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 up to 50 messages in a single request

SMTP API

Connect via SMTP instead of REST