Docs

Authorization: Bearer gm_…

curl https://mail.yourco.com/api/v1/send \
  -H "Authorization: Bearer $GENTLEMAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "support@yourco.com",
    "to": ["Ada Lovelace <ada@example.com>"],
    "subject": "Your order has shipped",
    "text": "It should arrive on Friday.",
    "html": "<p>It should arrive on <b>Friday</b>.</p>"
  }'

{ "id": "…", "thread_id": "…", "from": "support@yourco.com", "status": "sent" }

POST https://agents.yourco.com/mail
Content-Type: application/json
User-Agent: GentleMail-Webhooks/1
X-GentleMail-Event: message.received
X-GentleMail-Delivery: 6f1c2e4a-…
X-GentleMail-Timestamp: 1794580000
X-GentleMail-Signature: v1=5f2c…

{
  "id": "6f1c2e4a-…",
  "event": "message.received",
  "created_at": "2026-11-13T09:46:02.000Z",
  "data": {
    "id": "…",
    "thread_id": "…",
    "mailbox": { "id": "…", "address": "invoices@yourco.com" },
    "folder": "inbox",
    "direction": "inbound",
    "from": { "name": "Acme Billing", "address": "billing@acme.com" },
    "to": [{ "name": "", "address": "invoices@yourco.com" }],
    "cc": [],
    "reply_to": null,
    "subject": "Invoice INV-2041",
    "date": "2026-11-13T09:46:00.000Z",
    "snippet": "Please find the November invoice attached.",
    "text": "Please find the November invoice attached.\n…",
    "text_truncated": false,
    "has_html": true,
    "attachments": [{
      "id": "…", "filename": "invoice-2041.pdf", "content_type": "application/pdf",
      "size": 48213, "inline": false,
      "url": "https://mail.yourco.com/api/v1/attachments/…"
    }],
    "url": "https://mail.yourco.com/api/v1/messages/…"
  }
}

async function verify(request: Request, secret: string) {
  const body = await request.text();
  const ts = request.headers.get("X-GentleMail-Timestamp") ?? "";
  const sig = request.headers.get("X-GentleMail-Signature") ?? "";

  // Refuse anything older than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return null;

  const key = await crypto.subtle.importKey(
    "raw", new TextEncoder().encode(secret),
    { name: "HMAC", hash: "SHA-256" }, false, ["sign"],
  );
  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${ts}.${body}`));
  const expected = "v1=" + [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");

  // Compare in constant time.
  if (expected.length !== sig.length) return null;
  let diff = 0;
  for (let i = 0; i < sig.length; i++) diff |= expected.charCodeAt(i) ^ sig.charCodeAt(i);
  return diff === 0 ? JSON.parse(body) : null;
}

export default {
  async fetch(request: Request, env: Env) {
    const event = await verify(request, env.WEBHOOK_SECRET);
    if (!event) return new Response("Bad signature", { status: 401 });
    if (event.event !== "message.received") return new Response("Ignored");

    await handle(event.data, env); // one of the recipes below
    return new Response("OK");
  },
};

async function handle(mail, env) {
  for (const file of mail.attachments) {
    if (file.content_type !== "application/pdf") continue;
    const pdf = await fetch(file.url, {
      headers: { Authorization: `Bearer ${env.GENTLEMAIL_KEY}` },
    });
    const key = `${mail.id}/${file.filename}`;
    await env.INVOICE_FILES.put(key, await pdf.arrayBuffer());
    await env.PAYMENTS.send({ key, from: mail.from.address, subject: mail.subject });
  }
}

async function handle(mail, env) {
  await fetch(env.SLACK_WEBHOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `New email to ${mail.mailbox.address} from ${mail.from.name || mail.from.address}\n*${mail.subject}*\n${mail.snippet}`,
    }),
  });
}

async function handle(mail, env) {
  await fetch(`https://api.telegram.org/bot${env.TELEGRAM_TOKEN}/sendMessage`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      chat_id: env.TELEGRAM_CHAT_ID,
      text: `${mail.mailbox.address}\nFrom: ${mail.from.name || mail.from.address}\n${mail.subject}\n\n${mail.snippet}`,
    }),
  });
}

async function handle(mail, env) {
  const sender = mail.from.address.toLowerCase();
  if (/^(no-?reply|mailer-daemon|postmaster)@/.test(sender)) return;
  if (await env.REPLIED.get(sender)) return;

  await fetch("https://mail.yourco.com/api/v1/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${env.GENTLEMAIL_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      from: mail.mailbox.address,
      reply_to_message_id: mail.id,
      text: "Thanks for your message. I'm away until Monday. For anything urgent, write to team@yourco.com.",
    }),
  });
  await env.REPLIED.put(sender, "1", { expirationTtl: 7 * 24 * 3600 });
}

{ "error": { "code": "mailbox_not_allowed", "message": "This key can't send from sales@yourco.com." } }