Inbound mail and mailboxes

mail receives email through your provider's webhook, keeps it in mailboxes with threads and attachments, and pulls existing mailboxes over IMAP or JMAP. Reach for it for a support inbox, reply-by-email or a mail client.

MainSDK never runs an SMTP server. Every inbound post is verified before a byte is parsed, and mail is stored in the tenant's region.

mail:
  domains: [in.acme.app]
  inbound: { provider: ses, path: /mainsdk/mail/inbound, secret: secret:MAIL_INBOUND_SECRET }
  mailboxes:
    support: { address: support@in.acme.app, owner: tenant }
  reject: { dmarc: fail, virus: infected }

import { mail } from "mainsdk";

mail.on("support@", async (m) => {
  await tickets.open({ from: m.from.address, subject: m.subject, body: m.replyText ?? m.text });
});

mail:
  driver: ses

Quick start

mail:
  domains: [in.acme.app]
  inbound: { provider: ses, path: /mainsdk/mail/inbound, secret: secret:MAIL_INBOUND_SECRET }
  mailboxes:
    support: { address: support@in.acme.app, owner: tenant }
  reject: { dmarc: fail, virus: infected }

import { Mail } from "mainsdk/experimental/mail";
import { presetVerifier } from "mainsdk/experimental/mail-node";

type MailDeps = ConstructorParameters<typeof Mail>[0];

// The ports you wire in: your app's config, stores, tenant and files.
declare const app: {
  config: { mail: Record<string, unknown> };
  sqlStores: MailDeps["stores"];
  tenant: MailDeps["tenant"];
  files: MailDeps["files"];
};
declare const currentUser: { id: string };
declare const appKey: string;
declare const tickets: { open(t: { from: string; subject: string; body: string }): Promise<void> };

const mail = new Mail({
  config: app.config.mail,
  stores: app.sqlStores,
  tenant: { current: () => app.tenant.current() },
  subject: () => ({ id: currentUser.id }),
  secret: appKey,                                       // signs reply addresses
  verify: presetVerifier("ses", { secrets: [] }),
  files: app.files,
});

mail.on("support@", async (m) => {
  await tickets.open({ from: m.from.address, subject: m.subject, body: m.replyText ?? m.text ?? "" });
});

export const POST = (req: Request) => mail.receive(req);   // the provider posts here

Configuration

What you get

Always:

• No SMTP server; every inbound message is verified before it is parsed.
• Remote images in mail are blocked until the reader allows them.
• Attachments are scanned and stored through files, labelled personal.
• Mailbox tokens never reach app code, messages or logs.

Examples

Reply by email

import type { Mail } from "mainsdk/experimental/mail";

declare const mail: Mail;
declare const comment: { threadId: string };
declare const author: { email: string };
declare const lastMessageId: string;
declare const sender: { send(m: { to: string; replyTo: string; subject?: string; headers: Record<string, string> }): Promise<void> };   // your outbound mail sender

const replyTo = mail.replyAddress({ thread: comment.threadId });   // reply+<token>@in.acme.app
await sender.send({ to: author.email, replyTo, subject: "New comment", headers: await mail.headers({ replyTo: lastMessageId }) });

mail makes the address and the headers; email.send does not take a reply address or headers yet, so pass them to whichever sender you use. A reply to that address joins the thread when its token verifies. A tampered or expired token falls back to In-Reply-To and logs MAIN-MAIL-0005.

Connect a person's mailbox

import type { Mail } from "mainsdk/experimental/mail";

declare const mail: Mail;

export const GET = (req: Request) => mail.connect(req, { provider: "gmail", mailbox: "my-gmail" });

The person grants access, and MainSDK pulls the mailbox over IMAP (or JMAP for Fastmail). Revoking the connection stops the pull with MAIN-CONN-0007.

Errors and checks

mainsdk check has a mail gate for MAIN-MAIL-0008 and MAIN-MAIL-0009, each with its file and line. Each code's cause and fix is in check codes.

Swapping drivers

The inbound provider is one line: change inbound.provider and the verifier you pass, and nothing else moves. The same messages, threads and handlers work for ses, postmark, mailgun and cloudflare.

Testing

@mainsdk/testing has rawMail, a builder of raw messages, and fakeImap and fakeJmap, servers that keep a mailbox in memory. Post a signed mailgun body to mail.receive and read the result with mail.list. See Test your app.

Security and privacy

• A post is verified (SNS certificate, Basic credentials, HMAC or Standard Webhooks) before its body is parsed, and a replayed delivery runs the handler once.
• HTML is sanitised with the built-in allowlist, and cid: images point at signed files URLs.
• privacy.export holds a person's messages and attachment files; privacy.erase deletes them, revokes the connection and lists each in the erasure record.

Next

• Receive and thread email: the steps, end to end.
• Email
• Files
• Connections