@molecule/api-emails-inbound-ses

AWS SES inbound-email provider for molecule.dev.

Implements @molecule/api-emails-inbound's InboundEmailProvider interface against AWS SES Inbound's SNS-delivery format. Validates SNS notification signatures by fetching the publisher cert from a *.amazonaws.com-allowlisted URL, parses the SES mail + content fields, and decodes the embedded RFC 822 message via mailparser.

Outbound replies compose onto the bonded @molecule/api-emails transport (typically @molecule/api-emails-ses) — this package does not reimplement SMTP / SES SendEmail.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider } from '@molecule/api-emails-inbound'
import { provider as sesInbound } from '@molecule/api-emails-inbound-ses'

setProvider(sesInbound)

Type

provider

Installation

npm install @molecule/api-emails-inbound-ses @molecule/api-emails @molecule/api-emails-inbound @molecule/api-secrets mailparser
npm install -D @types/mailparser

API

Interfaces

SnsNotificationPayload

Shape of an Amazon SNS notification (or SubscriptionConfirmation / UnsubscribeConfirmation) payload, as POSTed to a subscribed HTTPS endpoint. Only the fields used by this bond are typed here.

interface SnsNotificationPayload {
  /**
   * Discriminates the kind of message: `Notification`,
   * `SubscriptionConfirmation`, or `UnsubscribeConfirmation`.
   */
  Type: string

  /** A unique UUID for the message. */
  MessageId: string

  /**
   * The notification topic ARN. Its account-id field is part of the
   * SNS-signed canonical string, so after signature verification it is an
   * attested publisher identity — the source used for
   * `AWS_SES_INBOUND_ACCOUNT_ID` pinning.
   */
  TopicArn?: string

  /**
   * Subject line as supplied by the publisher. Optional for notifications.
   */
  Subject?: string

  /** Message payload (string). For SES notifications this is JSON. */
  Message: string

  /** ISO 8601 timestamp when the message was published. */
  Timestamp: string

  /** Signature version. AWS SNS supports `1` (SHA1) and `2` (SHA256). */
  SignatureVersion: string

  /** Base64-encoded signature over the canonical string. */
  Signature: string

  /**
   * URL of the X.509 PEM cert used to sign the message. Must be HTTPS on an
   * allowlisted `*.amazonaws.com` host; a 12-digit account-id path segment,
   * when present, participates in `AWS_SES_INBOUND_ACCOUNT_ID` pinning.
   */
  SigningCertURL: string

  /** Confirmation token (only on SubscriptionConfirmation messages). */
  Token?: string

  /** Subscribe URL (only on SubscriptionConfirmation messages). */
  SubscribeURL?: string

  /** Unsubscribe URL (only on Notification / UnsubscribeConfirmation). */
  UnsubscribeURL?: string
}

SesInboundNotificationMessage

Shape of the JSON payload SES publishes to SNS for inbound-email notifications. Only the fields used by this bond are typed; SES emits a superset including verdicts, dkim, etc.

interface SesInboundNotificationMessage {
  /** Notification kind. We expect `Received` for inbound mail. */
  notificationType: string

  /** Metadata about the SES `mail` object. */
  mail: {
    /** ISO timestamp SES received the message. */
    timestamp: string
    /** Sender as decoded by SES. */
    source: string
    /** SES-assigned message ID. */
    messageId: string
    /** Envelope-recipient list. */
    destination: string[]
    /** Common headers SES extracts from the message. */
    commonHeaders?: {
      from?: string[]
      to?: string[]
      cc?: string[]
      bcc?: string[]
      subject?: string
      messageId?: string
      inReplyTo?: string
      references?: string
    }
    /**
     * All raw headers SES extracted, when `headersTruncated` is `false`.
     */
    headers?: Array<{ name: string; value: string }>
  }

  /**
   * Raw RFC 822 message content, base64-encoded, present when the SES
   * receipt rule includes the message content. Absent for header-only
   * notifications.
   */
  content?: string
}

InboundEmailAttachment

A binary attachment carried by an inbound email.

Providers normalize whatever multipart/MIME representation they receive into this neutral shape. The body is base64-encoded so the type is JSON-serializable across IPC, queue, and webhook boundaries.

