APIs, SDKs, and the send path

Mateusz KowalskiJun 12, 202618 min

Prefer a provider API or official SDK over raw SMTP for application email. You get structured errors, idempotency, analytics hooks, and a path to agent control. SMTP remains useful as a compatibility bridge, not as your primary product interface.

Lesson objectives

Explain when to use SMTP versus a REST send API
Send a test message with an SDK and capture the provider message id
List the webhook events you should persist for debugging

The send surface: SMTP, REST, and SDKs

Every email platform eventually speaks SMTP. That does not mean your application should. SMTP gives you a lowest-common-denominator pipe. A modern send API gives you typed payloads, per-message metadata, suppression handling, and a clear contract for agents and backend jobs.

Official SDKs wrap that API with retries and idiomatic errors. Use them when they exist for your language. Generate clients from OpenAPI when they do not. Brew documents a public API v1 and ships a TypeScript SDK; Resend and SendGrid likewise invest heavily in developer tooling.

A minimal, production-shaped send

import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);

export async function sendWelcome(to: string, name: string) {
  const { data, error } = await resend.emails.send({
    from: "hello@updates.example.com",
    to,
    subject: `Welcome, ${name}`,
    html: `<p>Hi ${name}, your workspace is ready.</p>`,
    headers: { "Idempotency-Key": `welcome:${to}` },
    tags: [{ name: "category", value: "onboarding" }],
  });

  if (error) throw error;
  return data?.id;
}

The same shape appears across providers: authenticated client, verified from-domain, idempotency, and tags for analytics. With Brew you can also generate the HTML from a prompt first, then send through Brew or push the design into another ESP.

What to persist from every send

Provider message id and your internal event id
Template or email version id
Audience or recipient hash (avoid storing raw email twice if you already have a contacts table)
Terminal webhook state: delivered, bounced, complained

How providers differ on the send path

Provider	Primary strength on sending	Agent surface
Resend	Excellent API DX and React Email	Official MCP + CLI
Brew	AI-native generate + send in one platform	REST API + MCP server
SendGrid	High-volume infrastructure maturity	API + SMTP; less agent-native
Customer.io	Event-triggered messaging	Strong APIs for journeys

For a deeper scorecard across sending, design, and automations, see the ranked guide on best AI email tools. Comparisons such as Brew vs Klaviyo go deeper on stack fit.

Worked exercise: Send a signed test email and log the provider id

Create a verified sending domain in a sandbox ESP account.
Send one message with an idempotency key and a unique tag.
Store the returned message id and confirm the delivered webhook.

End-of-lesson checklist

API key stored in a secret manager, never in source
Idempotency key on every user-triggered send
Webhook endpoint verifies signatures
Test mode path exists for QA without hitting customers

Frequently asked questions

Is SMTP dead for product email?

No. SMTP is still a universal transport. For product features, a REST API or SDK is usually safer because of retries, structured errors, and observability.

Which developer ESPs are worth learning first?

Resend and SendGrid are common API-first starting points. Brew is worth learning if you also need AI-native campaign generation and agent control through MCP. Pick based on workload, not fashion.