███████╗███████╗███╗   ██╗██████╗  ██████╗ ██████╗ ██╗██████╗
██╔════╝██╔════╝████╗  ██║██╔══██╗██╔════╝ ██╔══██╗██║██╔══██╗
███████╗█████╗  ██╔██╗ ██║██║  ██║██║  ███╗██████╔╝██║██║  ██║
╚════██║██╔══╝  ██║╚██╗██║██║  ██║██║   ██║██╔══██╗██║██║  ██║
███████║███████╗██║ ╚████║██████╔╝╚██████╔╝██║  ██║██║██████╔╝
╚══════╝╚══════╝╚═╝  ╚═══╝╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝╚═════╝

npm install @sendgrid/mail        # sending email
npm install @sendgrid/client      # raw Web API v3 (suppressions, templates, stats)
npm install @sendgrid/eventwebhook   # Event Webhook signature verification

// lib/sendgrid.ts
import sgMail from "@sendgrid/mail";

if (!process.env.SENDGRID_API_KEY) {
  throw new Error("SENDGRID_API_KEY is not set");
}
sgMail.setApiKey(process.env.SENDGRID_API_KEY);

export { sgMail };
export const FROM = process.env.SENDGRID_FROM_EMAIL!; // must be a verified sender / authenticated domain

// app/api/email/welcome/route.ts
import { NextRequest } from "next/server";
import { sgMail, FROM } from "@/lib/sendgrid";

export async function POST(req: NextRequest) {
  const { to, userName, dashboardUrl } = await req.json();

  try {
    await sgMail.send({
      to,
      from: FROM,
      templateId: process.env.SENDGRID_WELCOME_TEMPLATE_ID!, // "d-..."
      dynamicTemplateData: {
        userName,
        dashboardUrl,
        year: new Date().getFullYear(),
      },
    });
    return Response.json({ ok: true });
  } catch (error: any) {
    // SendGrid surfaces field-level errors in error.response.body.errors
    const body = error?.response?.body;
    console.error("sendgrid error", body ?? error);
    return Response.json({ error: body?.errors ?? "send failed" }, { status: 502 });
  }
}

await sgMail.send({
  to: "ops@client.example",
  from: FROM,
  subject: "Nightly job failed",
  text: "The reconciliation job exited non-zero. Check the logs.",
  html: "<p>The reconciliation job exited non-zero. Check the logs.</p>",
});

await sgMail.send(
  {
    to: ["a@example.com", "b@example.com"],
    from: FROM,
    templateId: process.env.SENDGRID_DIGEST_TEMPLATE_ID!,
    dynamicTemplateData: { week: "2026-W25" },
  },
  /* isMultiple */ true,
);

# Porkbun DNS records
# DKIM / return-path: add the 3 CNAMEs exactly as SendGrid lists them, e.g.
#   Type: CNAME  Host: s1._domainkey  Target: s1.domainkey.uXXXX.wlYYY.sendgrid.net
#   Type: CNAME  Host: s2._domainkey  Target: s2.domainkey.uXXXX.wlYYY.sendgrid.net
#   Type: CNAME  Host: em1234         Target: uXXXX.wlYYY.sendgrid.net
#
# DMARC (author this yourself — start at p=none and watch reports):
#   Type: TXT  Host: _dmarc  Value: v=DMARC1; p=none; rua=mailto:dmarc@client.example; fo=1

// app/api/webhooks/sendgrid/route.ts  (Next.js App Router — Node runtime)
import { EventWebhook, EventWebhookHeader } from "@sendgrid/eventwebhook";
import { NextRequest } from "next/server";

export const runtime = "nodejs";        // ECDSA verify needs Node crypto, not edge
export const dynamic = "force-dynamic";

interface SgEvent {
  email: string;
  event:
    | "delivered" | "bounce" | "dropped" | "deferred"
    | "open" | "click" | "spamreport" | "unsubscribe";
  timestamp: number;
  sg_event_id: string;
  reason?: string;
  url?: string;
}