interface InboundEmailAttachment {
  /**
   * The original filename as supplied by the sender, or a provider-derived
   * fallback when the sender omitted one.
   */
  name: string
  /**
   * MIME type of the attachment (e.g. `'application/pdf'`, `'image/png'`).
   * Defaults to `'application/octet-stream'` when the provider cannot
   * determine the type.
   */
  contentType: string
  /**
   * Attachment payload, base64-encoded.
   */
  contentBase64: string
  /**
   * Optional size hint in bytes of the decoded payload. Providers MAY set
   * this from upstream headers without decoding the payload themselves.
   */
  sizeBytes?: number
  /**
   * Optional Content-ID, used for inline images referenced from the HTML
   * body via `cid:` URLs.
   */
  contentId?: string
}

InboundEmail

A normalized inbound email, produced by parsing a provider webhook payload through InboundEmailProvider.parseWebhookPayload.

All providers (Mailgun Routes, SES Inbound, fixtures, etc.) return this same shape so handler code can treat inbound mail uniformly. Provider specifics (raw MIME, signing tokens, etc.) MUST NOT leak into this type.

interface InboundEmail {
  /**
   * Stable provider-supplied identifier for the message. Used for
   * deduplication when the same webhook is retried.
   */
  id: string
  /**
   * Sender address (RFC 5322 mailbox), e.g. `'alice@example.com'`.
   */
  from: string
  /**
   * Primary recipient addresses (the values from the `To:` header).
   */
  to: string[]
  /**
   * Carbon-copy recipient addresses, if present.
   */
  cc?: string[]
  /**
   * Subject line, decoded to a plain string. May be empty.
   */
  subject: string
  /**
   * Plain-text body of the message, if present.
   */
  textBody?: string
  /**
   * HTML body of the message, if present.
   */
  htmlBody?: string
  /**
   * Decoded attachments. An empty array when the message has none.
   */
  attachments?: InboundEmailAttachment[]
  /**
   * All headers from the raw message, lowercased keys to canonicalize the
   * many capitalizations that mail servers use. Multi-value headers
   * (`Received:`, etc.) are joined with newlines or returned as arrays at
   * provider discretion — see provider docs.
   */
  headers: Record<string, string | string[]>
  /**
   * Server-side timestamp the inbound provider received the message.
   */
  receivedAt: Date
  /**
   * Optional `Message-ID` header value for threading. Surfaced separately
   * from `headers` because helpdesk handlers almost always need it.
   */
  messageId?: string
  /**
   * Optional `In-Reply-To` header value for threading replies into an
   * existing ticket.
   */
  inReplyTo?: string
  /**
   * Optional `References` header values for threading.
   */
  references?: string[]
}

InboundEmailReply

Outgoing reply produced by handler code in response to an InboundEmail. Providers that support the optional InboundEmailProvider.replyTo method translate this into whatever outbound mechanism their upstream offers (Mailgun reply route, SES SendEmail, etc.).

For providers that do NOT expose an outbound reply path, handler code SHOULD fall back to the regular @molecule/api-emails outbound bond.

interface InboundEmailReply {
  /**
   * Subject line for the outbound reply. If omitted, providers SHOULD
   * default to the original subject prefixed with `'Re: '` (locale-aware
   * prefixing is the caller's responsibility).
   */
  subject?: string
  /**
   * Plain-text body of the reply, if any.
   */
  textBody?: string
  /**
   * HTML body of the reply, if any.
   */
  htmlBody?: string
  /**
   * Attachments to send with the reply.
   */
  attachments?: InboundEmailAttachment[]
  /**
   * Optional override for the `From:` address. Defaults to the address
   * the original message was sent to (the inbound mailbox).
   */
  from?: string
  /**
   * Optional additional headers to set on the outbound message.
   */
  headers?: Record<string, string>
}

InboundEmailReplyResult

Result of a successful reply dispatch via InboundEmailProvider.replyTo.

interface InboundEmailReplyResult {
  /**
   * Provider-supplied identifier for the dispatched outbound message.
   */
  id: string
}

InboundEmailProvider

Inbound-email provider interface.

Implementations (Mailgun Routes, SES Inbound, etc.) live in separate bond packages (@molecule/api-emails-inbound-mailgun-routes, @molecule/api-emails-inbound-ses). The interface is deliberately minimal: a webhook arrives at the host application's HTTP layer, the raw headers and body are handed to the provider, and the provider returns a normalized InboundEmail.

