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

Postmark does not sign Business Associate Agreements (BAAs). HIPAA requires a signed BAA with any vendor that handles Protected Health Information (PHI) in transit — including transactional email providers. Paubox is purpose-built for HIPAA-compliant email and signs a BAA with every customer. The Postmark API uses familiar REST/JSON patterns, so the switch is straightforward for developers already comfortable with Postmark.

​
What stays the same

  • REST API over HTTPS with JSON request bodies
  • API key authentication via a request header
  • Domain authentication: SPF and DKIM records required
  • SMTP as an alternative to the HTTP API
  • Webhook-based event notifications for delivery status

​
Key differences

DimensionPostmarkPaubox Email API
Base URLhttps://api.postmarkapp.com/emailhttps://api.paubox.net/v1/$PAUBOX_ENDPOINT/messages
Auth headerX-Postmark-Server-Token: $TOKENAuthorization: Bearer $PAUBOX_API_KEY
Request body shapeFrom, To, Subject, HtmlBody flat keysdata.message object with headers and content keys
SMTP hostsmtp.postmarkapp.comsmtp.paubox.com
SMTP usernamePostmark server token (as username)apikey (literal)
SMTP passwordPostmark server token (as password)Paubox API key
SMTP port587 or 2525587 (also supports 465, 25)
Webhook eventsDelivery, Open, Click, Bounce, SpamComplaint, SubscriptionChangedelivered, opened, temporary_failure, permanent_failure
Batch send/email/batch endpoint, up to 500/request/bulk_messages endpoint, recommended max 50 per request
TLS enforcementOptionalAlways-on, cannot be disabled
Message streamsTransactional + Broadcast streamsSingle unified API — no stream concept

​
Send a single email

curl -X POST https://api.postmarkapp.com/email \
  -H "X-Postmark-Server-Token: $POSTMARK_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "From": "provider@yourclinic.com",
    "To": "patient@example.com",
    "Subject": "Your appointment summary",
    "HtmlBody": "<p>See attached.</p>",
    "MessageStream": "outbound"
  }'
Note:$PAUBOX_ENDPOINT is the username shown on your Paubox Email API > Settings page — not your email address.

​
SMTP configuration

const transporter = nodemailer.createTransport({
  host: 'smtp.postmarkapp.com',
  port: 587,
  auth: {
    user: process.env.POSTMARK_SERVER_TOKEN,
    pass: process.env.POSTMARK_SERVER_TOKEN,
  },
});
Tip:Note the username change: Postmark uses the server token as both username and password. Paubox uses the literal string apikey as username and your API key as password.

​
Webhook event mapping

Postmark eventPaubox event keyNotes
Deliveryapi_mail_log_delivered
Openapi_mail_log_opened
Bounce (hard)api_mail_log_permanent_failure
Bounce (soft)api_mail_log_temporary_failure
Click— no equivalentRemove handler or no-op; poll click data via Get message receipt
SpamComplaint— no equivalentRemove handler
SubscriptionChange— 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

Replace the Postmark endpoint and X-Postmark-Server-Token header with the Paubox endpoint and Bearer token. Restructure the request body to use the data.message shape shown above.
5

Remove MessageStream

Paubox has no stream concept. Remove the "MessageStream" field from all requests.
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 Click, SpamComplaint, and SubscriptionChange.
8

Remove any code that disables TLS

Paubox enforces TLS on every message. Any allowNonTLS: true or equivalent settings should be removed.
9

Send a test message

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

Swap DNS records

Replace Postmark SPF/DKIM records with the Paubox records shown in your Settings page.
11

Revoke Postmark server tokens

Once traffic has fully moved to Paubox, revoke your Postmark server tokens.

​
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