export async function POST(req: NextRequest) {
  // 1) Read the RAW body — do not JSON.parse before verifying.
  const rawBody = await req.text();

  const publicKey = process.env.SENDGRID_WEBHOOK_PUBLIC_KEY;
  const signature = req.headers.get(EventWebhookHeader.SIGNATURE());   // X-Twilio-Email-Event-Webhook-Signature
  const timestamp = req.headers.get(EventWebhookHeader.TIMESTAMP());   // X-Twilio-Email-Event-Webhook-Timestamp

  if (!publicKey || !signature || !timestamp) {
    return new Response("missing signature material", { status: 400 });
  }

  // 2) Verify the ECDSA signature over (timestamp + rawBody).
  const ew = new EventWebhook();
  const ecKey = ew.convertPublicKeyToECDSA(publicKey);
  const valid = ew.verifySignature(ecKey, rawBody, signature, timestamp);
  if (!valid) {
    return new Response("invalid signature", { status: 403 });
  }

  // 3) Now it's safe to parse and process the batch.
  const events: SgEvent[] = JSON.parse(rawBody);
  for (const e of events) {
    switch (e.event) {
      case "delivered":
        // mark delivered in DB
        break;
      case "bounce":
      case "dropped":
        // hard failure — add to your local suppression mirror, stop sending
        await suppressLocally(e.email, e.reason);
        break;
      case "spamreport":
      case "unsubscribe":
        // honor opt-out — never email again
        await markUnsubscribed(e.email);
        break;
      case "open":
      case "click":
        // engagement analytics (e.url for clicks)
        break;
    }
  }

  // 4) ACK fast. SendGrid retries non-2xx; 2xx stops retries.
  return new Response(null, { status: 204 });
}

declare function suppressLocally(email: string, reason?: string): Promise<void>;
declare function markUnsubscribed(email: string): Promise<void>;

// lib/sendgrid-suppressions.ts
import client from "@sendgrid/client";

client.setApiKey(process.env.SENDGRID_API_KEY!);

/** Remove an address from the global bounce list (e.g. after a typo fix). */
export async function clearBounce(email: string): Promise<void> {
  await client.request({
    method: "DELETE",
    url: `/v3/suppression/bounces/${encodeURIComponent(email)}`,
  });
}

/** Check whether an address is on the global unsubscribe list. */
export async function isUnsubscribed(email: string): Promise<boolean> {
  const [, body] = await client.request({
    method: "GET",
    url: "/v3/suppression/unsubscribes",
    qs: { email },
  });
  return Array.isArray(body) && body.length > 0;
}

// app/api/inbound/route.ts  — SendGrid posts multipart/form-data
import { NextRequest } from "next/server";

export const runtime = "nodejs";

export async function POST(req: NextRequest) {
  const form = await req.formData();
  const from = String(form.get("from") ?? "");
  const subject = String(form.get("subject") ?? "");
  const text = String(form.get("text") ?? "");      // plain-text body
  const attachmentCount = Number(form.get("attachments") ?? 0);

  // route by +tag, file a ticket, persist attachments, etc.
  await handleInbound({ from, subject, text, attachmentCount });

  return new Response(null, { status: 200 });
}

declare function handleInbound(msg: {
  from: string; subject: string; text: string; attachmentCount: number;
}): Promise<void>;

# Required
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxx   # create as "Restricted Access" (Mail Send only) where possible
SENDGRID_FROM_EMAIL=no-reply@mail.client.example   # verified sender / authenticated domain

# Event Webhook (Base64 public key from Mail Settings → Event Webhook → Signed)
SENDGRID_WEBHOOK_PUBLIC_KEY=MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...

# Dynamic template IDs (always start with d-)
SENDGRID_WELCOME_TEMPLATE_ID=d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SENDGRID_DIGEST_TEMPLATE_ID=d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx