Inbound

Import everything on this page from @opencoredev/email-sdk/inbound. The module uses only Request, Headers, Uint8Array, TextDecoder, and Web Crypto, so it runs on Node 20+, Bun, Cloudflare Workers, and Convex. It adds no runtime dependency and is not part of the root entrypoint. For a walkthrough, see Receive email.

InboundEmail

Verdicts are "pass" | "fail" | "softfail" | "neutral" | "none" | "temperror" | "permerror" | "gray" | "processing_failed" | "unknown". They come from fields the provider adds after its own checks (SES receipt verdicts, SendGrid SPF/dkim, Mandrill spf/dkim, Lettermint and Primitive auth results, Mailgun X-Mailgun-* headers). Authentication-Results headers count only when their authserv-id is trusted, because a sender can write that header into the message: JetEmail trusts smtp.jetsmtp.net, and parseCloudflareInbound and emailFromMime take a trustedAuthServIds option. Only the topmost header from a trusted server counts, so trust an authserv-id only if that server removes incoming headers that claim it. Spam scores use each provider's scale, so compare them per provider.

InboundAttachment has filename?, contentType, size?, contentId?, disposition? ("attachment" | "inline"), content? (bytes when delivered inline), url?, and read(): Promise<Uint8Array>. read() downloads from the provider when the content is remote and throws InboundError when it cannot, for example a Brevo attachment without apiKey. Mandrill sends no Content-ID for an image when the event has no raw_msg, and keys images by filename, so the SDK sets contentId only when the HTML links the image's key or name as cid:.

handleInbound

handleInbound(request: Request, config: InboundHandlerConfig): Promise<InboundHandlerResult>

Verifies the request, parses it, and returns { type: "emails", emails } or { type: "handshake", response }. Return a handshake response unchanged: it answers Graph's validationToken request, SNS subscription confirmations, MailerSend's webhook.test route check, and Mandrill's HEAD probe and empty test POST. The provider test secrets (MailerSend's published key, Mandrill's test-webhook) only ever produce a handshake for a body that carries no message; they never authenticate an email. A Graph handshake fails with secret_missing when clientState is empty, so a subscription is only confirmed once its notifications can be checked. Every config also accepts toleranceSeconds (default 300), now, fetch, and signal.

auth is { basic: { username, password } }, { bearer: token }, or { none: true }. Secrets and keys accept an array during rotation; any match passes, and a malformed entry is skipped.

Functions by provider

verify… functions return { ok: true } or { ok: false, reason } and never throw for bad input. parse… functions do not verify; call them only after a successful check. Every fetch… function takes fetch and signal options.

isMailerSendRouteTest(payload) and isMandrillWebhookTest(payload, { url }) detect the providers' setup checks when you verify by hand; answer those with a 200 and do not parse them. verifySnsMessage takes the result of parseSnsMessage(body). parseGraphNotifications checks clientState on every notification, and graphValidationResponse(url) answers the subscription handshake. parseMandrillInbound, parseSparkPostInbound, parseLettrInbound, and parseBrevoInbound return arrays, because one post can carry several messages.

Fetching from provider APIs

Some providers keep the message, or parts of it, behind their API:

• fetchResendInboundEmail(id, { apiKey }) returns bodies, headers, and attachments whose read() downloads them.
• fetchPostmarkInboundEmail(id, { serverToken }) returns the message details. That API lists attachments without their bytes, so their read() throws; read attachments from the webhook payload.
• fetchMailgunStoredEmail(storageUrl, { apiKey }) reads a message a route's store() action kept.
• fetchSesInboundFromS3({ bucket, key }, credentials) downloads mail an S3 receipt action stored, and confirmSnsSubscription(message) confirms an SNS subscription.
• fetchGraphInboundEmail(resource, { getAccessToken }) fetches a Graph message as MIME.
• fetchMailtrapInboundEmail(inboxId, messageId, { apiToken }) fetches a Mailtrap message.
• Brevo and Lettermint attachments download through read(). Brevo needs apiKey.
• parsePrimitiveInbound downloads the raw message when the webhook does not include it, only from https://*.primitive.dev. A self-hosted Primitive lists its origins in downloadOrigins.

parseInbound(provider, payload, options?) dispatches to the right parser and always returns an array. It covers every provider above except Cloudflare, Graph, and Mailtrap, which have no webhook payload to parse.

Signature schemes

All comparisons run in constant time. A valid signature does not stop a replay inside the tolerance window, so deduplicate on email.id or email.messageId.

Errors

InboundError has reason, provider, and status (HTTP status for fetch_failed).

MIME parsing

parseMimeMessage(raw) and emailFromMime({ provider, raw, ... }) are exported for your own sources, such as an IMAP fetch or a stored .eml. parseMimeMessage returns headers with encoded words decoded for display, and rawHeaders as sent; addresses are always parsed from the raw values, so an encoded display name cannot change the address. The parser handles nested multipart (mixed, alternative, related, digest), base64, quoted-printable, 7bit/8bit/binary, RFC 2047 encoded words, RFC 2231 parameters and continuations, message/rfc822 parts as attachments, and charsets through TextDecoder. Unknown charsets fall back to UTF-8, then Latin-1. It stops at 32 nesting levels and 2,000 parts.

It does not verify DKIM or S/MIME, decode TNEF (winmail.dat), or decode uuencode bodies. Within multipart/alternative it keeps the last (preferred) text and HTML part. Elsewhere, several inline text or HTML parts are joined with a newline in message order.

Provider coverage

Plunk, Sequenzy, Unosend, Loops, Iterable, Scaleway, ZeptoMail, Sendheron, Helo, and SMTP have no inbound support. Plunk's receiving feature fires a workflow event with a body you template yourself. Sequenzy tracks replies but does not return messages. The others document send-only APIs, and SMTP is a sending transport. The full audit, with provider documentation links, is in packages/email-sdk/INBOUND.md.