Signature verification is mandatory for any provider that runs against a public webhook endpoint; verifySignature is the hook for that. Providers without signed webhooks SHOULD return false rather than true so callers can decide whether to accept unsigned mail.

interface InboundEmailProvider {
  /**
   * Parses the raw webhook payload (HTTP headers + body) into a
   * normalized `InboundEmail`.
   *
   * @param headers - HTTP request headers received by the webhook
   *   endpoint. Lowercased keys are recommended but not required;
   *   implementations MUST handle either casing.
   * @param body - Raw HTTP request body. May be a `Buffer` (e.g. from a
   *   raw body parser), a `string`, or an already-parsed object provided
   *   by an upstream JSON middleware.
   * @returns The normalized inbound email.
   */
  parseWebhookPayload(
    headers: Record<string, string | string[] | undefined>,
    body: Buffer | string | Record<string, unknown>,
  ): Promise<InboundEmail>
  /**
   * Verifies the signature of a webhook request, using whatever scheme
   * the provider exposes (Mailgun HMAC, SES SNS subscription
   * confirmation, etc.). Implementations MUST be constant-time when
   * comparing secrets.
   *
   * A genuinely invalid webhook (forged, stale, malformed, tampered
   * signature) resolves `false` — that is the normal, expected failure
   * path and callers map it to a `401`. Implementations MAY instead THROW
   * a tagged configuration error (e.g. via `configNotConfiguredError()`
   * from `@molecule/api-secrets`) when the provider itself is
   * misconfigured — for example a missing signing key/secret. This is a
   * DISTINCT failure class from a `false` return: a misconfigured server
   * is not the same problem as a forged request, and collapsing both into
   * the same `false` makes a broken deployment indistinguishable from an
   * attack, with no trace either way. `@molecule/api-emails-inbound-mailgun`
   * follows this pattern — `verifySignature` throws the tagged
   * `config.notConfigured` error when `MAILGUN_API_KEY` is unset, and
   * resolves `false` for every other verification failure.
   *
   * @param headers - HTTP request headers received by the webhook
   *   endpoint.
   * @param body - Raw HTTP request body. Implementations that need the
   *   exact bytes (e.g. for HMAC) MUST be passed a `Buffer`.
   * @returns `true` when the signature is valid, `false` for an
   *   invalid/forged/stale/malformed webhook.
   * @throws {Error} Implementations MAY throw a tagged configuration error
   *   when the provider is missing required configuration (e.g. an unset
   *   signing key) — a server misconfiguration, not an invalid request.
   * @example
   * ```typescript
   * // In an HTTP handler bound to the inbound webhook URL:
   * const ok = await verifySignature(req.headers, req.rawBody)
   * if (!ok) return res.status(401).end()
   * // A thrown configuration error (server misconfigured) is deliberately
   * // NOT caught above — do not wrap this call in a try/catch that maps
   * // every failure to the same 401. Let it propagate to standard error
   * // middleware, which maps a tagged config error to a 503, distinct
   * // from the 401 an invalid/forged webhook gets.
   * ```
   */
  verifySignature(
    headers: Record<string, string | string[] | undefined>,
    body: Buffer | string,
  ): Promise<boolean>
  /**
   * Optional: dispatches an outbound reply through the provider's own
   * reply mechanism. Providers that do not support reply dispatch (e.g.
   * pure inbound-only adapters) SHOULD omit this method; callers MUST
   * use `InboundEmailProvider.supportsReply` to detect support.
   *
   * @param email - The original inbound email being replied to.
   * @param reply - The reply payload.
   * @returns Result of the dispatch.
   */
  replyTo?(email: InboundEmail, reply: InboundEmailReply): Promise<InboundEmailReplyResult>
  /**
   * Indicates whether the provider supports outbound reply dispatch via
   * `replyTo`. Implementations SHOULD return a stable `true` /
   * `false` based on their own configuration; the property is a function
   * so providers can defer to runtime configuration if needed.
   *
   * @returns `true` when `replyTo` is implemented and ready to use.
   */
  supportsReply(): boolean
}

Functions

_resetSigningCertCache()

Resets the cached signing certificates. Exposed for tests.

function _resetSigningCertCache(): void

verifySignature(_headers, body)

Verifies the signature of an SNS notification payload. Implements the AWS SNS signature-verification flow:

