SendGrid

Send through the Twilio SendGrid Mail Send API with the fullest field support of any adapter.

Capabilities

Repeated headers	Idempotency	Scheduling	Personalized
No	`none`	Yes	`native`

These values come from the adapter's exported capabilities declaration. The field support matrix covers normalized message fields.

The SendGrid adapter calls the Twilio SendGrid Mail Send API with plain fetch. It supports every EmailMessage field: recipients land in a personalizations entry, metadata becomes custom_args, and tags become categories.

SendGrid@opencoredev/email-sdk/sendgrid

Provider docs

Configure

Create an API key with Mail Send permission in the SendGrid dashboard and verify the sender identity or domain you use in from.

lib/email.ts

import { createEmailClient } from "@opencoredev/email-sdk";
import { sendgrid } from "@opencoredev/email-sdk/sendgrid";

export const email = createEmailClient({
  adapters: [sendgrid({ apiKey: process.env.SENDGRID_API_KEY! })],
});

Prop

Type

Send

Everything maps: cc, bcc, headers, attachments, tags, metadata, and even multiple replyTo addresses (sent as reply_to_list). sendAt schedules the send natively as send_at (a Unix timestamp in seconds); SendGrid accepts at most 72 hours in the future.

const result = await email.send({
  from: "Acme <security@acme.com>",
  to: [{ email: "user@example.com", name: "Ada" }],
  subject: "Reset your password",
  html: "<p>Click the link below to reset your password.</p>",
  text: "Use the link below to reset your password.",
  metadata: { userId: "user_123", flow: "password-reset" },
  tags: [{ name: "type", value: "password-reset" }],
});

console.log(result.id); // SendGrid message id from the x-message-id header

SendGrid's send endpoint returns 202 Accepted with an empty body, so the adapter reads result.id from the x-message-id response header. metadata values arrive in SendGrid event webhooks as custom_args; tag values arrive as categories.

Personalized sends

SendGrid implements native sendPersonalized, so the adapter emits one personalizations entry per recipient and sends the complete set in one request.

await email.sendPersonalized({
  message: {
    from: "Acme <hello@acme.com>",
    subject: "Hi %recipient.name%",
    html: '<a href="https://acme.com/unsub?id=%recipient.id%">Unsubscribe</a>',
  },
  recipients: [
    { to: "ada@example.com", variables: { name: "Ada", id: "u_1" } },
    { to: "linus@example.com", variables: { name: "Linus", id: "u_2" } },
  ],
});

Verify from the CLI

SENDGRID_API_KEY="SG...." npx --package @opencoredev/email-sdk email-sdk doctor --adapter sendgrid

SENDGRID_API_KEY="SG...." npx --package @opencoredev/email-sdk email-sdk send \
  --adapter sendgrid \
  --from "Acme <hello@acme.com>" \
  --to user@example.com \
  --subject "SendGrid smoke test" \
  --text "It works" \
  --dry-run

Drop --dry-run for one real send. SendGrid account review and sender verification can block delivery even when the payload validates, and only a live send proves they are done.

Compare SendGrid with other providers

Side-by-side message-field support from the SDK capability matrix, with working code for both adapters:

Frequently asked questions

Does Email SDK support SendGrid?

Yes. Email SDK ships a SendGrid adapter imported from @opencoredev/email-sdk/sendgrid. You keep your SendGrid account and credentials; the SDK adds message validation, typed errors, and no-network test adapters around the same send() call used for every other provider.

Which message fields does the SendGrid adapter support?

SendGrid supports every normalized message field: CC recipients, BCC recipients, Reply-To address, Custom headers, Attachments, Tags, Metadata, and Scheduled sending (sendAt).

Can SendGrid schedule email for later with Email SDK?

Yes. Set sendAt on the message and the SendGrid adapter passes the scheduled time to the provider.

Does the SendGrid adapter support idempotent sends?

No. SendGrid has no provider-side idempotency, so a retried send can be delivered twice. Deduplicate in your own queue before retrying.