Migrate

Migrate from SendGrid to AgenticEmail

How the API maps

import sgMail from "@sendgrid/mail";

sgMail.setApiKey(process.env.SENDGRID_API_KEY);

await sgMail.send({
  to: "customer@example.com",
  from: "support@yourdomain.com",
  subject: "Thanks for reaching out",
  html: "<p>Hi there - an agent will follow up shortly.</p>",
});

import { AgenticEmail } from "agenticemail";

const client = new AgenticEmail({ apiKey: process.env.AGENTICEMAIL_API_KEY });

// Create the inbox once, then reuse inbox.id (it also receives replies).
const inbox = await client.inboxes.create({ username: "support" });

await client.messages.send({
  inboxId: inbox.id,
  to: "customer@example.com",
  subject: "Thanks for reaching out",
  html: "<p>Hi there - an agent will follow up shortly.</p>",
});

// SendGrid posts multipart/form-data for the whole domain.
app.post("/inbound", upload.none(), (req, res) => {
  const from = req.body.from;
  const subject = req.body.subject;
  const text = req.body.text; // parse the raw fields yourself
  res.sendStatus(200);
});

// Each inbox is a real address; inbound arrives as parsed JSON.
const { messages } = await client.messages.list({ inboxId: inbox.id });

for (const m of messages) {
  console.log(m.from, m.subject, m.text); // no MIME parsing required
}

// Or push instead of poll: register a signed webhook, or open the
// WebSocket stream at /v1/events for message.received events.

Migration steps

1. 1

   Install the SDK and set your key

   npm install agenticemail and set AGENTICEMAIL_API_KEY. Grab the key from the dashboard; scope it to specific inboxes if you want least-privilege per agent.

2. 2

   Create an inbox to replace your verified sender

   Where SendGrid used a verified `from` address, create an inbox with client.inboxes.create(). Omit the domain to use the shared sending domain, or add your own domain first.

3. 3

   Swap the send call

   Replace sgMail.send(...) with client.messages.send({ inboxId, ... }). The to, subject, text, html, and attachment fields map directly.

4. 4

   Repoint inbound

   Replace Inbound Parse with a per-inbox webhook or the WebSocket stream, or poll client.messages.list(). Payloads arrive as parsed JSON, so you can delete your MIME parsing code.

5. 5

   Move deliverability, then cut over

   Add your domain to AgenticEmail; SPF, DKIM, and DMARC are generated and verified. Run a share of traffic through both providers, compare deliverability, then flip fully.

What is different

• The sender model is different: SendGrid sends from a verified address, AgenticEmail sends from an inbox that also receives - so replies land in the same mailbox instead of a separate Inbound Parse route.
• AgenticEmail does not host Dynamic Templates. Render your HTML in your app (React Email, Handlebars, etc.) and pass it as `html`.
• SendGrid Marketing Campaigns has no direct equivalent. AgenticEmail is transactional and conversational, not a bulk campaign tool - keep a marketing ESP if you send campaigns.
• Do it gradually: run a percentage of sends through AgenticEmail alongside SendGrid, compare delivery and bounce rates, then complete the cutover.

Frequently asked questions

How hard is it to migrate from SendGrid?

The send call maps almost one-to-one. The main change is sending from an inbox instead of a verified `from` string, which also gives you inbound replies for free. Most migrations are a swap of SDK calls plus repointing your inbound handler.

Can I keep my existing domain?

Yes. Add your domain to AgenticEmail and SPF, DKIM, and DMARC are generated and verified for you, optionally pushed to Cloudflare. You can keep sending from your own domain.

Does AgenticEmail replace SendGrid Inbound Parse?

Yes, and per inbox rather than per domain. Each inbox is a real address that delivers parsed JSON via webhook, WebSocket, or messages.list, instead of one domain-wide MIME firehose you have to parse.

What about SendGrid templates and marketing email?

AgenticEmail focuses on transactional and two-way agent mail. Render templates in your app and pass HTML, and keep a dedicated marketing ESP if you also send campaigns.