1. Parse the JSON body.
2. PIN THE PUBLISHER (fail-closed): accept the notification only when EITHER AWS_SES_INBOUND_TOPIC_ARN is configured and matches the payload's TopicArn, OR AWS_SES_INBOUND_ACCOUNT_ID is configured and matches the AWS account id carried by the notification (the 12-digit segment of the SigningCertURL path, or the account field of the SIGNED TopicArn). When NEITHER is configured, verification THROWS a tagged config.notConfigured error — a valid AWS signature only proves that some AWS account published the message (the cert-hostname allowlist admits every sns.<region>.amazonaws.com cert), so without a pin ANY AWS account that can publish to SNS can forge inbound mail.
3. Reject if SigningCertURL is not from an allowlisted host.
4. Fetch the X.509 certificate from SigningCertURL.
5. Build the canonical string per AWS docs (field order varies by Type).
6. Verify the base64-decoded Signature against the canonical string using SHA1 (SignatureVersion === '1') or SHA256 (SignatureVersion === '2').

Errors NEVER leak signing material; failures simply return false. The ONLY throw is the misconfiguration error from step 2 (distinct failure class per the InboundEmailProvider contract).

function verifySignature(
  _headers: Record<string, string | string[] | undefined>,
  body: string | Buffer<ArrayBufferLike>,
): Promise<boolean>

• _headers — HTTP headers (unused — SNS signs the body).
• body — Raw HTTP request body (JSON).

Returns: true when the signature is valid, false otherwise.

parseWebhookPayload(_headers, body)

Parses an SNS notification carrying an SES inbound-email payload into a normalized InboundEmail.

When the SES Message.content field is present, it is base64-decoded and parsed as RFC 822 via mailparser. When content is absent (header-only notifications), we synthesize an InboundEmail from the SES mail metadata so the caller can still log/dedupe the message.

SubscriptionConfirmation messages are returned as a synthetic InboundEmail whose subject is '__sns:SubscriptionConfirmation' and whose headers['x-sns-subscribe-url'] carries the confirmation URL — applications inspect this so they can subscribe out-of-band.

function parseWebhookPayload(
  _headers: Record<string, string | string[] | undefined>,
  body: string | Buffer<ArrayBufferLike> | Record<string, unknown>,
): Promise<InboundEmail>

• _headers — HTTP headers (unused).
• body — Raw HTTP body (SNS JSON).

Returns: The normalized inbound email.

replyTo(email, reply)

Dispatches an outbound reply through the bonded @molecule/api-emails transport. The reply's In-Reply-To and References headers are populated from the original message when present.

function replyTo(email: InboundEmail, reply: InboundEmailReply): Promise<InboundEmailReplyResult>

• email — The original inbound email being replied to.
• reply — The reply payload.

Returns: The reply dispatch result.

supportsReply()

Indicates that this provider supports outbound reply dispatch via replyTo. The reply path requires the outbound @molecule/api-emails bond to be wired with a transport — typically @molecule/api-emails-ses.

function supportsReply(): boolean

Returns: Always true.

headerToString(value)

Coerces an HTTP header value (which may be string, string[], or undefined) to a single string. Multi-value headers are joined with , per RFC 9110 §5.2.

function headerToString(value: string | string[] | undefined): string | undefined

• value — The header value to coerce.

Returns: The header value as a single string, or undefined when the header was not present.

getHeader(headers, name)

Returns the value of headers[name] (case-insensitive) coerced to a single string.

function getHeader(
  headers: Record<string, string | string[] | undefined>,
  name: string,
): string | undefined

• headers — The headers object.
• name — The header name (case-insensitive).

Returns: The header value as a single string, or undefined if absent.

bodyToString(body)

Coerces the request body into a UTF-8 string. SNS POSTs JSON as UTF-8.

function bodyToString(body: string | Buffer<ArrayBufferLike>): string

• body — The raw body.

Returns: The body as a UTF-8 string.

parseJsonBody(body)

Parses a Buffer/string/object body as an SNS JSON payload. Throws (caught by the caller) when the body is not valid JSON.

function parseJsonBody(body: string | Buffer<ArrayBufferLike> | Record<string, unknown>): unknown

• body — The raw body.

Returns: The parsed object.

getSigningCertHostnameSuffixes()

