Moving from SendGrid to Pharos

The order the work happens in.

1. 01

   Export the suppression list

   Pull every suppressed address out of SendGrid before anything else changes.

2. 02

   Verify the domain on Pharos

   Add four DNS records alongside the ones already there. Both providers stay authenticated.

3. 03

   Move the send call

   Point the application at POST /v1/send or the SMTP relay, behind whatever flag you use.

4. 04

   Ramp the traffic

   Move a share of sending across, watch the events, increase it. No cutover window is required.

5. 05

   Repoint the webhook and clean up DNS

   Move the event consumer, then remove the SendGrid records once nothing depends on them.

Steps two and three are reversible and can overlap for as long as you like. An SPF record may name both providers, DKIM selectors are independent of one another, and the single DMARC record does not change at any point. That is what makes a phased migration possible: there is no moment where the domain is authenticated for the new provider and not the old one.

Step 1 — export the suppression list.

Five endpoints, each paginated at a maximum of 500 records a page. Loop the offset until a page comes back short. If your account uses subusers, every subuser has its own suppression lists and needs its own pass with the on-behalf-of header — the parent account key does not return them.

# every list, one page at a time, 500 at a time
for list in bounces blocks spam_reports invalid_emails; do
  offset=0
  while :; do
    page=$(curl -sG "https://api.sendgrid.com/v3/suppression/$list" \
      -H "Authorization: Bearer $SENDGRID_API_KEY" \
      -d "limit=500" -d "offset=$offset")
    [ "$(echo "$page" | jq 'length')" -eq 0 ] && break
    echo "$page" | jq -r '.[].email' >> suppressions.txt
    offset=$((offset + 500))
  done
done

# global unsubscribes live on their own path
curl -sG "https://api.sendgrid.com/v3/suppression/unsubscribes" \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -d "limit=500" | jq -r '.[].email' >> suppressions.txt

sort -u suppressions.txt > suppressions-deduped.txt

Import the deduplicated file into the Pharos suppression list before the first send, not after it. Pharos adds to that list automatically on every hard bounce and every complaint, but it cannot know about the four years of them that happened somewhere else.

Pharos suppresses an address automatically on a hard bounce and on a complaint, keeps the list per account, and lets you export it again whenever you like — including on the way out, if this page ever needs writing in the other direction. The difference between a hard and a soft bounce decides which addresses end up on it.

Steps 3 and 4 — move the call, then the traffic.

The send call is plain HTTP. There is no SDK to install and nothing to import, which means the change in your application is a URL, a header and a body shape rather than a dependency.

curl -X POST https://api.pharos.email/v1/send \
  -H "Authorization: Bearer $PHAROS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4471" \
  -d '{
    "from": "receipts@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>"
  }'

If you would rather not touch application code at all, point your existing mailer at the SMTP relay on smtp.pharosinfra.net:587 with STARTTLS. Same pipeline, same events, and a migration that is four lines of configuration. The Idempotency-Key header matters more during a migration than at any other time: a retry across a half-switched deployment is exactly the situation that sends a password reset twice.

Then ramp. Send a percentage, read the events, raise it. There is no warmup requirement to satisfy here — the sending IPs are dedicated to Pharos and already have a reputation — but ramping is still how you find the template that renders wrong or the address list nobody had cleaned, at a volume where finding it is cheap.

When to stay on SendGrid.

Four reasons not to do any of the above. They are here because you would find them during the migration otherwise, and finding them then costs a great deal more than reading them now.

• You use Marketing Campaigns

  Pharos sends transactional mail only — the AUP says so, and the complaint threshold is written for it. A campaign builder, contact lists and segmentation have no equivalent here, and asking for one is asking for a different product.

• You depend on subusers

  Subusers give one account separate sending identities with separate reputations and separate API keys. Pharos scopes keys to a verified sending domain rather than to a sub-identity, which covers some of the same ground and not all of it. If you resell sending to your own customers, check this before anything else.

• You use Inbound Parse

  Receiving mail and posting it to your application is not something Pharos does. That stays where it is, or moves somewhere else, and it is worth deciding which before you delete an MX record.

• Your volume is genuinely enormous

  Pharos is a young gateway. If you are sending at a scale where a provider’s own capacity planning is your capacity planning, say so in the first email rather than discovering it at cutover.

Pharos carries transactional mail only — mail a recipient's own action caused. That single constraint is the reason for most of the gaps above, and it is written down in the acceptable use policy rather than discovered at suspension time.