@aidalinfo/email-mcp 0.1.1 → 0.3.0

package/dist/tools.js

@@ -1,37 +1,66 @@
 import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { z } from "zod";
 import { domainOf, isAllowed, normalizeAddress, UUID_RE } from "./config.js";
 import { Confirmations, digest } from "./confirm.js";
-import { AuditLogger, RateLimiter } from "./audit.js";
+import { AuditLogger } from "./audit.js";
 import { EmailError, errorResult, toEmailError } from "./errors.js";
+import { Quotas } from "./quota.js";
+import { IDEMPOTENCY_KEY_RE, SendLedger } from "./ledger.js";
+import { HARD_VARIABLE_LENGTH, TemplateCatalog } from "./templates.js";
+import { AttachmentResolver, DEFAULT_MAX_ATTACHMENT_BYTES, DEFAULT_MAX_ATTACHMENTS, HARD_MAX_ATTACHMENTS } from "./attachments.js";
+import { SMTP_MAX_EMAIL_BYTES } from "./smtp-client.js";
 export const MAX_SUBJECT = 200;
 export const MAX_TEXT = 100_000;
 export const MAX_HTML = 200_000;
+export const MAX_SUPPRESSION_LOOKUPS = 20;
+/** TEM refuses an email above 2 MB through its API (not raisable); kept a little under for the JSON envelope. */
+export const API_MAX_EMAIL_BYTES = 1_900_000;
 /** Above this, the preview shows the start of the HTML only (the digest still covers all of it). */
 const PREVIEW_HTML = 20_000;
 export const SERVER_INSTRUCTIONS = "Sends email from ONE fixed sender (set by the operator, not by you) to an allowlist of recipients, through Scaleway Transactional Email. " +
-    "Call email_config first to see the sender, the allowed recipients and the remaining hourly quota. " +
-    "email_send works in two steps: without confirmToken it only previews (nothing is sent) and returns a token; show the preview to the human, " +
-    "and only after their explicit approval call email_send again with the SAME arguments plus confirmToken. Never confirm on your own initiative. " +
+    "Call email_config first to see the sender, the recipients you may write to, your quotas, templates and attachment sources. " +
+    "Sequence: email_preview (nothing is sent, returns a confirmToken) → show the preview to the human and wait for their explicit approval → " +
+    "email_send with the SAME arguments, the SAME idempotency_key and the confirmToken → email_status to follow delivery. " +
+    "Never confirm on your own initiative. Never reuse an idempotency_key for another message; after an unknown_outcome, check email_status before anything else. " +
     "Recipients outside the allowlist are refused — do not try to work around it.";
