SendGrid
Send through the Twilio SendGrid Mail Send API with the fullest field support of any adapter.
The SendGrid adapter calls the Twilio SendGrid Mail Send API over fetch — no extra dependency. It supports every EmailMessage field: recipients land in a personalizations entry, metadata becomes custom_args, and tags become categories.
@opencoredev/email-sdk/sendgridConfigure
Create an API key with Mail Send permission in the SendGrid dashboard and verify the sender identity or domain you use in from.
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).
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 headerSendGrid'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.
Verify from the CLI
SENDGRID_API_KEY="SG...." npx email-sdk doctor --adapter sendgridSENDGRID_API_KEY="SG...." npx email-sdk send \
--adapter sendgrid \
--from "Acme <hello@acme.com>" \
--to user@example.com \
--subject "SendGrid smoke test" \
--text "It works" \
--dry-runDrop --dry-run for one real send — account review and sender verification can block delivery even when the payload validates, and only a live send proves they are done.