@primitivedotdev/sdk 0.13.0 → 0.14.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import { a as parseHeaderAddress, i as normalizeReceivedEmail, n as buildReplySubject, r as formatAddress, t as buildForwardSubject } from "./received-email-D6tKtWwW.js";
-import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-DvJpdOJ8.js";
+import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-DH-YKt7a.js";
 import { A as PRIMITIVE_CONFIRMED_HEADER, B as RAW_EMAIL_ERRORS, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, G as WebhookVerificationError, H as VERIFICATION_ERRORS, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, R as PAYLOAD_ERRORS, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, U as WebhookPayloadError, V as RawEmailDecodeError, W as WebhookValidationError, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict, z as PrimitiveWebhookError } from "./webhook-zkN4wUTs.js";
 //#region src/index.ts
 const primitive = {

package/dist/oclif/commands/emails-latest.js

@@ -0,0 +1,118 @@
+import { Command, Flags } from "@oclif/core";
+import { listEmails } from "../../api/generated/sdk.gen.js";
+import { PrimitiveApiClient } from "../../api/index.js";
+import { extractErrorPayload, writeErrorWithHints } from "../api-command.js";
+// `primitive emails:latest` is the agent-grade shortcut for "show me
+// the most recent inbound emails as something I can read at a glance."
+// `emails:list-emails` returns the full JSON envelope which is great
+// for piping but blows out the screen for a quick triage. The AGX
+// walkthrough flagged that an agent doing inbox triage had no compact
+// view to reach for; `latest` is that view.
+//
+// Output is a fixed-width text table: short-id, received timestamp,
+// from address, to address, and subject. Subject is truncated for
+// display only; the underlying JSON is unchanged. For machine-readable
+// output, callers should use `emails:list-emails` and pipe to jq.
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+// Truncation widths chosen so a row fits in ~140 columns total. Long
+// values wrap to "..." rather than blowing out terminal layout.
+const SUBJECT_DISPLAY_WIDTH = 50;
+const ADDRESS_DISPLAY_WIDTH = 32;
+const ID_DISPLAY_WIDTH = 8;
+const RECEIVED_DISPLAY_WIDTH = 19;
+// Truncate to width with right-padding; values longer than width are
+// cut to width-3 with a "..." suffix so the output is exactly `width`
+// chars (3 of which are the ellipsis). Display-only; never mutates
+// the underlying value the caller passed in.
+//
+// Width-exact output matters here: formatRow relies on each column
+// being exactly its declared width so columns line up across rows.
+// An overflowing truncate would shift every later column to the
+// right whenever truncation fired (e.g. a row with both addresses
+// truncated would push SUBJECT 4 chars off).
+export function truncate(value, width) {
+    if (value.length <= width)
+        return value.padEnd(width);
+    return `${value.slice(0, width - 3)}...`;
+}
+// Compact ISO timestamp for display: `YYYY-MM-DD HH:MM:SS` in UTC.
+// The full ISO string with milliseconds and `T`/`Z` markers is too
+// dense to scan at a glance; this is the same shape git log uses.
+export function formatReceivedAt(value) {
+    if (!value)
+        return "-".padEnd(RECEIVED_DISPLAY_WIDTH);
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()))
+        return value.padEnd(RECEIVED_DISPLAY_WIDTH);
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+}
+export function formatRow(email) {
+    const id = truncate(email.id.slice(0, ID_DISPLAY_WIDTH), ID_DISPLAY_WIDTH);
+    const received = formatReceivedAt(email.received_at);
+    const from = truncate(email.sender ?? "", ADDRESS_DISPLAY_WIDTH);
+    const to = truncate(email.recipient ?? "", ADDRESS_DISPLAY_WIDTH);
+    const subject = (email.subject ?? "").replace(/\s+/g, " ");
+    const subjectCol = truncate(subject, SUBJECT_DISPLAY_WIDTH);
+    return `${id}  ${received}  ${from}  ${to}  ${subjectCol}`;
+}
+class EmailsLatestCommand extends Command {
+    static description = `Print the N most recent inbound emails as a one-line-per-row text table. Designed for quick triage and visual scanning. For programmatic access, use \`primitive emails:list-emails\` (full JSON envelope, cursor pagination, filters).
+
+  The displayed id is the first ${ID_DISPLAY_WIDTH} characters of the email's UUID; pass the full UUID (from \`emails:list-emails\` or \`emails:get-email\`) to operations that need it.`;
+    static summary = "Show the most recent inbound emails as a compact table";
+    static examples = [
+        "<%= config.bin %> emails:latest",
+        "<%= config.bin %> emails:latest --limit 25",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "base-url": Flags.string({
+            description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
+            env: "PRIMITIVE_API_URL",
+        }),
+        limit: Flags.integer({
+            description: `Number of rows to print (1-${MAX_LIMIT}, default ${DEFAULT_LIMIT}).`,
+            default: DEFAULT_LIMIT,
+            // oclif validates min/max at parse time and emits a consistent
+            // out-of-range error before run() is reached, so no manual
+            // bounds check is needed here.
+            min: 1,
+            max: MAX_LIMIT,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(EmailsLatestCommand);
+        const apiClient = new PrimitiveApiClient({
+            apiKey: flags["api-key"],
+            baseUrl: flags["base-url"],
+        });
+        const result = await listEmails({
+            client: apiClient.client,
+            query: { limit: flags.limit },
+            responseStyle: "fields",
+        });
+        if (result.error) {
+            writeErrorWithHints(extractErrorPayload(result.error));
+            process.exitCode = 1;
+            return;
+        }
+        const envelope = result.data;
+        const rows = envelope?.data ?? [];
+        if (rows.length === 0) {
+            process.stderr.write("No inbound emails yet. Send an email to one of your verified domains to populate this list.\n");
+            return;
+        }
+        // Header on stderr so the table itself stays grep-friendly.
+        const header = `${"ID".padEnd(ID_DISPLAY_WIDTH)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
+        process.stderr.write(`${header}\n`);
+        for (const row of rows) {
+            this.log(formatRow(row));
+        }
+    }
+}
+export default EmailsLatestCommand;

package/dist/oclif/commands/send.js

@@ -30,7 +30,15 @@ import { extractErrorCode, extractErrorPayload, formatErrorPayload, writeErrorWi
 // pattern-matching from there lands in the happy path. We just
 // don't need swaks's `--server` / `--auth-*` flags because the
 // HTTPS API key is the auth and the server is implicit.
-const SUBJECT_MAX_LENGTH = 70;
+// 200 chars is a generous cap that almost never trips on natural
+// first-line subjects (a sentence is typically <120 chars). The
+// previous 70-char limit was tight enough that legitimate one-line
+// bodies routinely produced ellipsis-truncated subjects in inbox
+// listings, e.g. `"this is the simplest possible send: agent typed
+// two flags and hit\\n e..."` from the AGX walkthrough. Real spam
+// scoring engines don't penalize subjects under ~200 chars, so 200
+// is both more useful and still well under the practical wire limit.
+const SUBJECT_MAX_LENGTH = 200;
 function deriveSubject(body) {
     for (const line of body.split("\n")) {
         const trimmed = line.trim();

package/dist/oclif/index.js

@@ -1,16 +1,73 @@
-import { Args, Command } from "@oclif/core";
+import { Args, Command, Errors } from "@oclif/core";
 import { operationManifest, } from "../openapi/index.js";
 import { createOperationCommand } from "./api-command.js";
+import EmailsLatestCommand from "./commands/emails-latest.js";
 import SendCommand from "./commands/send.js";
 import WhoamiCommand from "./commands/whoami.js";
 import { renderFishCompletion } from "./fish-completion.js";
 class ListOperationsCommand extends Command {
-    static description = "List all generated API operations";
-    static summary = "List all generated API operations";
+    static description = "List all generated API operations as JSON. Useful for piping to `jq` to discover available commands, their request/response schemas, and per-field descriptions. For inspecting a single operation in detail, prefer `primitive describe <command>`.";
+    static summary = "List all generated API operations (JSON)";
     async run() {
         this.log(JSON.stringify(operationManifest, null, 2));
     }
 }
+// Looks up an operation manifest entry by its `<topic>:<command>` id
+// (e.g. `emails:get-email`). On miss, returns up to 5 closest
+// candidates by substring match so the caller can render a
+// "did you mean" hint. Pure function: no oclif config dependency,
+// so it's also unit-testable in isolation.
+export function lookupOperation(id) {
+    const trimmed = id.trim();
+    const sep = trimmed.indexOf(":");
+    const tag = sep === -1 ? "" : trimmed.slice(0, sep);
+    const cmd = sep === -1 ? trimmed : trimmed.slice(sep + 1);
+    const match = operationManifest.find((op) => op.command === cmd && op.tagCommand === tag) ?? null;
+    if (match)
+        return { match, candidates: [] };
+    const candidates = operationManifest
+        .filter((op) => op.command.includes(cmd) || op.tagCommand.includes(tag))
+        .slice(0, 5)
+        .map((op) => op.tagCommand ? `${op.tagCommand}:${op.command}` : op.command);
+    return { match: null, candidates };
+}
+// `primitive describe <command>` is the operation-detail inspector
+// the AGX walkthrough kept wanting. The information is already in
+// the operation manifest emitted by `list-operations`, but agents
+// don't intuitively reach for `list-operations | jq '.[] | select(...)'`
+// when they want to know "what does the from_email field on this
+// response actually mean." A direct command is more discoverable.
+//
+// Lookup is by the colon-joined command id (e.g. `emails:get-email`,
+// `sending:send-email`, `account:get-account`). For top-level
+// generated commands (without a topic), pass the bare command id.
+class DescribeCommand extends Command {
+    static args = {
+        command: Args.string({
+            description: "Command id to describe, in `<topic>:<command>` form (e.g. `emails:get-email`). Run `primitive list-operations | jq -r '.[] | \"\\(.tagCommand):\\(.command)\"'` to enumerate.",
+            required: true,
+        }),
+    };
+    static description = `Print the full operation manifest entry for a single API command, including the path, request schema, response schema, and per-field descriptions sourced from the OpenAPI spec.
+
+  Useful for clarifying response field meanings (e.g. on inbound EmailDetail, which of \`sender\`, \`from_email\`, \`from_header\`, and \`smtp_mail_from\` to read), confirming required body fields, or checking a path's parameter shape before composing a request.`;
+    static summary = "Describe a single API operation in detail";
+    static examples = [
+        "<%= config.bin %> describe emails:get-email",
+        "<%= config.bin %> describe sending:send-email",
+    ];
+    async run() {
+        const { args } = await this.parse(DescribeCommand);
+        const { match, candidates } = lookupOperation(args.command);
+        if (!match) {
+            const hint = candidates.length > 0
+                ? `Did you mean: ${candidates.join(", ")}?`
+                : "Run `primitive list-operations` to enumerate.";
+            throw new Errors.CLIError(`Unknown operation \`${args.command.trim()}\`. ${hint}`, { exit: 1 });
+        }
+        this.log(JSON.stringify(match, null, 2));
+    }
+}
 class CompletionCommand extends Command {
     static args = {
         shell: Args.string({
@@ -40,6 +97,11 @@ const generatedCommands = Object.fromEntries(operationManifest.map((operation) =
 export const COMMANDS = {
     completion: CompletionCommand,
     "list-operations": ListOperationsCommand,
+    // `describe` prints a single operation's full manifest entry
+    // (path, request schema, response schema, per-field descriptions).
+    // The same data is in `list-operations` but agents don't reach for
+    // `list-operations | jq` when they want to clarify a field meaning.
+    describe: DescribeCommand,
     // `send` is the agent-grade shortcut for sending:send-email with
     // sensible defaults (auto from-address, auto subject). The full
     // operation stays available under sending:send-email for callers
@@ -50,5 +112,9 @@ export const COMMANDS = {
     // wanting this before risking a real call against a possibly-
     // bad key.
     whoami: WhoamiCommand,
+    // `emails:latest` is the inbox-triage shortcut: the most recent N
+    // inbound emails as a compact text table. emails:list-emails stays
+    // available for the full JSON envelope + cursor pagination.
+    "emails:latest": EmailsLatestCommand,
     ...generatedCommands,
 };

package/dist/openapi/openapi.generated.js

@@ -1647,6 +1647,150 @@ export const openapiDocument = {
                     }
                 }
             }
+        },
+        "/sent-emails": {
+            "get": {
+                "operationId": "listSentEmails",
+                "summary": "List outbound sent emails",
+                "description": "Returns a paginated list of OUTBOUND emails the caller's\norg has sent via /send-mail (and /emails/{id}/reply, which\nforwards through /send-mail). Includes every recorded\nattempt, including gate-denied attempts that the agent\nnever called and rows still in `queued` state.\n\nFor inbound mail received at your verified domains, see\n/emails. There is no unified send/receive history endpoint;\nthe two surfaces are intentionally separate because the\nunderlying tables, statuses, and lifecycle differ.\n\nEmail bodies (`body_text`, `body_html`) are NOT included on\nlist rows so a 50-row page can't balloon into a multi-MB\nresponse when sends are near the 5MB body cap. Use\n/sent-emails/{id} to fetch a single row with bodies, or\ncross-reference by `client_idempotency_key` if the caller\nalready has the body locally.\n",
+                "tags": [
+                    "Sending"
+                ],
+                "parameters": [
+                    {
+                        "$ref": "#/components/parameters/Cursor"
+                    },
+                    {
+                        "$ref": "#/components/parameters/Limit"
+                    },
+                    {
+                        "name": "status",
+                        "in": "query",
+                        "schema": {
+                            "$ref": "#/components/schemas/SentEmailStatus"
+                        },
+                        "description": "Filter to rows in this status. Useful for polling\nqueued rows that haven't transitioned, auditing\ngate-denied attempts, or listing only successful\ndeliveries.\n"
+                    },
+                    {
+                        "name": "request_id",
+                        "in": "query",
+                        "schema": {
+                            "type": "string",
+                            "format": "uuid"
+                        },
+                        "description": "Filter to the row matching a specific server-issued\n`request_id`. The /send-mail response surfaces\n`request_id` on every send; this lookup lets the\ncaller find the historical row for a given live call\nwithout remembering its `id`.\n"
+                    },
+                    {
+                        "name": "idempotency_key",
+                        "in": "query",
+                        "schema": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 255
+                        },
+                        "description": "Filter to rows with the given `client_idempotency_key`.\nMultiple rows can share a key (a retry that hit the\nidempotent-replay path returns the same row, but a\nretry with a DIFFERENT canonical payload under the\nsame key is rejected by /send-mail before the row is\nwritten, so duplicates are bounded).\n"
+                    },
+                    {
+                        "name": "date_from",
+                        "in": "query",
+                        "schema": {
+                            "type": "string",
+                            "format": "date-time"
+                        },
+                        "description": "Inclusive lower bound on `created_at`."
+                    },
+                    {
+                        "name": "date_to",
+                        "in": "query",
+                        "schema": {
+                            "type": "string",
+                            "format": "date-time"
+                        },
+                        "description": "Inclusive upper bound on `created_at`."
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Page of sent-email summaries",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/ListEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "type": "array",
+                                                    "items": {
+                                                        "$ref": "#/components/schemas/SentEmailSummary"
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    }
+                }
+            }
+        },
+        "/sent-emails/{id}": {
+            "get": {
+                "operationId": "getSentEmail",
+                "summary": "Get a sent email by id",
+                "description": "Returns the full sent-email record by id, including\n`body_text` and `body_html` (omitted from the listing\nendpoint to keep paginated responses small). Use this when\ndiagnosing a specific send, e.g. inspecting the receiver's\nSMTP response on a `bounced` row or pulling the gate\ndenial detail on a `gate_denied` row.\n",
+                "tags": [
+                    "Sending"
+                ],
+                "parameters": [
+                    {
+                        "$ref": "#/components/parameters/ResourceId"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Sent-email detail",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/SentEmailDetail"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    }
+                }
+            }
         }
     },
     "components": {
@@ -2867,10 +3011,12 @@ export const openapiDocument = {
             },
             "SentEmailStatus": {
                 "type": "string",
+                "description": "Lifecycle status of a sent_emails row. Possible values:\n\n  - `queued`: pre-call INSERT; the outbound agent has not\n    yet replied.\n  - `submitted_to_agent`: agent accepted; `queue_id` is set.\n  - `agent_failed`: agent rejected; `error_code` and\n    `error_message` carry the reason.\n  - `gate_denied`: a recipient-scope gate denied the send;\n    the agent was never called. The `gates` array carries\n    the denial detail. /send-mail returns 403 in this case\n    so callers see the denial synchronously; /sent-emails\n    additionally records the row for historical lookup,\n    which is when this status appears in a listing.\n  - `unknown`: terminal indeterminate; the on-box log\n    poller couldn't classify the receiver's response.\n  - `delivered` / `bounced` / `deferred` / `wait_timeout`:\n    terminal delivery outcomes (see DeliveryStatus).\n",
                 "enum": [
                     "queued",
                     "submitted_to_agent",
                     "agent_failed",
+                    "gate_denied",
                     "unknown",
                     "delivered",
                     "bounced",
@@ -2887,6 +3033,217 @@ export const openapiDocument = {
                     "wait_timeout"
                 ]
             },
+            "SentEmailSummary": {
+                "type": "object",
+                "description": "List-row projection of a sent-email record. Drops\n`body_text` and `body_html` to keep paginated responses\nsmall; fetch /sent-emails/{id} for the full record with\nbodies.\n",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "format": "uuid"
+                    },
+                    "status": {
+                        "$ref": "#/components/schemas/SentEmailStatus"
+                    },
+                    "status_changed_at": {
+                        "type": "string",
+                        "format": "date-time",
+                        "description": "Timestamp of the most recent status transition.\nPolling clients should treat `status='queued'` AND\n`status_changed_at` older than 5 minutes as\n\"stuck-queued\" (the post-tx UPDATE failed and the\nactual delivery state is recoverable from on-box logs\nvia `queue_id` when populated, or `request_id`).\n"
+                    },
+                    "created_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "updated_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "client_idempotency_key": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Effective idempotency key used for this send. If the\ncaller passed the `Idempotency-Key` header, this is\nthat value; otherwise it's a server-derived hash of\nthe canonical request payload.\n"
+                    },
+                    "content_hash": {
+                        "type": "string",
+                        "description": "Stable hash of the canonical send payload."
+                    },
+                    "from_header": {
+                        "type": "string",
+                        "description": "Raw `From:` header as sent on the wire, including any\ndisplay name (e.g. `\"Acme Support\" <agent@acme.test>`).\n"
+                    },
+                    "from_address": {
+                        "type": "string",
+                        "description": "Bare email address parsed from `from_header`."
+                    },
+                    "to_header": {
+                        "type": "string",
+                        "description": "Raw `To:` header as sent on the wire, including any\ndisplay name.\n"
+                    },
+                    "to_address": {
+                        "type": "string",
+                        "description": "Bare email address parsed from `to_header`."
+                    },
+                    "subject": {
+                        "type": "string"
+                    },
+                    "body_size_bytes": {
+                        "type": "integer",
+                        "description": "Total UTF-8 byte length of `body_text` + `body_html`.\nSurfaced on the list endpoint so callers can see \"this\nrow has a 4MB body\" without fetching it.\n"
+                    },
+                    "content_discarded_at": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date-time",
+                        "description": "Timestamp at which the bodies were discarded by an\nentitlement-driven retention policy. Null when bodies\nare still present. The detail endpoint returns\nnull-valued `body_text`/`body_html` for discarded rows.\n"
+                    },
+                    "message_id": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Wire-level Message-ID assigned to the outbound message\n(RFC 5322). Null on rows that never reached signing\n(queued, gate_denied, agent_failed before signing).\n"
+                    },
+                    "in_reply_to": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Wire-level In-Reply-To header value, when this send\nwas a reply.\n"
+                    },
+                    "email_references": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Wire-level References header value, when this send\nwas a reply.\n"
+                    },
+                    "in_reply_to_email_id": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "uuid",
+                        "description": "Reference to the inbound `emails.id` that this send\nreplied to, when known. Populated when the caller used\n/emails/{id}/reply or when /send-mail's `in_reply_to`\nmatched a stored inbound message_id in the same org.\n"
+                    },
+                    "queue_id": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Message identifier assigned by Primitive's outbound\nrelay once the agent accepts the message. Null on\nqueued, gate_denied, and agent_failed rows.\n"
+                    },
+                    "smtp_response_code": {
+                        "type": [
+                            "integer",
+                            "null"
+                        ],
+                        "description": "Receiver's 3-digit SMTP code (e.g. 250, 550, 451).\nPopulated on terminal delivery statuses; may be null\non a deferred where the agent never got an SMTP-level\nresponse (TCP refused, DNS failed, TLS handshake\nfailed). `smtp_response_text` still carries Postfix's\ndescriptive text in those cases.\n"
+                    },
+                    "smtp_response_text": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Free-form text portion of the receiver's SMTP\nresponse. The most useful debugging signal on a\n`bounced` or `deferred` row.\n"
+                    },
+                    "smtp_enhanced_status_code": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "RFC 3463 enhanced status code (e.g. `5.1.1` for \"Bad\ndestination mailbox address\"). Distinct from\n`smtp_response_code`: the basic 3-digit code is coarse\n(550 = \"permanent failure\"), the enhanced code is\nfiner-grained.\n"
+                    },
+                    "dkim_selector": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "DKIM selector used to sign the outbound message.\nPublic DNS data; useful for diagnosing why a downstream\nverifier rejected the signature.\n"
+                    },
+                    "dkim_domain": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "DKIM signing domain."
+                    },
+                    "error_code": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Stable public error code on `agent_failed` rows. The\nagent's internal codes are remapped to a stable public\ntaxonomy (see `publicAgentError` in the server) so this\nfield is safe to branch on across agent versions.\n"
+                    },
+                    "error_message": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Free-form error message accompanying `error_code`."
+                    },
+                    "gates": {
+                        "type": [
+                            "array",
+                            "null"
+                        ],
+                        "items": {
+                            "$ref": "#/components/schemas/GateDenial"
+                        },
+                        "description": "Gate-denial detail on `gate_denied` rows. Mirrors the\nsynchronous /send-mail 403 contract so a caller's\nGateDenial handler is the same across live denies and\nhistorical lookups. Null on every other status.\n"
+                    },
+                    "request_id": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Server-issued request identifier from the original\n/send-mail call. Surfaced as the `X-Request-Id`\nresponse header on the live send and recorded here\nfor support escalation.\n"
+                    }
+                },
+                "required": [
+                    "id",
+                    "status",
+                    "status_changed_at",
+                    "created_at",
+                    "updated_at",
+                    "content_hash",
+                    "from_header",
+                    "from_address",
+                    "to_header",
+                    "to_address",
+                    "subject",
+                    "body_size_bytes"
+                ]
+            },
+            "SentEmailDetail": {
+                "description": "Full sent-email record, including `body_text` and\n`body_html`. Returned by /sent-emails/{id}.\n",
+                "allOf": [
+                    {
+                        "$ref": "#/components/schemas/SentEmailSummary"
+                    },
+                    {
+                        "type": "object",
+                        "properties": {
+                            "body_text": {
+                                "type": [
+                                    "string",
+                                    "null"
+                                ],
+                                "description": "Plain-text body sent on the wire. Null when the\nsend carried only an HTML body, or when bodies have\nbeen discarded post-send (`content_discarded_at`\nset).\n"
+                            },
+                            "body_html": {
+                                "type": [
+                                    "string",
+                                    "null"
+                                ],
+                                "description": "HTML body sent on the wire. Null when the send\ncarried only a plain-text body, or when bodies\nhave been discarded post-send.\n"
+                            }
+                        }
+                    }
+                ]
+            },
             "ReplyInput": {
                 "type": "object",
                 "additionalProperties": false,
@@ -2922,6 +3279,10 @@ export const openapiDocument = {
                     "status": {
                         "$ref": "#/components/schemas/SentEmailStatus"
                     },
+                    "from": {
+                        "type": "string",
+                        "description": "Bare from-address actually written on the wire. Echoed\non every success branch so callers can confirm what\nwent out, particularly useful for the /emails/{id}/reply\npath where `from` is server-derived from the inbound's\nrecipient when the caller doesn't override.\n\nFor sends where the caller passed a from-header that\nincluded a display name (e.g. `\"Acme Support\" <support@acme.test>`),\nthis field is the parsed bare address (`support@acme.test`).\nThe display name was sent on the wire intact; this field\njust makes the address easy to compare against allowlists.\n"
+                    },
                     "queue_id": {
                         "type": [
                             "string",
@@ -2977,6 +3338,7 @@ export const openapiDocument = {
                 "required": [
                     "id",
                     "status",
+                    "from",
                     "queue_id",
                     "accepted",
                     "rejected",