Migrate from SendGrid to Postal

Add the domain in the dashboard and create the records it shows. Going by the names, Postal's records don't collide with SendGrid's, and both stay verified at the same time during the switch. If you already have a _dmarc, keep yours.

• Postal checks the records on its own for up to 72 hours and notifies you by webhook (domain.updated)
• Create an API key (it starts with ps_). For systems that only send, use a sending-only key, restricted to the domain

Postal does not accept the /v3/mail/send format: the call becomes POST /emails, with the fields at the top level. Below, the same email in both formats. If you use the SendGrid SDK, replace the sending with the Postal SDK (Node.js, PHP and Laravel) or with HTTP, which is JSON with the key in the Authorization header.

• SendGrid responds 202 Accepted; Postal responds 200 with the email's id. Keep the id: it is what shows up in webhooks and in GET /emails/{id}
• Several recipients in the same to form a single email in which everyone can see each other. For one email per person, use batch sending
• Repeating the call with the same Idempotency-Key does not duplicate the send

Before: SendGrid

POST https://api.sendgrid.com/v3/mail/send
Authorization: Bearer <SendGrid key>

{
  "personalizations": [{
    "to": [{ "email": "[email protected]", "name": "Ana" }],
    "custom_args": { "order_id": "10482" }
  }],
  "from": { "email": "[email protected]", "name": "Loja Exemplo" },
  "subject": "Your order #10482 is out for delivery",
  "content": [
    { "type": "text/plain", "value": "Order #10482 is on its way." },
    { "type": "text/html", "value": "<p>Order <b>#10482</b> is on its way.</p>" }
  ],
  "categories": ["shipping"]
}

After: Postal

POST https://api.postal.so/emails
Authorization: Bearer ps_your_key
Idempotency-Key: order-10482-shipped

{
  "from": "Loja Exemplo <[email protected]>",
  "to": ["Ana <[email protected]>"],
  "subject": "Your order #10482 is out for delivery",
  "text": "Order #10482 is on its way.",
  "html": "<p>Order <b>#10482</b> is on its way.</p>",
  "tags": [
    { "name": "category", "value": "shipping" },
    { "name": "order_id", "value": "10482" }
  ]
}

In code

- const sgMail = require('@sendgrid/mail');- sgMail.setApiKey(process.env.SENDGRID_API_KEY);- await sgMail.send({-   to: '[email protected]',-   from: '[email protected]',-   subject, html,- });+ import { Postal } from 'postal-so';+ const postal = new Postal(); // reads POSTAL_API_KEY+ await postal.emails.send({+   from: 'Loja Exemplo <[email protected]>',+   to: '[email protected]',+   subject, html,+ });

The table applies to new code and works as a checklist of what your system uses today. The rows that change how you build the email are the ones for batch recipients, categories and custom arguments.

If you send over SMTP, you rewrite nothing: you change the server, the user and the password. The fixed user is postal, not apikey. Postal also accepts 2465 (TLS) and 2587 (STARTTLS) for networks that block the usual ports.

• The X-SMTPAPI header (category, unique_args, sub, send_at, filters…) is not interpreted by Postal: it goes through as an ordinary header. Whatever you use it for has to move to the API
• Recipients are the envelope ones (RCPT TO), up to 50 per message. Anyone who doesn't appear in To or Cc is treated as Bcc
• Postal's SMTP has no tags, scheduling or templates. Quotas, suppression list, events and webhooks are the same as the API's
• Messages up to 40 MB; Postal replies 250 2.0.0 OK queued as <id>, and the id is the email's id in the API

- Server: smtp.sendgrid.net- Port: 587 (or 25, 2525, 465)- User: apikey- Password: the SendGrid API key+ Server: smtp.postal.so+ Port: 465 (direct TLS) or 587 (STARTTLS)+ User: postal+ Password: the Postal API key (ps_…)

SendGrid sends the Event Webhook signed with a public key (ECDSA); Postal signs with one secret per endpoint, following the Standard Webhooks standard. The body changes too: one event per request, with the email inside data.

import express from 'express';
import { verifyWebhook, PostalWebhookVerificationError } from 'postal-so';

const app = express();
// The body must arrive raw (Buffer) so the signature matches.
app.post('/webhooks/postal', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = verifyWebhook(req.body, req.headers, process.env.POSTAL_WEBHOOK_SECRET);
    if (event.type === 'email.bounced') {
      // remove the address
    }
    res.sendStatus(200);
  } catch (error) {
    if (error instanceof PostalWebhookVerificationError) {
      return res.sendStatus(400);
    }
    throw error;
  }
});

The suppression list first, so you don't write to people who shouldn't receive anything. Then the contacts, if you use the marketing audience. SendGrid exports each type of suppression through its own route; Postal has a single list.

• Do the contact import after the suppression: addresses already on the suppression list are ignored and don't count toward the plan's contact limit
• Marketing broadcasts and automations need to be recreated in Postal; what you bring over is the contacts and the content

curl -X POST https://api.postal.so/suppressions/batch/add \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["[email protected]", "[email protected]"]}'

With the domain verified on both, move one flow at a time. Invitations, password resets and codes should go out through a single path at a time.

• IDs belong to each platform: record which provider each email went out through and keep receiving events from SendGrid for what went out through it
• Use tags (for example, provider: postal) to tell the new emails apart in webhooks
• New accounts start with a ceiling of 500 emails a day, which grows with the account reputation, and sending pauses with permanent bounces above 3% to 5%, depending on the level, or complaints above 0.3%: raise the volume in stages