Migrating from SendGrid to Sendpository

Or let your coding agent do the whole migration

Paste it in. It finds every SendGrid call, rewrites it, updates your webhook handler and switches over behind a flag you can flip back.

ClaudeGrokGeminiCursorCodex

Copy prompt

Show the promptHide the prompt

Switch this project's email from SendGrid to Sendpository. First run `npx sendpository@latest init` - it opens my browser for me to approve, saves the API key and installs the Sendpository skill - then follow the skill's migration guide (references/migrate.md). If you can't run commands, read https://www.sendpository.com/agents/sendpository/references/migrate.md instead.

1. API differences

2. Authentication differences

3. Domain setup

4. Webhooks

Event names

5. Error handling

6. Code migration

await fetch("https://api.sendgrid.com/v3/mail/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SENDGRID_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    personalizations: [{ to: [{ email: "customer@example.com" }] }],
    from: { email: "billing@yourdomain.com", name: "Acme" },
    subject: "Your receipt",
    content: [{ type: "text/html", value: "<p>Thanks for your order.</p>" }],
    categories: ["receipt"],
  }),
}); // 202, empty body

const res = await fetch("https://api.sendpository.com/v1/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SENDPOSITORY_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "receipt-10428",
  },
  body: JSON.stringify({
    from: "Acme <billing@mail.yourdomain.com>",
    to: ["customer@example.com"],
    subject: "Your receipt",
    html: "<p>Thanks for your order.</p>",
    text: "Thanks for your order.",
    tags: { type: "receipt" },
  }),
});

const body = await res.json();
if (!res.ok) throw new Error(`${body.error.type}: ${body.error.message}`);
console.log(body.id);

Watch out for

• A 202 with no body is gone - read the id from the JSON response and store it if you look messages up later.
• Personalizations that sent different content to several recipients in one call become separate messages, or one POST to /emails/batch with up to 100.
• Dynamic templates (template_id with dynamic_template_data) have no equivalent - render the HTML in your app before sending.
• Your event handler must accept a single JSON object, not an array.

7. Pricing

8. Things to test before switching

• Flatten any `personalizations` array. SendGrid's send body nests recipients and substitutions inside it; ours takes `to`, `cc` and `bcc` at the top level, so a multi-recipient send ported verbatim will send to nobody.
• Re-point domain authentication. SendGrid authenticates with CNAMEs aimed at their infrastructure, so your DKIM key lives with them; ours is a TXT record on your own apex. Leave theirs in place until our domain verifies.
• Rewrite Dynamic Template calls. There is no `template_id` on our send - render your Handlebars templates in your own code and post the resulting HTML.

• Send to a real Gmail and a real Outlook address and open Show original: SPF, DKIM and DMARC should all say PASS, with DKIM signed as your own domain.
• Send a message with an attachment and one with an inline image, and check both render.
• Trigger a bounce (an address at a domain you control with no mailbox) and confirm your webhook handler receives email.bounced and marks the address.
• Send the same request twice with one Idempotency-Key and confirm only one email arrives.
• Point a staging environment at the new API key first, and watch the Logs page for 4xx responses before switching production.
• Keep the old provider's DNS records until the new domain has verified and a day of production mail has been delivered - removing them first breaks mail still in flight.

Questions

Keep reading