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

# Migrate from SendGrid

> Switch from SendGrid v3 to the Paubox Email API for HIPAA-compliant transactional email.

## 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.net/v1/$PAUBOX_ENDPOINT`              |
| 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

<CodeGroup>
  ```bash SendGrid (before) theme={null}
  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>"}]
    }'
  ```

  ```bash Paubox (after) theme={null}
  curl -X POST https://api.paubox.net/v1/$PAUBOX_ENDPOINT/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>"
          }
        }
      }
    }'
  ```
</CodeGroup>

<Note>
  **Note:**

  `$PAUBOX_ENDPOINT` is the username shown on your [Paubox Email API > Settings](https://next.paubox.com/emailapi/settings) page, not your email address.
</Note>

## SMTP configuration

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

<CodeGroup>
  ```js SendGrid (before) theme={null}
  const transporter = nodemailer.createTransport({
    host: 'smtp.sendgrid.net',
    port: 587,
    auth: {
      user: 'apikey',
      pass: process.env.SENDGRID_API_KEY,
    },
  });
  ```

  ```js Paubox (after) theme={null}
  const transporter = nodemailer.createTransport({
    host: 'smtp.paubox.com',
    port: 587,
    auth: {
      user: 'apikey',
      pass: process.env.PAUBOX_API_KEY,
    },
  });
  ```
</CodeGroup>

<Tip>
  **Tip:**

  `port`, `user`, and the auth pattern are unchanged. Only `host` needs to be updated.
</Tip>

## 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](/email-api/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>
  **Note:**

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

## Migration checklist

<Steps>
  <Step title="Sign a BAA with Paubox">
    Required before go-live. Contact Paubox to initiate the Business Associate Agreement.
  </Step>

  <Step title="Create an account and verify your sending domain">
    Add your domain on the [Paubox Email API > Settings](https://next.paubox.com/emailapi/settings) page and complete the TXT record verification. See the [Quickstart guide](/email-api/quickstart) for step-by-step instructions.
  </Step>

  <Step title="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`).
  </Step>

  <Step title="Update base URL, auth header, and request body">
    Apply the changes shown in the [Key differences](#key-differences) table and [Send a single email](#send-a-single-email) section above.
  </Step>

  <Step title="Update SMTP credentials">
    If you use the SMTP path, update `host` to `smtp.paubox.com`. See [SMTP configuration](#smtp-configuration) above.
  </Step>

  <Step title="Remap or remove webhook handlers">
    Update your webhook endpoint using the [event mapping table](#webhook-event-mapping) above. Remove handlers for `click`, `spam_report`, `processed`, and `unsubscribe`.
  </Step>

  <Step title="Remove any code that disables TLS">
    Paubox enforces TLS on every message. Any `allowNonTLS: true` or equivalent settings should be removed.
  </Step>

  <Step title="Send a test message">
    Confirm delivery using the [Get message receipt](/email-api/message-receipt) endpoint with the `sourceTrackingId` returned from your test send.
  </Step>

  <Step title="Swap DNS records">
    Replace SendGrid SPF/DKIM records with the Paubox records shown in your Settings page.
  </Step>

  <Step title="Revoke SendGrid API keys">
    Once traffic has fully moved to Paubox, revoke your SendGrid API keys.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart guide" icon="rocket" href="/email-api/quickstart">
    Full setup walkthrough from account creation to first send
  </Card>

  <Card title="Webhooks reference" icon="webhook" href="/email-api/webhooks">
    Configure delivery event notifications
  </Card>

  <Card title="Batch send" icon="layer-group" href="/email-api/bulk-messages">
    Send up to 50 messages in a single request
  </Card>

  <Card title="SMTP API" icon="server" href="/email-api/smtp">
    Connect via SMTP instead of REST
  </Card>
</CardGroup>