Returns the configured allowlist of hostname suffixes for the SNS SigningCertURL. Defaults to SNS_SIGNING_CERT_HOSTNAME_SUFFIXES when the env override is unset.

function getSigningCertHostnameSuffixes(): readonly string[]

Returns: The allowlist of hostname suffixes.

isAllowedSigningCertUrl(url)

Validates that an SNS SigningCertURL is HTTPS and its hostname matches an entry in the allowlist. Defends against SSRF and certificate substitution attacks where an attacker tricks the verifier into fetching a cert from a host they control.

function isAllowedSigningCertUrl(url: string): boolean

• url — The candidate URL string.

Returns: true when the URL is acceptable.

buildSnsCanonicalString(payload)

Builds the canonical string SNS signs for the supplied notification. The exact field order is mandated by the SNS message-and-signature format; the canonical string is built from key/value pairs separated by \n, with a trailing \n after the last value.

function buildSnsCanonicalString(payload: {
  Type?: string
  Message?: string
  MessageId?: string
  Subject?: string
  SubscribeURL?: string
  Timestamp?: string
  Token?: string
  TopicArn?: string
}): string

• payload — The SNS notification payload.

Returns: The canonical string suitable for HMAC verification.

splitReferences(value)

Splits a References: header (whitespace-separated <message-id> tokens) into individual values, preserving the angle brackets.

function splitReferences(value: string | undefined): string[]

• value — The raw header value.

Returns: Array of message-id tokens (with angle brackets) or empty.

unwrapMessageId(value)

Strips surrounding angle brackets from a Message-ID value.

function unwrapMessageId(value: string | undefined): string | undefined

• value — The raw value (with or without angle brackets).

Returns: The value without angle brackets, or undefined if input was empty.

base64ToBuffer(value)

Decodes a base64 string into a Node Buffer.

function base64ToBuffer(value: string): Buffer<ArrayBufferLike>

• value — The base64 string.

Returns: The decoded buffer.

parseRawMimeContent(raw, overrides)

Parses a raw RFC 822 MIME message into a normalized InboundEmail.

Used internally by parseWebhookPayload after the SES content field has been base64-decoded. Exposed so that applications using SES's S3-only delivery mode can reuse the same parser by fetching the S3 object themselves and calling this helper.

function parseRawMimeContent(
  raw: string | Buffer<ArrayBufferLike>,
  overrides?: Partial<InboundEmail>,
): Promise<InboundEmail>

• raw — The raw RFC 822 message bytes.
• overrides — Optional fields to override on the parsed result (e.g. an SES-assigned id or receivedAt timestamp).

Returns: The normalized inbound email.

Constants

provider

The AWS SES inbound-email provider implementing the InboundEmailProvider interface.

const provider: InboundEmailProvider

emailsInboundSesSecretDefinitions

Secret definitions required by the AWS SES inbound-email bond.

const emailsInboundSesSecretDefinitions: SecretDefinition[]

SNS_SIGNING_CERT_HOSTNAME_SUFFIXES

Allowed hostname suffixes for the SNS SigningCertURL. AWS SNS only publishes signing certificates from *.amazonaws.com; any URL outside this allowlist MUST be rejected to defend against SSRF and certificate substitution attacks.

Exposed for unit-testing; not part of the public bond surface.

const SNS_SIGNING_CERT_HOSTNAME_SUFFIXES: readonly string[]

Core Interface

Implements @molecule/api-emails-inbound interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-emails-inbound'
import { provider } from '@molecule/api-emails-inbound-ses'