-export function createContext(config, tem) {
+export const NO_ATTACHMENTS = { sources: [], maxCount: DEFAULT_MAX_ATTACHMENTS, maxTotalBytes: DEFAULT_MAX_ATTACHMENT_BYTES, types: [] };
+export function localClient(config) {
+    return { id: "local", maxPerHour: config.maxPerHour, maxPerDay: config.maxPerDay, templatesOnly: false };
+}
+export function createService(config, tem, opts = {}) {
     return {
         config,
         tem,
+        smtp: opts.smtp,
         confirmations: new Confirmations(),
         audit: new AuditLogger(config.auditFile),
-        limiter: new RateLimiter(config.maxPerHour),
+        quotas: new Quotas(config),
+        ledger: new SendLedger(config.stateDir ? join(config.stateDir, "ledger.json") : undefined),
+        templates: new TemplateCatalog(config.templatesDir),
+        attachments: new AttachmentResolver(opts.attachments ?? NO_ATTACHMENTS, opts.fetchImpl),
+        multiClient: !!opts.multiClient,
+        webhookConfigured: !!opts.webhookConfigured,
         killSwitchActive: () => !!config.killSwitchFile && existsSync(config.killSwitchFile),
     };
 }
+/** Stdio: one implicit client, `local`. */
+export function createContext(config, tem, opts = {}) {
+    return { ...createService(config, tem, opts), client: localClient(config) };
+}
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const json = (v) => "```json\n" + JSON.stringify(v, null, 2) + "\n```";
 const fence = (s) => {
     const ticks = "`".repeat(Math.max(3, ...[...s.matchAll(/`+/g)].map((m) => m[0].length + 1)));
     return `${ticks}\n${s}\n${ticks}`;
 };
-/** Validates the arguments into the exact message that will be sent. Throws on any guard. */
-export function buildMessage(config, a) {
+const allowedFor = (ctx, address) => isAllowed(ctx.config.allowlist, address) && (!ctx.client.allowlist || isAllowed(ctx.client.allowlist, address));
+/** Validates the arguments into the exact message that will be sent, and how it will leave. Throws on any guard. */
+export async function buildMessage(ctx, a) {
+    const { config } = ctx;
+    if (!IDEMPOTENCY_KEY_RE.test(a.idempotency_key ?? "")) {
+        throw new EmailError("invalid_request", "invalid_request: idempotency_key is required (8 to 128 characters among letters, digits and . _ : -)");
+    }
     const seen = new Set();
     const norm = (list, field) => list.map((raw) => {
         const addr = normalizeAddress(raw);
@@ -49,20 +78,69 @@ export function buildMessage(config, a) {
     if (seen.size > config.maxRecipients) {
         throw new EmailError("invalid_request", `invalid_request: ${seen.size} recipients, the maximum is ${config.maxRecipients} (EMAIL_MAX_RECIPIENTS)`);
     }
-    const denied = [...seen].filter((r) => !isAllowed(config.allowlist, r));
+    const denied = [...seen].filter((r) => !allowedFor(ctx, r));
     if (denied.length) {
-        throw new EmailError("recipient_not_allowed", `recipient_not_allowed: ${denied.join(", ")} not in EMAIL_ALLOWED_RECIPIENTS — nothing was sent`);
+        throw new EmailError("recipient_not_allowed", `recipient_not_allowed: ${denied.join(", ")} not allowed for this client — nothing was sent`);
     }
-    if (!a.subject.trim())
+    let subject, body, html, template;
+    if (a.template) {
+        if (a.subject !== undefined || a.text !== undefined || a.html !== undefined) {
+            throw new EmailError("invalid_request", "invalid_request: give either a template or subject/text/html, not both");
+        }
+        ({ subject, text: body, html } = ctx.templates.render(ctx.client.id, a.template.name, a.template.version, a.template.variables ?? {}));
+        template = `${a.template.name}@${a.template.version}`;
+    }
+    else {
+        if (ctx.client.templatesOnly)
+            throw new EmailError("refused", `refused: client "${ctx.client.id}" may only send templates — see email_templates`);
+        subject = a.subject ?? "";
+        body = a.text ?? "";
+        html = a.html;
+    }
+    if (!subject.trim())
         throw new EmailError("invalid_request", "invalid_request: empty subject");
     // a line break in a header value is how header injection starts
-    if (/[\u0000-\u001f\u007f]/.test(a.subject))
+    if (/[\u0000-\u001f\u007f]/.test(subject))
         throw new EmailError("invalid_request", "invalid_request: the subject must not contain line breaks or control characters");
-    if (!a.text.trim())
+    if (subject.length > MAX_SUBJECT)
+        throw new EmailError("invalid_request", `invalid_request: subject longer than ${MAX_SUBJECT} characters`);
+    if (!body.trim())
         throw new EmailError("invalid_request", "invalid_request: empty text body (a plain-text version is always required)");
-    if (a.html !== undefined && !a.html.trim())
+    if (body.length > MAX_TEXT)
+        throw new EmailError("invalid_request", `invalid_request: text body longer than ${MAX_TEXT} characters`);
+    if (html !== undefined && !html.trim())
         throw new EmailError("invalid_request", "invalid_request: html is empty — omit it instead");
-    return { from: config.from, replyTo: config.replyTo, to, cc, subject: a.subject, text: a.text, html: a.html };
+    if (html !== undefined && html.length > MAX_HTML)
+        throw new EmailError("invalid_request", `invalid_request: HTML body longer than ${MAX_HTML} characters`);
+    const files = await ctx.attachments.resolve(ctx.client.id, a.attachments ?? []);
+    const msg = {
+        from: config.from,
+        replyTo: config.replyTo,
+        to,
+        cc,
+        subject,
+        text: body,
+        html,
+        template,
+        attachments: files.map(({ name, type, size, sha256 }) => ({ name, type, size, sha256 })),
+    };
+    return { msg, files, via: viaFor(ctx, msg) };
+}
+/** The TEM API up to its 2 MB, SMTP above (EMAIL_SEND_VIA=auto), or the one transport the operator chose. */
+function viaFor(ctx, msg) {
+    const size = estimatedSize(msg);
+    const mode = ctx.config.sendVia;
+    if (mode === "api" || (mode === "auto" && size <= API_MAX_EMAIL_BYTES)) {
+        if (size > API_MAX_EMAIL_BYTES) {
+            throw new EmailError("invalid_request", `invalid_request: about ${size} bytes once encoded, above the ${API_MAX_EMAIL_BYTES}-byte limit of the TEM API (EMAIL_SEND_VIA=api) — lighten the attachments, or let the operator enable SMTP (EMAIL_SEND_VIA=auto)`);
+        }
+        return "api";
+    }
+    if (!ctx.smtp)
+        throw new EmailError("capability_unavailable", "capability_unavailable: this email needs SMTP (above the 2 MB of the TEM API) and SMTP is not configured");
+    if (size > SMTP_MAX_EMAIL_BYTES)
+        throw new EmailError("invalid_request", `invalid_request: about ${size} bytes once encoded, above the ${SMTP_MAX_EMAIL_BYTES}-byte limit of TEM over SMTP`);
+    return "smtp";
 }
 function header(m) {
     const from = m.from.name ? `${m.from.name} <${m.from.email}>` : m.from.email;
@@ -70,99 +148,310 @@ function header(m) {
         .filter(Boolean)
         .join("\n");
 }
+/** Bytes on the wire, roughly: bodies plus base64-encoded attachments. */
+const estimatedSize = (m) => Buffer.byteLength(m.subject) + Buffer.byteLength(m.text) + (m.html ? Buffer.byteLength(m.html) : 0) + m.attachments.reduce((n, a) => n + Math.ceil(a.size / 3) * 4, 0);
+const killSwitchError = (ctx) => new EmailError("refused", `refused: sending is disabled by the kill switch${ctx.config.killSwitchFile ? ` (${ctx.config.killSwitchFile} exists)` : ""}`);
+/** Kill switch, sender domain, quotas: the server-side state a confirmation is bound to. */
+async function checkSendable(ctx) {
+    const { config } = ctx;
+    if (ctx.killSwitchActive())
+        throw killSwitchError(ctx);
+    const domain = await ctx.tem.findDomain(domainOf(config.from.email));
+    if (!domain) {
+        throw new EmailError("domain_not_ready", `domain_not_ready: ${domainOf(config.from.email)} is not a TEM domain of project ${config.projectId} (${config.region})`);
+    }
+    if (domain.status !== "checked") {
+        throw new EmailError("domain_not_ready", `domain_not_ready: TEM domain ${domain.name} is "${domain.status}", it must be "checked" (SPF/DKIM verified) before sending`);
+    }
+    ctx.quotas.check(ctx.client.id, ctx.client);
+    return domain;
+}
+const bindingOf = (ctx, domain, key, msg) => ({
+    tool: "email_send",
+    state: { domainId: domain.id, status: domain.status },
+    plan: { client: ctx.client.id, idempotencyKey: key, msg },
+});
+/** A key already in the ledger: same message and sent → the earlier result; anything else → refused. */
+function priorSend(prior, messageDigest) {
+    if (prior.digest !== messageDigest) {
+        throw new EmailError("idempotency_conflict", "idempotency_conflict: this idempotency_key was already used for a different message — use a new key for a new message");
+    }
+    if (prior.state === "in_flight")
+        throw new EmailError("idempotency_conflict", "idempotency_conflict: a send with this idempotency_key is in progress");
+    if (prior.state === "unknown_outcome") {
+        throw new EmailError("unknown_outcome", "unknown_outcome: an earlier send with this idempotency_key may or may not have left — check email_status (idempotency_key) and the TEM console; do not send it again under another key without checking");
+    }
+    return text(`# Already sent — idempotency_key reused with the same message\n\nNothing was sent again. TEM email ids from the original send (${prior.updatedAt}):\n` +
+        json(prior.emailIds) +
+        "\n\nFollow delivery with email_status.");
+}
+const auditBase = (ctx, tool, a) => ({
+    tool,
+    client: ctx.client.id,
+    from: ctx.config.from.email,
+    approvalId: a.approvalId,
+    idempotencyKey: IDEMPOTENCY_KEY_RE.test(a.idempotency_key ?? "") ? a.idempotency_key : undefined,
+});
+const auditMsg = (m, messageDigest) => m
+    ? {
+        to: m.to,
+        cc: m.cc.length ? m.cc : undefined,
+        subject: m.subject,
+        template: m.template,
+        attachments: m.attachments.length ? m.attachments.map(({ type, size, sha256 }) => ({ type, size, sha256 })) : undefined,
+        messageDigest,
+    }
+    : {};
+const REFUSALS = ["invalid_request", "recipient_not_allowed", "domain_not_ready", "rate_limited", "refused", "confirmation_invalid", "idempotency_conflict", "attachment_refused", "capability_unavailable", "not_found"];
+export async function previewEmail(ctx, a) {
+    const tool = "email_preview";
+    const { config } = ctx;
+    let msg;
+    let messageDigest;
+    try {
+        let via;
+        ({ msg, via } = await buildMessage(ctx, a));
+        messageDigest = digest(msg);
+        const prior = ctx.ledger.find(ctx.client.id, a.idempotency_key);
+        if (prior)
+            return priorSend(prior, messageDigest);
+        const domain = await checkSendable(ctx);
+        const { token, expiresAt } = ctx.confirmations.issue(bindingOf(ctx, domain, a.idempotency_key, msg));
+        ctx.audit.log({ ...auditBase(ctx, tool, a), ...auditMsg(msg, messageDigest), result: "preview" });
+        const q = ctx.quotas.remaining(ctx.client.id, ctx.client);
+        const html = msg.html === undefined
+            ? ""
+            : `\n\nHTML body (${msg.html.length} characters${msg.html.length > PREVIEW_HTML ? `, first ${PREVIEW_HTML} shown` : ""}):\n${fence(msg.html.slice(0, PREVIEW_HTML))}`;
+        const files = msg.attachments.length
+            ? `\n\nAttachments (resolved by the server):\n${json(msg.attachments.map((f) => ({ name: f.name, type: f.type, bytes: f.size, sha256: f.sha256 })))}`
+            : "";
+        return text(`# Preview — nothing sent\n\n${fence(header(msg))}\n\nText body${msg.template ? ` (template ${msg.template})` : ""}:\n${fence(msg.text)}${html}${files}\n\n` +
+            json({
+                effectiveSender: config.from.email,
+                recipients: msg.to.length + msg.cc.length,
+                format: msg.html === undefined ? "text" : "text + html",
+                estimatedBytes: estimatedSize(msg),
+                transport: via === "smtp" ? "TEM over SMTP (above the 2 MB of the API)" : "TEM API",
+                messageDigest: `sha256:${messageDigest}`,
+                policy: { recipientsAllowed: true, senderDomain: domain.status, killSwitch: "inactive" },
+                quotaLeft: { client: q.client, server: q.global },
+                idempotencyKey: a.idempotency_key,
+            }) +
+            `\n\nShow this preview to the human. Only after their explicit approval, call email_send with the same arguments, ` +
+            `the same idempotency_key and confirmToken: "${token}" (valid until ${expiresAt}, single use).`);
+    }
+    catch (err) {
+        const e = toEmailError(err);
+        ctx.audit.log({ ...auditBase(ctx, tool, a), ...auditMsg(msg, messageDigest), result: REFUSALS.includes(e.code) ? "refused" : "failed", errorCode: e.code });
+        return errorResult(e);
+    }
+}
 export async function sendEmail(ctx, a) {
     const tool = "email_send";
     const { config } = ctx;
-    const base = { tool, from: config.from.email, approvalId: a.approvalId };
     let msg;
     let messageDigest;
     try {
-        if (ctx.killSwitchActive())
-            throw new EmailError("refused", `refused: sending is disabled by the kill switch (${config.killSwitchFile} exists)`);
-        msg = buildMessage(config, a);
+        if (!a.confirmToken)
+            throw new EmailError("confirmation_invalid", "confirmation_invalid: confirmToken is required — call email_preview first and get the human's approval");
+        const built = await buildMessage(ctx, a);
+        msg = built.msg;
         messageDigest = digest(msg);
-        const domain = await ctx.tem.findDomain(domainOf(config.from.email));
-        if (!domain) {
-            throw new EmailError("domain_not_ready", `domain_not_ready: ${domainOf(config.from.email)} is not a TEM domain of project ${config.projectId} (${config.region})`);
-        }
-        if (domain.status !== "checked") {
-            throw new EmailError("domain_not_ready", `domain_not_ready: TEM domain ${domain.name} is "${domain.status}", it must be "checked" (SPF/DKIM verified) before sending`);
-        }
-        if (ctx.limiter.remaining() <= 0) {
-            throw new EmailError("rate_limited", `rate_limited: ${config.maxPerHour} emails already sent in the last hour (EMAIL_MAX_PER_HOUR)`);
+        const prior = ctx.ledger.find(ctx.client.id, a.idempotency_key);
+        if (prior) {
+            const r = priorSend(prior, messageDigest);
+            ctx.audit.log({ ...auditBase(ctx, tool, a), ...auditMsg(msg, messageDigest), result: "replayed", temEmailIds: prior.emailIds });
+            return r;
         }
-        const binding = { tool, state: { domainId: domain.id, status: domain.status }, plan: msg };
-        const who = { to: msg.to, cc: msg.cc.length ? msg.cc : undefined, subject: msg.subject, messageDigest };
-        if (!a.confirmToken) {
-            const { token, expiresAt } = ctx.confirmations.issue(binding);
-            ctx.audit.log({ ...base, ...who, result: "preview" });
-            const html = msg.html === undefined
-                ? ""
-                : `\n\nHTML body (${msg.html.length} characters${msg.html.length > PREVIEW_HTML ? `, first ${PREVIEW_HTML} shown` : ""}):\n${fence(msg.html.slice(0, PREVIEW_HTML))}`;
-            return text(`# Preview — ${tool} (nothing sent yet)\n\n${fence(header(msg))}\n\nText body:\n${fence(msg.text)}${html}\n\n` +
-                `Message digest: sha256:${messageDigest} · quota left this hour: ${ctx.limiter.remaining()}/${config.maxPerHour}\n\n` +
-                `Show this preview to the human. Only after their explicit approval, call ${tool} again with the same arguments and ` +
-                `confirmToken: "${token}" (valid until ${expiresAt}, single use).`);
-        }
-        ctx.confirmations.verify(a.confirmToken, binding);
+        const domain = await checkSendable(ctx);
+        ctx.confirmations.verify(a.confirmToken, bindingOf(ctx, domain, a.idempotency_key, msg));
         // the switch may have been set while the human was reading the preview
         if (ctx.killSwitchActive())
-            throw new EmailError("refused", `refused: sending is disabled by the kill switch (${config.killSwitchFile} exists)`);
-        const release = ctx.limiter.reserve();
-        let emails;
+            throw killSwitchError(ctx);
+        const record = ctx.ledger.begin(ctx.client.id, a.idempotency_key, messageDigest);
+        const release = ctx.quotas.reserve(ctx.client.id);
+        let emails = [];
+        let smtp;
+        // TEM lists the email after it arrived: look from a little before, for clock skew
+        const since = new Date(Date.now() - 5 * 60_000).toISOString();
         try {
-            emails = await ctx.tem.createEmail({
-                from: msg.from,
-                to: msg.to.map((email) => ({ email })),
-                cc: msg.cc.map((email) => ({ email })),
-                subject: msg.subject,
-                text: msg.text,
-                html: msg.html,
-                project_id: config.projectId,
-                additional_headers: msg.replyTo ? [{ key: "Reply-To", value: msg.replyTo }] : undefined,
-            });
+            if (built.via === "smtp") {
+                smtp = await ctx.smtp.send({
+                    from: msg.from,
+                    replyTo: msg.replyTo,
+                    to: msg.to,
+                    cc: msg.cc,
+                    subject: msg.subject,
+                    text: msg.text,
+                    html: msg.html,
+                    attachments: built.files.map((f) => ({ name: f.name, type: f.type, content: f.content })),
+                });
+            }
+            else
+                emails = await ctx.tem.createEmail({
+                    from: msg.from,
+                    to: msg.to.map((email) => ({ email })),
+                    cc: msg.cc.map((email) => ({ email })),
+                    subject: msg.subject,
+                    text: msg.text,
+                    html: msg.html,
+                    project_id: config.projectId,
+                    additional_headers: msg.replyTo ? [{ key: "Reply-To", value: msg.replyTo }] : undefined,
+                    attachments: built.files.length ? built.files.map((f) => ({ name: f.name, type: f.type, content: f.content.toString("base64") })) : undefined,
+                });
         }
         catch (err) {
-            // a send that may have left keeps its quota slot
-            if (toEmailError(err).code !== "unknown_outcome")
+            // a send that may have left keeps its quota slot and burns its key
+            if (toEmailError(err).code === "unknown_outcome")
+                ctx.ledger.settle(record, "unknown_outcome");
+            else {
                 release();
+                ctx.ledger.drop(record);
+            }
             throw err;
         }
+        const q = ctx.quotas.remaining(ctx.client.id, ctx.client);
+        if (smtp) {
+            const recipients = smtp.accepted.length ? smtp.accepted : [...msg.to, ...msg.cc];
+            ctx.ledger.settle(record, "sent", [], { since, subject: msg.subject, recipients, messageId: UUID_IN.exec(smtp.response)?.[0].toLowerCase() });
+            ctx.audit.log({ ...auditBase(ctx, tool, a), ...auditMsg(msg, messageDigest), result: "sent", via: "smtp", smtpResponse: smtp.response.slice(0, 200), rejected: smtp.rejected.length ? smtp.rejected : undefined });
+            return text(`# email_send — accepted by Scaleway TEM over SMTP\n\n${fence(header(msg))}\n\n` +
+                json({ accepted: smtp.accepted, rejected: smtp.rejected.length ? smtp.rejected : undefined, smtpResponse: smtp.response.slice(0, 200) }) +
+                `\n\nSMTP does not return TEM email ids: follow delivery with email_status (idempotency_key), which finds them once TEM lists the email (usually within a minute). Quota left: ${q.client.hour} this hour, ${q.client.day} today.`);
+        }
         const ids = emails.map((e) => e.id);
-        ctx.audit.log({ ...base, ...who, result: "sent", temEmailIds: ids });
-        return text(`# ${tool} — accepted by Scaleway TEM\n\n${fence(header(msg))}\n\n` +
+        ctx.ledger.settle(record, "sent", ids);
+        ctx.audit.log({ ...auditBase(ctx, tool, a), ...auditMsg(msg, messageDigest), result: "sent", temEmailIds: ids });
+        return text(`# email_send — accepted by Scaleway TEM\n\n${fence(header(msg))}\n\n` +
             json(emails.map((e) => ({ id: e.id, rcptTo: e.rcpt_to, rcptType: e.rcpt_type, status: e.status }))) +
-            `\n\nDelivery is asynchronous: check it with email_status. Quota left this hour: ${ctx.limiter.remaining()}/${config.maxPerHour}.`);
+            `\n\nDelivery is asynchronous: follow it with email_status (emailId or idempotency_key). Quota left: ${q.client.hour} this hour, ${q.client.day} today.`);
     }
     catch (err) {
         const e = toEmailError(err);
-        const result = e.code === "unknown_outcome" ? "unknown_outcome" : ["invalid_request", "recipient_not_allowed", "domain_not_ready", "rate_limited", "refused", "confirmation_invalid"].includes(e.code) ? "refused" : "failed";
-        ctx.audit.log({ ...base, to: msg?.to, cc: msg?.cc.length ? msg.cc : undefined, subject: msg?.subject, messageDigest, result, errorCode: e.code });
+        const result = e.code === "unknown_outcome" ? "unknown_outcome" : REFUSALS.includes(e.code) ? "refused" : "failed";
+        ctx.audit.log({ ...auditBase(ctx, tool, a), ...auditMsg(msg, messageDigest), result, errorCode: e.code });
         return errorResult(e);
     }
 }
 const addressOf = (s) => (/<([^>]+)>/.exec(s)?.[1] ?? s).trim().toLowerCase();
-export async function emailStatus(ctx, emailId) {
+const UUID_IN = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+/**
+ * SMTP does not return the TEM ids: look the email up by the TEM message id of the SMTP reply, or by
+ * sender, subject and date, one email per recipient, the oldest not already owned by another send.
+ * Nothing is attached until every recipient is listed.
+ */
+async function findSmtpIds(ctx, r) {
+    const s = r.smtp;
+    const from = ctx.config.from.email;
+    let list = s.messageId ? await ctx.tem.listEmails({ messageId: s.messageId, mailFrom: from, since: s.since }) : [];
+    if (!list.length)
+        list = await ctx.tem.listEmails({ mailFrom: from, subject: s.subject, since: s.since });
+    const candidates = list
+        .filter((e) => addressOf(e.mail_from ?? "") === from && e.subject === s.subject && !ctx.ledger.ownerOf(e.id))
+        .sort((x, y) => (x.created_at ?? "").localeCompare(y.created_at ?? ""));
+    const ids = [];
+    for (const rcpt of s.recipients) {
+        const e = candidates.find((c) => addressOf(c.rcpt_to ?? "") === rcpt && !ids.includes(c.id));
+        if (!e)
+            return;
+        ids.push(e.id);
+    }
+    ctx.ledger.attach(r, ids);
+}
+async function statusOf(ctx, id) {
+    const e = await ctx.tem.getEmail(id);
+    // only this server's own sends: the project may also carry other applications' mail
+    if (e.project_id !== ctx.config.projectId || addressOf(e.mail_from ?? "") !== ctx.config.from.email) {
+        throw new EmailError("not_found", "not_found: no email with this id was sent by this sender");
+    }
+    return {
+        id: e.id,
+        status: e.status,
+        statusDetails: e.status_details || undefined,
+        rcptTo: e.rcpt_to,
+        rcptType: e.rcpt_type,
+        subject: e.subject,
+        createdAt: e.created_at,
+        updatedAt: e.updated_at,
+        tryCount: e.try_count,
+        lastTries: e.last_tries?.slice(-5).map((t) => ({ triedAt: t.tried_at, code: t.code, message: t.message?.slice(0, 300) })),
+        deliveryEvents: ctx.webhookConfigured ? (ctx.ledger.ownerOf(e.id)?.events[e.id] ?? []) : "webhook not configured",
+    };
+}
+export async function emailStatus(ctx, a) {
     try {
-        if (!UUID_RE.test(emailId))
+        if (!!a.emailId === !!a.idempotency_key)
+            throw new EmailError("invalid_request", "invalid_request: give either emailId or idempotency_key");
+        if (a.idempotency_key) {
+            const r = ctx.ledger.find(ctx.client.id, a.idempotency_key);
+            if (!r)
+                throw new EmailError("not_found", "not_found: no send with this idempotency_key for this client (kept 30 days)");
+            if (r.smtp && r.state === "sent") {
+                await findSmtpIds(ctx, r);
+                if (r.smtp) {
+                    return text(json({ idempotencyKey: r.key, state: r.state, transport: "smtp", createdAt: r.createdAt, emails: [], note: "accepted over SMTP; TEM does not list this email yet — ask again in a minute" }));
+                }
+            }
+            const emails = [];
+            for (const id of r.emailIds.slice(0, 10))
+                emails.push(await statusOf(ctx, id).catch((err) => ({ id, error: toEmailError(err).message })));
+            return text(json({ idempotencyKey: r.key, state: r.state, createdAt: r.createdAt, updatedAt: r.updatedAt, emails, more: r.emailIds.length > 10 ? r.emailIds.length - 10 : undefined }));
+        }
+        const id = a.emailId;
+        if (!UUID_RE.test(id))
             throw new EmailError("invalid_request", "invalid_request: emailId must be a TEM email id (UUID) as returned by email_send");
-        const e = await ctx.tem.getEmail(emailId.toLowerCase());
-        // only this server's own sends: the project may also carry other applications' mail
-        if (e.project_id !== ctx.config.projectId || addressOf(e.mail_from ?? "") !== ctx.config.from.email) {
-            throw new EmailError("not_found", "not_found: no email with this id was sent by this sender");
+        if (ctx.multiClient && ctx.ledger.ownerOf(id.toLowerCase())?.client !== ctx.client.id) {
+            throw new EmailError("not_found", "not_found: no email with this id was sent by this client");
         }
-        return text(json({
-            id: e.id,
-            status: e.status,
-            statusDetails: e.status_details || undefined,
-            rcptTo: e.rcpt_to,
-            rcptType: e.rcpt_type,
-            subject: e.subject,
-            createdAt: e.created_at,
-            updatedAt: e.updated_at,
-            tryCount: e.try_count,
-            lastTries: e.last_tries?.map((t) => ({ triedAt: t.tried_at, code: t.code, message: t.message })),
-        }));
+        return text(json(await statusOf(ctx, id.toLowerCase())));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+export async function emailSuppressions(ctx, addresses) {
+    try {
+        if (!addresses.length || addresses.length > MAX_SUPPRESSION_LOOKUPS)
+            throw new EmailError("invalid_request", `invalid_request: 1 to ${MAX_SUPPRESSION_LOOKUPS} addresses`);
+        const list = addresses.map((raw) => {
+            const a = normalizeAddress(raw);
+            if (!a)
+                throw new EmailError("invalid_request", `invalid_request: invalid address "${raw.slice(0, 100)}"`);
+            // no probing: only addresses this client may write to
+            if (!allowedFor(ctx, a))
+                throw new EmailError("recipient_not_allowed", `recipient_not_allowed: ${a} is not a recipient this client may write to`);
+            return a;
+        });
+        const domain = await ctx.tem.findDomain(domainOf(ctx.config.from.email));
+        if (!domain)
+            throw new EmailError("domain_not_ready", `domain_not_ready: ${domainOf(ctx.config.from.email)} is not a TEM domain of project ${ctx.config.projectId}`);
+        const out = [];
+        for (const address of [...new Set(list)]) {
+            const entries = await ctx.tem.listBlocklists(domain.id, address);
+            out.push({
+                address,
+                suppressed: entries.some((b) => !b.ends_at || Date.parse(b.ends_at) > Date.now()),
+                entries: entries.slice(0, 5).map((b) => ({ type: b.type, reason: b.reason?.slice(0, 200), createdAt: b.created_at, endsAt: b.ends_at, custom: b.custom })),
+            });
+        }
+        return text(json(out));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+export function emailTemplates(ctx) {
+    try {
+        if (!ctx.templates.configured)
+            throw new EmailError("capability_unavailable", "capability_unavailable: no template directory is configured (EMAIL_TEMPLATES_DIR)");
+        return text(json(ctx.templates.list(ctx.client.id).map((t) => ({
+            name: t.name,
+            version: t.version,
+            description: t.description,
+            subject: t.subject,
+            html: t.html !== undefined,
+            variables: t.variables,
+        }))));
     }
     catch (err) {
         return errorResult(err);
@@ -178,35 +467,84 @@ export async function emailConfig(ctx) {
     catch (err) {
         domain = { name: domainOf(c.from.email), error: toEmailError(err).message };
     }
+    const cl = ctx.client;
+    const fmt = (l) => ({ addresses: [...l.addresses], domains: [...l.domains].map((d) => `@${d}`) });
     return text(json({
+        client: cl.id,
         sender: c.from.name ? `${c.from.name} <${c.from.email}>` : c.from.email,
         replyTo: c.replyTo,
         domain,
-        provider: { name: "Scaleway Transactional Email", region: c.region, projectId: c.projectId },
-        allowedRecipients: { addresses: [...c.allowlist.addresses], domains: [...c.allowlist.domains].map((d) => `@${d}`) },
-        limits: { maxRecipientsPerEmail: c.maxRecipients, maxPerHour: c.maxPerHour, remainingThisHour: ctx.limiter.remaining(), subjectChars: MAX_SUBJECT, textChars: MAX_TEXT, htmlChars: MAX_HTML },
-        killSwitch: c.killSwitchFile ? { file: c.killSwitchFile, active: ctx.killSwitchActive() } : "not configured",
+        provider: {
+            name: "Scaleway Transactional Email",
+            region: c.region,
+            sendVia: c.sendVia === "auto" ? (ctx.smtp ? "API up to 2 MB, SMTP above" : "API") : c.sendVia === "smtp" ? "SMTP" : "API",
+            maxEmailBytes: c.sendVia === "api" || !ctx.smtp ? API_MAX_EMAIL_BYTES : SMTP_MAX_EMAIL_BYTES,
+        },
+        allowedRecipients: cl.allowlist ? { server: fmt(c.allowlist), client: fmt(cl.allowlist), rule: "a recipient must be in both" } : fmt(c.allowlist),
+        limits: {
+            maxRecipientsPerEmail: c.maxRecipients,
+            client: { maxPerHour: cl.maxPerHour, maxPerDay: cl.maxPerDay },
+            remaining: ctx.quotas.remaining(cl.id, cl),
+            subjectChars: MAX_SUBJECT,
+            textChars: MAX_TEXT,
+            htmlChars: MAX_HTML,
+        },
+        templates: ctx.templates.configured ? { available: ctx.templates.list(cl.id).length, only: cl.templatesOnly } : "not configured",
+        attachments: ctx.attachments.configured
+            ? { sources: ctx.attachments.sourcesFor(cl.id), types: ctx.attachments.config.types, maxCount: ctx.attachments.config.maxCount, maxTotalBytes: ctx.attachments.config.maxTotalBytes }
+            : "not configured",
+        deliveryEvents: ctx.webhookConfigured ? "webhook configured" : "webhook not configured",
+        killSwitch: ctx.killSwitchActive() ? "active — every send is refused" : c.killSwitchFile ? "inactive" : "not configured",
     }));
 }
 const address = z.string().min(3).max(254);
+const messageShape = {
+    to: z.array(address).min(1).max(50).describe("Recipient addresses (bare addresses, each must be allowed for this client)"),
+    cc: z.array(address).max(50).optional().describe("Carbon-copy addresses, same rules as to. There is no bcc."),
+    subject: z.string().min(1).max(MAX_SUBJECT).optional().describe("Required unless template is given"),
+    text: z.string().min(1).max(MAX_TEXT).optional().describe("Plain-text body, required unless template is given"),
+    html: z.string().max(MAX_HTML).optional().describe("Optional HTML body; the plain-text body stays the fallback"),
+    template: z
+        .object({
+        name: z.string().max(64),
+        version: z.number().int().min(1),
+        variables: z.record(z.string().max(40), z.string().max(HARD_VARIABLE_LENGTH)).optional(),
+    })
+        .strict()
+        .optional()
+        .describe("A versioned template from email_templates, instead of subject/text/html"),
+    attachments: z
+        .array(z
+        .object({
+        source: z.string().max(40).describe("Attachment source id from email_config"),
+        ref: z.string().max(512).describe("Reference of the file inside that source (e.g. a vault file id) — never a local path or a URL"),
+        filename: z.string().max(100).optional().describe("Name shown to the recipient; its extension must match the file type"),
+    })
+        .strict())
+        .max(HARD_MAX_ATTACHMENTS)
+        .optional()
+        .describe("Files resolved by the server from configured sources"),
+    idempotency_key: z
+        .string()
+        .regex(IDEMPOTENCY_KEY_RE)
+        .describe("Your unique key for this message (8-128 of letters, digits . _ : -), the same in email_preview and email_send. A key never sends twice."),
+    approvalId: z
+        .string()
+        .regex(/^[\w.:-]{1,128}$/)
+        .optional()
+        .describe("Pulse Chat approval id, recorded in the audit trail for correlation (not an authorisation)."),
+};
 export function registerTools(server, ctx) {
-    server.tool("email_config", "Sender address, allowed recipients, per-email and hourly limits, sender domain status and kill switch. Start here.", {}, async () => emailConfig(ctx));
-    server.tool("email_send", `[SEND] Send an email from the fixed sender ${ctx.config.from.email} to allowlisted recipients. Two steps: call without confirmToken to preview (nothing is sent), show the preview to the human, then — only after their explicit approval — call again with the same arguments and the returned confirmToken.`, {
-        to: z.array(address).min(1).max(50).describe("Recipient addresses (bare addresses, each must be allowed by EMAIL_ALLOWED_RECIPIENTS)"),
-        cc: z.array(address).max(50).optional().describe("Carbon-copy addresses, same rules as to. There is no bcc."),
-        subject: z.string().min(1).max(MAX_SUBJECT),
-        text: z.string().min(1).max(MAX_TEXT).describe("Plain-text body (always required)"),
-        html: z.string().max(MAX_HTML).optional().describe("Optional HTML body; the plain-text body stays the fallback"),
-        confirmToken: z
-            .string()
-            .max(200)
-            .optional()
-            .describe("Omit for the preview. Then the token from the preview, with the SAME arguments, to send. Single use, valid 5 minutes."),
-        approvalId: z
-            .string()
-            .regex(/^[\w.:-]{1,128}$/)
-            .optional()
-            .describe("Pulse Chat approval id, recorded in the audit trail for correlation (not an authorisation)."),
+    server.tool("email_config", "Your client id, the fixed sender, the recipients you may write to, your quotas, templates, attachment sources, sender domain status and kill switch. Start here.", {}, async () => emailConfig(ctx));
+    server.tool("email_preview", `Prepare an email from the fixed sender ${ctx.config.from.email} and check every policy WITHOUT sending: effective recipients, sender, bodies, resolved attachments, size, quotas. Returns a confirmToken for email_send, to use only after the human approved this preview.`, messageShape, async (args) => previewEmail(ctx, args));
+    server.tool("email_send", `[SEND] Send the email previewed by email_preview — same arguments, same idempotency_key, plus its confirmToken — only after the human's explicit approval. A reused idempotency_key never sends twice.`, {
+        ...messageShape,
+        confirmToken: z.string().max(200).describe("Token returned by email_preview for exactly these arguments. Single use, valid 5 minutes."),
     }, async (args) => sendEmail(ctx, args));
-    server.tool("email_status", "Delivery status of an email sent by this server (TEM email id returned by email_send): new, sending, sent, failed, canceled, with the last delivery attempts.", { emailId: z.string().max(64).describe("TEM email id (UUID)") }, async ({ emailId }) => emailStatus(ctx, emailId));
+    server.tool("email_status", "Delivery status of one of your sends, by TEM email id (from email_send) or by idempotency_key: new, sending, sent, failed, canceled, last attempts and webhook events (delivered, bounce, complaint…).", {
+        emailId: z.string().max(64).optional().describe("TEM email id (UUID)"),
+        idempotency_key: z.string().regex(IDEMPOTENCY_KEY_RE).optional().describe("The key used for the send"),
+    }, async (args) => emailStatus(ctx, args));
+    server.tool("email_templates", "Versioned templates you may send (name, version, subject, variables).", {}, async () => emailTemplates(ctx));
+    server.tool("email_suppressions", `Whether addresses you may write to are on the provider's suppression list (bounce, full mailbox…), at most ${MAX_SUPPRESSION_LOOKUPS} at a time.`, { addresses: z.array(address).min(1).max(MAX_SUPPRESSION_LOOKUPS) }, async ({ addresses }) => emailSuppressions(ctx, addresses));
 }