Migrate from SendGrid in 10 minutes

Sandbox self-test

curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@mail.groundmail.dev",
    "to": "you@yourcompany.com",
    "subject": "Sandbox check",
    "text": "It works."
  }'

Merged SPF (example)

example.com.  TXT  "v=spf1 include:_spf.google.com include:spf.groundmail.dev ~all"

SendGrid

curl -X POST https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{ "to": [{ "email": "ada@example.com", "name": "Ada" }] }],
    "from": { "email": "no-reply@acme.com", "name": "Acme" },
    "reply_to": { "email": "support@acme.com" },
    "subject": "Your receipt",
    "content": [
      { "type": "text/plain", "value": "Thanks for your order." },
      { "type": "text/html", "value": "<p>Thanks for your order.</p>" }
    ],
    "categories": ["receipt"],
    "custom_args": { "order_id": "1234" }
  }'

Groundmail

curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-1234" \
  -d '{
    "from": { "email": "no-reply@acme.com", "name": "Acme" },
    "to": "ada@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your receipt",
    "text": "Thanks for your order.",
    "html": "<p>Thanks for your order.</p>",
    "tags": { "category": "receipt", "order_id": "1234" }
  }'

SendGrid (@sendgrid/mail)

import sgMail from "@sendgrid/mail";

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

await sgMail.send({
  to: "ada@example.com",
  from: "no-reply@acme.com",
  subject: "Your receipt",
  text: "Thanks for your order.",
  html: "<p>Thanks for your order.</p>",
});

Groundmail (npm install groundmail)

import { Groundmail } from "groundmail";

const gm = new Groundmail(process.env.GROUNDMAIL_API_KEY!);

const { id } = await gm.emails.send({
  from: "no-reply@acme.com",
  to: "ada@example.com",
  subject: "Your receipt",
  text: "Thanks for your order.",
  html: "<p>Thanks for your order.</p>",
});
// Store id (msg_...) to match webhook events to this send.

SendGrid dynamic template

{
  "from": { "email": "no-reply@acme.com" },
  "template_id": "YOUR_SENDGRID_TEMPLATE_ID",
  "personalizations": [{
    "to": [{ "email": "ada@example.com" }],
    "dynamic_template_data": { "name": "Ada", "reset_url": "https://acme.com/reset/abc" }
  }]
}

Groundmail template

{
  "from": "no-reply@acme.com",
  "to": "ada@example.com",
  "template": {
    "id": "password-reset",
    "variables": { "name": "Ada", "reset_url": "https://acme.com/reset/abc" }
  }
}

Node: one personalization per batch entry

const { data } = await gm.emails.batch(
  orders.slice(0, 100).map((order) => ({
    from: "no-reply@acme.com",
    to: order.email,
    template: { id: "order-shipped", variables: { name: order.name, tracking: order.tracking } },
  })),
);

for (const result of data) {
  if (result.error) console.error(result.index, result.error.message);
}

Go (go get github.com/Groundmail/groundmail-sdks/go)

import groundmail "github.com/Groundmail/groundmail-sdks/go"

client, err := groundmail.New(os.Getenv("GROUNDMAIL_API_KEY"))
if err != nil {
	log.Fatal(err)
}

result, err := client.Emails.Send(map[string]any{
	"from":    "no-reply@acme.com",
	"to":      "ada@example.com",
	"subject": "Your receipt",
	"html":    "<p>Thanks for your order.</p>",
})
if err != nil {
	log.Fatal(err)
}
log.Println(result["id"], result["status"])

Node handler (Next.js route, Fetch API)

import { verifyWebhookSignature } from "groundmail";

export async function POST(request: Request) {
  const rawBody = await request.text(); // verify before parsing
  const ok = verifyWebhookSignature(
    process.env.GROUNDMAIL_WEBHOOK_SECRET!,
    rawBody,
    request.headers.get("groundmail-signature"),
  );
  if (!ok) return new Response("invalid signature", { status: 401 });

  const event = JSON.parse(rawBody); // one event, not an array
  switch (event.type) {
    case "email.bounced":
    case "email.complained":
      await markUndeliverable(event.data.to, event.data.email_id);
      break;
    case "email.delivered":
      await markDelivered(event.data.email_id);
      break;
  }
  return new Response("ok");
}

bash (curl + jq)

#!/usr/bin/env bash
set -euo pipefail

for list in bounces spam_reports invalid_emails; do
  curl -s "https://api.sendgrid.com/v3/suppression/$list" \
    -H "Authorization: Bearer $SENDGRID_API_KEY" |
  jq -r '.[].email' |
  while read -r email; do
    curl -s -o /dev/null -w "%{http_code} $email\n" \
      -X POST https://api.groundmail.dev/suppressions \
      -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
      -H "Content-Type: application/json" \
      -d "$(jq -n --arg e "$email" --arg r "imported from SendGrid $list" '{email: $e, reason: $r}')"
  done
done