export function setupEmailsInboundSes(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-emails ^1.0.1
• @molecule/api-emails-inbound ^1.0.1
• @molecule/api-secrets ^1.0.1

Environment Variables

• AWS_ACCESS_KEY_ID (required) — AWS access key ID
  • Setup: Create an IAM user with the needed policy (SES/S3/SQS) and create an access key under Security credentials.
  • Get it here: https://console.aws.amazon.com/iam/
  • Example: AKIA...
• AWS_SECRET_ACCESS_KEY (required) — AWS secret access key
  • Setup: Shown once when creating the IAM access key — store it immediately.
  • Get it here: https://console.aws.amazon.com/iam/
• AWS_SES_REGION (required) — AWS SES region
  • Setup: The AWS region where SES is set up (and out of sandbox for production sending).
  • Example: us-east-1
• AWS_SES_INBOUND_TOPIC_ARN (optional) — SES inbound SNS topic ARN
  • Setup: ARN of the SNS topic your SES receipt rule publishes inbound mail to.
  • Get it here: https://console.aws.amazon.com/ses/
  • Example: arn:aws:sns:us-east-1:123456789012:ses-inbound
• AWS_SNS_SIGNING_CERT_HOSTNAME_SUFFIXES (optional) — SNS signing-cert hostname allowlist — default: .amazonaws.com
  • Setup: Comma-separated hostname suffixes allowed for SNS signature certificates; the default (.amazonaws.com) is fine.
  • Example: .amazonaws.com

Runtime Dependencies

• @molecule/api-emails
• @molecule/api-emails-inbound
• @molecule/api-secrets
• mailparser

Verification is FAIL-CLOSED on publisher identity. An SNS signature only proves that some AWS account published the message — the *.amazonaws.com cert-hostname allowlist admits every AWS account's signing cert — so a notification is accepted only when it is pinned to YOUR infrastructure: either AWS_SES_INBOUND_TOPIC_ARN is set and exactly matches the payload's TopicArn, or AWS_SES_INBOUND_ACCOUNT_ID is set and matches the publisher's 12-digit AWS account id (read from the SigningCertURL path or the account field of the SNS-signed TopicArn). When NEITHER is configured, verifySignature throws a tagged config.notConfigured (503) error instead of accepting any validly-signed SNS message — without a pin, any AWS account could forge inbound mail into your app. Configure at least one of the two in api/.env; the topic ARN is the tighter pin.

The (uncached) signing-certificate fetch is bounded to a 5 second timeout — a hanging/slow SigningCertURL endpoint fails fast into a false verification result instead of stalling the webhook handler for fetch's much longer default. Once a cert is fetched it is cached in-process, so this only affects the first verification against a given SigningCertURL.

E2E Tests

Integration checklist — drive the real inbound endpoint (live preview, no mocks), adapt each item to this app's actual inbox/ticket/thread flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip. COUNTERPARTY: the app can't receive a real email in the sandbox, so YOU play the mail provider — POST a realistic inbound-email webhook to the app's inbound endpoint with sandbox_fetch (curl runs inside the container). Model the payload on the BONDED provider's real format (Mailgun: form fields sender/recipient/subject/body-plain/body-html/ attachment-N plus the timestamp/token/signature triple; SES/Postmark: their JSON), and the happy-path POST must carry a VALID signature — compute it the way the provider does (Mailgun signs HMAC-SHA256 of timestamp+token with MAILGUN_API_KEY inside the replay window; read the key from the Environment panel / .env.molecule). Never disable verifySignature() or mock parseWebhookPayload() to go green — that proves nothing.

• A signed sample webhook to the inbound endpoint parses into the normalized fields (from / to / subject / textBody / htmlBody) AND the app ACTS on it — it files the mail into the right place (creates a ticket, a comment on a thread, or a reply-thread) keyed off the recipient (support@) or a plus-address / thread token (reply+<id>@). Verify the CREATED record (a DB row, and it shows up in the UI) — not just a 200.
• Routing is correct: an email to support@ opens a NEW ticket, while reply+<id>@ (or an In-Reply-To / References match) threads onto the EXISTING one — each lands in the right user's / conversation's place, never a stranger's.
• Attachments survive: an inbound message with an attachment has it decoded from attachments[].contentBase64 and stored on the app's OWN storage (the uploads bond), not left as a provider link — the stored file opens from the ticket.
• Retries don't duplicate: re-POST the SAME webhook (providers retry slow / 5xx deliveries) and confirm handling is idempotent — one ticket, not two (dedupe on id / messageId).
• Malformed / empty payloads (missing body-plain, no attachments, absent headers) are handled without a crash — a clean response, not a 500 stack trace.
• SECURITY — the endpoint is AUTHENTICATED: a forged POST with a bad or missing signature (or a timestamp outside the replay window) is REJECTED (401) and creates NO record, so an attacker can't inject mail into another user's thread. A missing signing key is a DISTINCT 503, not a 401 — a server misconfig must not masquerade as an accepted or forged webhook.
• SECURITY — the parsed htmlBody is sanitized before it is rendered anywhere: a <script> / onerror= in an inbound body must NOT execute when the ticket is viewed (no stored XSS from an inbound email body).