Email — API Reference

The module mounts at /v1/shop-access/email. The configuration resource is served through the DataAuthority framework (standard record envelope, bitemporal coordinates, asOf); the routes below specify only the payloads and the email-specific behavior. Standard headers: Authorization: Bearer <ARDA_API_KEY>, X-Tenant-Id, X-Author.

Identifiers in payloads are slugs / local-parts, never fully-qualified strings — the hosting environment supplies the partition and mail-root, keeping payloads stable across partitions.

`POST /configuration`

Create a configuration. Created PENDING ∥ LOCKED (locked-by-default). Payload (EmailConfigurationInput):

{
  "sendingDomainSlug": "acme",
  "signatureRequest": {
    "fromLocalPart": "noreply",
    "fromName": "Acme Co",
    "replyToEmail": "support@acme.com"
  }
}

Server-side synthesis: sendingDomain = {sendingDomainSlug}.{partition}.ardamails.com; signature.fromEmail = {fromLocalPart}@{sendingDomain} (fromLocalPart defaults to noreply). sendingDomainSlug must be DNS-label-safe and unique among active configurations in the partition. Errors: 400 invalid input; 409 slug already in use.

Lifecycle signals

The configuration advances via signal sub-routes rather than generic PUT/DELETE (which are un-mounted): provision, re-provision, re-verify, lock, force-lock, unlock, remove. See Lifecycle.

`POST /job`

Submit a transactional send. Requires an Idempotency-Key header. Payload (EmailJobInput):

{
  "configurationEId": "<UUID>",
  "recipient": "buyer@vendor.example",
  "replyToEmail": "support@acme.com",
  "subject": "PO-2026-00042: Order details",
  "htmlBody": "<html>...</html>",
  "textBody": "Order details: ...",
  "attachments": [
    { "filename": "po.pdf", "contentType": "application/pdf", "contentBase64": "JVBERi0xLjQK..." }
  ]
}

Server-side synthesis: from = {configuration.signature.fromLocalPart}@{configuration.sendingDomain} — fixed by the configuration signature; there is no per-send From override (Postmark Sender Signatures authorize one address; multi-From is deferred to PDEV-903). replyToEmail falls back to the configuration’s when omitted. At least one of htmlBody / textBody is required; attachments are inline base64 (≤ 5 MiB each, ≤ 10 MiB per message).

Body content is constrained. Both bodies are validated against an allow-list of markup and rejected, not cleaned, if they carry anything outside it. Permitted: basic text formatting, headings (h1–h4) and div, lists, tables, links to http / https / mailto, and the inline style attribute. Refused: script, iframe, style as an element, object, form, meta, svg, img, inline event handlers, javascript: / data: links, a single body over 1,000,000 characters (the limit applies to htmlBody and textBody independently, not to the two combined), and any inline style that would fetch a remote resource (url(), image-set()) or run script. Subject, recipients and reply-to reject control characters (the header-injection guard) and cap at 1,024 characters. The full contract, including how to validate before persisting rather than at send time, is in Integrating with System Email §5 — the same library backs both capabilities.

Errors: 400 invalid shape / recipient / body content; 403 recipient suppressed; 404 configuration not found; 412 configuration not sendable (canSend() false); 413 payload too large.

`POST /job/postmark-events`

The inbound Postmark webhook. Authenticated by Authorization: Bearer <ARDA_API_KEY> plus the per-configuration webhookRoutingToken. Projects delivery status onto the EmailJob and drives suppression — see Webhook ingestion.