@primitivedotdev/sdk 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,3 +1,12 @@
-import { AuthConfidence$1 as AuthConfidence, AuthVerdict$1 as AuthVerdict, DkimResult$1 as DkimResult, DkimSignature, DmarcPolicy$1 as DmarcPolicy, DmarcResult$1 as DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType$1 as EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict$1 as ForwardVerdict, ForwardVerification, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus$1 as ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, SpfResult$1 as SpfResult, UnknownEvent, ValidateEmailAuthResult, WebhookAttachment, WebhookEvent } from "./types-CKFmgitP.js";
-import { DecodeRawEmailOptions, GenerateDownloadTokenOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER$1 as LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER$1 as LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER$1 as PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER$1 as PRIMITIVE_SIGNATURE_HEADER, PrimitiveWebhookError$1 as PrimitiveWebhookError, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER$1 as STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER$1 as STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER$1 as STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookErrorCode, WebhookHeaders, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders$1 as confirmedHeaders, decodeRawEmail$1 as decodeRawEmail, emailReceivedEventJsonSchema$1 as emailReceivedEventJsonSchema, generateDownloadToken$1 as generateDownloadToken, getDownloadTimeRemaining$1 as getDownloadTimeRemaining, handleWebhook$1 as handleWebhook, isDownloadExpired$1 as isDownloadExpired, isEmailReceivedEvent$1 as isEmailReceivedEvent, isRawIncluded$1 as isRawIncluded, parseWebhookEvent$1 as parseWebhookEvent, safeValidateEmailReceivedEvent$1 as safeValidateEmailReceivedEvent, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload, validateEmailAuth$1 as validateEmailAuth, validateEmailReceivedEvent$1 as validateEmailReceivedEvent, verifyDownloadToken$1 as verifyDownloadToken, verifyRawEmailDownload$1 as verifyRawEmailDownload, verifyStandardWebhooksSignature$1 as verifyStandardWebhooksSignature, verifyWebhookSignature$1 as verifyWebhookSignature } from "./index-DLmAI4UQ.js";
-export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, GenerateDownloadTokenOptions, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+import { A as UnknownEvent, C as ParsedDataFailed, D as RawContentDownloadOnly, E as RawContent, M as WebhookAttachment, N as WebhookEvent, O as RawContentInline, S as ParsedDataComplete, T as ParsedStatus, _ as ForwardResultInline, a as DmarcPolicy, b as KnownWebhookEvent, c as EmailAnalysis, d as EventType, f as ForwardAnalysis, g as ForwardResultAttachmentSkipped, h as ForwardResultAttachmentAnalyzed, i as DkimSignature, j as ValidateEmailAuthResult, k as SpfResult, l as EmailAuth, m as ForwardResult, n as AuthVerdict, o as DmarcResult, p as ForwardOriginalSender, r as DkimResult, s as EmailAddress, t as AuthConfidence, u as EmailReceivedEvent, v as ForwardVerdict, w as ParsedError, x as ParsedData, y as ForwardVerification } from "./types-9vXGZjPd.js";
+import { a as buildReplySubject, c as parseHeaderAddress, i as buildForwardSubject, n as ReceivedEmailAddress, o as formatAddress, r as ReceivedEmailThread, s as normalizeReceivedEmail, t as ReceivedEmail } from "./received-email-DNjpq_Wt.js";
+import { a as PrimitiveApiError, c as PrimitiveClientOptions, d as SendResult, f as SendThreadInput, h as createPrimitiveClient, l as ReplyInput, n as ForwardInput, p as client, s as PrimitiveClient, u as SendInput } from "./index-DVow4Fjd.js";
+import { A as VerifyOptions, B as PAYLOAD_ERRORS, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, G as VERIFICATION_ERRORS, H as RAW_EMAIL_ERRORS, I as generateDownloadToken, J as WebhookPayloadErrorCode, K as WebhookErrorCode, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, Q as WebhookVerificationErrorCode, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, U as RawEmailDecodeError, V as PrimitiveWebhookError, W as RawEmailDecodeErrorCode, X as WebhookValidationErrorCode, Y as WebhookValidationError, Z as WebhookVerificationError, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, q as WebhookPayloadError, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "./index-CbEivn3S.js";
+
+//#region src/index.d.ts
+declare const primitive: {
+  client: typeof client;
+  receive: typeof receive;
+};
+//#endregion
+export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, type ForwardInput, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, GenerateDownloadTokenOptions, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveApiError, PrimitiveClient, type PrimitiveClientOptions, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, ReceiveRequestOptions, ReceivedEmail, ReceivedEmailAddress, ReceivedEmailThread, type ReplyInput, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, type SendInput, type SendResult, type SendThreadInput, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, buildForwardSubject, buildReplySubject, client, confirmedHeaders, createPrimitiveClient, decodeRawEmail, primitive as default, emailReceivedEventJsonSchema, formatAddress, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, normalizeReceivedEmail, parseHeaderAddress, parseWebhookEvent, receive, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/index.js

@@ -1,3 +1,10 @@
-import { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature } from "./webhook-COe5N_Uj.js";
-
-export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+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-COSr-Fqm.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 = {
+	client,
+	receive
+};
+//#endregion
+export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveApiError, PrimitiveClient, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, buildForwardSubject, buildReplySubject, client, confirmedHeaders, createPrimitiveClient, decodeRawEmail, primitive as default, emailReceivedEventJsonSchema, formatAddress, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, normalizeReceivedEmail, parseHeaderAddress, parseWebhookEvent, receive, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/oclif/api-command.js

@@ -7,6 +7,82 @@ function flagName(parameterName) {
 function flagDescription(parameter) {
     return parameter.description ?? parameter.name;
 }
+/**
+ * Render a one-shot description of a JSON Schema's top-level
+ * properties so an agent reading `<command> --help` can build a
+ * valid `--body` payload without probing the server. Pulled from
+ * the resolved request schema embedded on the manifest.
+ *
+ * Format prioritizes scanability over completeness: required
+ * fields first, each line is `<name> <type> [- description]`
+ * truncated to a reasonable width. Callers who need the full
+ * schema can run `primitive list-operations | jq` and read
+ * `requestSchema` directly.
+ */
+function renderRequestSchemaSummary(schema) {
+    if (!schema || typeof schema !== "object")
+        return null;
+    const properties = schema.properties;
+    if (!properties || typeof properties !== "object")
+        return null;
+    const requiredArr = Array.isArray(schema.required)
+        ? schema.required.filter((k) => typeof k === "string")
+        : [];
+    const required = new Set(requiredArr);
+    const entries = Object.entries(properties)
+        .map(([name, raw]) => {
+        const propSchema = raw && typeof raw === "object" ? raw : {};
+        let type = "any";
+        const t = propSchema.type;
+        if (typeof t === "string") {
+            type = t;
+            if (type === "array") {
+                const items = propSchema.items;
+                if (items && typeof items === "object") {
+                    const itemType = items.type;
+                    if (typeof itemType === "string") {
+                        type = `array<${itemType}>`;
+                    }
+                }
+            }
+        }
+        else if (Array.isArray(t)) {
+            // Nullable shorthand the codegen normalizes to e.g. ["string","null"].
+            const nonNull = t.filter((s) => s !== "null");
+            type = nonNull.length === 1 ? `${nonNull[0]}?` : nonNull.join("|");
+        }
+        const description = typeof propSchema.description === "string"
+            ? propSchema.description.split("\n")[0].trim()
+            : "";
+        return {
+            name,
+            type,
+            description,
+            required: required.has(name),
+        };
+    })
+        .sort((a, b) => {
+        if (a.required !== b.required)
+            return a.required ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+    if (entries.length === 0)
+        return null;
+    const nameWidth = Math.min(24, Math.max(...entries.map((e) => e.name.length)));
+    const lines = ["Body fields (JSON --body):"];
+    const descMax = 78;
+    for (const e of entries) {
+        const flag = e.required ? " *" : "  ";
+        const padName = e.name.padEnd(nameWidth);
+        const trimmedDesc = e.description.length > descMax
+            ? `${e.description.slice(0, descMax - 3)}...`
+            : e.description;
+        const desc = trimmedDesc ? `  ${trimmedDesc}` : "";
+        lines.push(`${flag} ${padName}  ${e.type}${desc}`);
+    }
+    lines.push("(* = required)");
+    return lines.join("\n");
+}
 export function flagForParameter(parameter) {
     const common = {
         description: flagDescription(parameter),
@@ -159,8 +235,20 @@ function collectValues(parameters, flags) {
 }
 export function createOperationCommand(operation) {
     const flags = buildFlags(operation);
+    // Append a "Body fields" summary to the description so agents
+    // running `<command> --help` learn the JSON shape immediately.
+    // Without this, `--help` only said "JSON request body" and agents
+    // had to probe the server with malformed payloads to discover
+    // required fields. (CLI agent walkthrough surfaced this.)
+    const baseDescription = operation.description ?? `${operation.method} ${operation.path}`;
+    const schemaSummary = operation.hasJsonBody
+        ? renderRequestSchemaSummary(operation.requestSchema)
+        : null;
+    const fullDescription = schemaSummary
+        ? `${baseDescription}\n\n${schemaSummary}`
+        : baseDescription;
     class OperationCommand extends Command {
-        static description = operation.description ?? `${operation.method} ${operation.path}`;
+        static description = fullDescription;
         static flags = flags;
         static summary = operation.summary ?? `${operation.method} ${operation.path}`;
         async run() {

package/dist/openapi/index.d.ts

@@ -6,7 +6,6 @@
  * Run `pnpm generate:openapi` to regenerate.
  */
 declare const openapiDocument: Record<string, unknown>;
-
 //#endregion
 //#region src/openapi/operations.generated.d.ts
 /**
@@ -33,10 +32,16 @@ type PrimitiveOperationManifest = {
   path: string;
   pathParams: PrimitiveParameterManifest[];
   queryParams: PrimitiveParameterManifest[];
+  /**
+   * Resolved JSON Schema for the request body when `hasJsonBody` is
+   * true. `$ref`s into the OpenAPI components are inlined.
+   */
+  requestSchema: Record<string, unknown> | null;
   sdkName: string;
   summary: string | null;
   tag: string;
   tagCommand: string;
 };
-declare const operationManifest: PrimitiveOperationManifest[]; //#endregion
-export { PrimitiveOperationManifest, PrimitiveParameterManifest, openapiDocument, operationManifest };
+declare const operationManifest: PrimitiveOperationManifest[];
+//#endregion
+export { type PrimitiveOperationManifest, type PrimitiveParameterManifest, openapiDocument, operationManifest };

package/dist/openapi/openapi.generated.js

@@ -43,6 +43,10 @@ export const openapiDocument = {
             "name": "Emails",
             "description": "List, inspect, and manage received emails"
         },
+        {
+            "name": "Sending",
+            "description": "Send outbound emails through the Primitive API"
+        },
         {
             "name": "Endpoints",
             "description": "Manage webhook endpoints that receive email events"
@@ -1427,6 +1431,85 @@ export const openapiDocument = {
                     }
                 }
             }
+        },
+        "/send-mail": {
+            "post": {
+                "operationId": "sendEmail",
+                "summary": "Send outbound email",
+                "description": "Sends an outbound email through Primitive's outbound relay. By default\nthe request returns once the relay accepts the message for delivery.\nSet `wait: true` to wait for the first downstream SMTP delivery outcome.\n",
+                "tags": [
+                    "Sending"
+                ],
+                "parameters": [
+                    {
+                        "name": "Idempotency-Key",
+                        "in": "header",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 255,
+                            "pattern": "^[\\x21-\\x7E]+$"
+                        },
+                        "description": "Optional customer-supplied idempotency key. If omitted, Primitive\nderives one from the canonical request payload and echoes the\neffective value in the `Idempotency-Key` response header.\n"
+                    }
+                ],
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/SendMailInput"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Outbound relay result",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/SendMailResult"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "403": {
+                        "$ref": "#/components/responses/Forbidden"
+                    },
+                    "429": {
+                        "$ref": "#/components/responses/RateLimited"
+                    },
+                    "500": {
+                        "$ref": "#/components/responses/InternalError"
+                    },
+                    "502": {
+                        "$ref": "#/components/responses/BadGateway"
+                    },
+                    "503": {
+                        "$ref": "#/components/responses/ServiceUnavailable"
+                    }
+                }
+            }
         }
     },
     "components": {
@@ -1492,6 +1575,23 @@ export const openapiDocument = {
                     }
                 }
             },
+            "Forbidden": {
+                "description": "Authenticated caller lacks permission for the operation",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "$ref": "#/components/schemas/ErrorResponse"
+                        },
+                        "example": {
+                            "success": false,
+                            "error": {
+                                "code": "forbidden",
+                                "message": "Insufficient permissions"
+                            }
+                        }
+                    }
+                }
+            },
             "NotFound": {
                 "description": "Resource not found",
                 "content": {
@@ -1551,6 +1651,57 @@ export const openapiDocument = {
                     }
                 }
             },
+            "BadGateway": {
+                "description": "Primitive could not complete the downstream SMTP request",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "$ref": "#/components/schemas/ErrorResponse"
+                        },
+                        "example": {
+                            "success": false,
+                            "error": {
+                                "code": "outbound_unreachable",
+                                "message": "Outbound SMTP service request failed"
+                            }
+                        }
+                    }
+                }
+            },
+            "ServiceUnavailable": {
+                "description": "Primitive is temporarily unable to process the request",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "$ref": "#/components/schemas/ErrorResponse"
+                        },
+                        "example": {
+                            "success": false,
+                            "error": {
+                                "code": "outbound_capacity_exhausted",
+                                "message": "Outbound capacity is temporarily exhausted"
+                            }
+                        }
+                    }
+                }
+            },
+            "InternalError": {
+                "description": "Primitive encountered an internal error",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "$ref": "#/components/schemas/ErrorResponse"
+                        },
+                        "example": {
+                            "success": false,
+                            "error": {
+                                "code": "internal_error",
+                                "message": "Internal server error"
+                            }
+                        }
+                    }
+                }
+            },
             "Deleted": {
                 "description": "Resource deleted",
                 "content": {
@@ -1659,7 +1810,16 @@ export const openapiDocument = {
                                     "rate_limit_exceeded",
                                     "internal_error",
                                     "conflict",
-                                    "mx_conflict"
+                                    "mx_conflict",
+                                    "outbound_disabled",
+                                    "cannot_send_from_domain",
+                                    "recipient_not_allowed",
+                                    "outbound_key_missing",
+                                    "outbound_unreachable",
+                                    "outbound_key_invalid",
+                                    "outbound_capacity_exhausted",
+                                    "outbound_response_malformed",
+                                    "outbound_relay_failed"
                                 ]
                             },
                             "message": {
@@ -1687,8 +1847,38 @@ export const openapiDocument = {
                                                 "description": "Subdomain to try instead (e.g. \"mail\" for `mail.example.com`)."
                                             }
                                         }
+                                    },
+                                    "required_entitlements": {
+                                        "type": "array",
+                                        "items": {
+                                            "type": "string"
+                                        },
+                                        "description": "Entitlements that would allow a denied send when no recipient-scope gate was granted."
+                                    },
+                                    "sent_email_id": {
+                                        "type": "string",
+                                        "description": "ID of the persisted sent-email attempt associated with the error."
+                                    },
+                                    "content_hash": {
+                                        "type": "string",
+                                        "description": "Content hash of the original request on idempotency cache-hit errors."
+                                    },
+                                    "client_idempotency_key": {
+                                        "type": "string",
+                                        "description": "Effective idempotency key associated with the original request."
                                     }
                                 }
+                            },
+                            "gates": {
+                                "type": "array",
+                                "items": {
+                                    "$ref": "#/components/schemas/GateDenial"
+                                },
+                                "description": "Structured per-gate denial detail for recipient-scope send-mail failures."
+                            },
+                            "request_id": {
+                                "type": "string",
+                                "description": "Server-issued request identifier for support and tracing."
                             }
                         },
                         "required": [
@@ -1702,6 +1892,71 @@ export const openapiDocument = {
                     "error"
                 ]
             },
+            "GateDenial": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "enum": [
+                            "send_to_confirmed_domains",
+                            "send_to_known_addresses"
+                        ],
+                        "description": "Public recipient-scope gate name that denied the send."
+                    },
+                    "reason": {
+                        "type": "string",
+                        "enum": [
+                            "domain_not_confirmed",
+                            "recipient_unauthenticated",
+                            "recipient_not_known"
+                        ],
+                        "description": "Stable machine-readable denial reason."
+                    },
+                    "message": {
+                        "type": "string",
+                        "description": "Human-readable explanation of the gate denial."
+                    },
+                    "subject": {
+                        "type": "string",
+                        "description": "Domain or address the gate evaluated."
+                    },
+                    "fix": {
+                        "$ref": "#/components/schemas/GateFix"
+                    },
+                    "docs_url": {
+                        "type": "string",
+                        "description": "Public docs URL with more context."
+                    }
+                },
+                "required": [
+                    "name",
+                    "reason",
+                    "message",
+                    "subject"
+                ]
+            },
+            "GateFix": {
+                "type": "object",
+                "properties": {
+                    "action": {
+                        "type": "string",
+                        "enum": [
+                            "confirm_domain",
+                            "sender_must_fix_authentication",
+                            "wait_for_inbound"
+                        ],
+                        "description": "Suggested next action for the caller."
+                    },
+                    "subject": {
+                        "type": "string",
+                        "description": "Entity the action applies to."
+                    }
+                },
+                "required": [
+                    "action",
+                    "subject"
+                ]
+            },
             "Account": {
                 "type": "object",
                 "properties": {
@@ -2337,6 +2592,162 @@ export const openapiDocument = {
                     "to_email"
                 ]
             },
+            "SendMailInput": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "from": {
+                        "type": "string",
+                        "minLength": 3,
+                        "maxLength": 998,
+                        "description": "RFC 5322 From header. The sender domain must be a verified outbound domain for your organization."
+                    },
+                    "to": {
+                        "type": "string",
+                        "minLength": 3,
+                        "maxLength": 320,
+                        "description": "Recipient address. Recipient eligibility depends on your account's outbound entitlements."
+                    },
+                    "subject": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 998,
+                        "description": "Subject line for the outbound message"
+                    },
+                    "body_text": {
+                        "type": "string",
+                        "description": "Plain-text message body. At least one of body_text or body_html is required. The combined UTF-8 byte length of body_text and body_html must be at most 262144 bytes."
+                    },
+                    "body_html": {
+                        "type": "string",
+                        "description": "HTML message body. At least one of body_text or body_html is required. The combined UTF-8 byte length of body_text and body_html must be at most 262144 bytes."
+                    },
+                    "in_reply_to": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 998,
+                        "pattern": "^[^\\x00-\\x1F\\x7F]+$",
+                        "description": "Message-ID of the direct parent email when sending a threaded reply."
+                    },
+                    "references": {
+                        "type": "array",
+                        "maxItems": 100,
+                        "description": "Full ordered message-id chain for the thread.",
+                        "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 998,
+                            "pattern": "^[^\\x00-\\x1F\\x7F]+$"
+                        }
+                    },
+                    "wait": {
+                        "type": "boolean",
+                        "description": "When true, wait for the first downstream SMTP delivery outcome before returning."
+                    },
+                    "wait_timeout_ms": {
+                        "type": "integer",
+                        "minimum": 1000,
+                        "maximum": 30000,
+                        "description": "Maximum time to wait for a delivery outcome when wait is true. Defaults to 30000."
+                    }
+                },
+                "required": [
+                    "from",
+                    "to",
+                    "subject"
+                ]
+            },
+            "SentEmailStatus": {
+                "type": "string",
+                "enum": [
+                    "queued",
+                    "submitted_to_agent",
+                    "agent_failed",
+                    "unknown",
+                    "delivered",
+                    "bounced",
+                    "deferred",
+                    "wait_timeout"
+                ]
+            },
+            "DeliveryStatus": {
+                "type": "string",
+                "enum": [
+                    "delivered",
+                    "bounced",
+                    "deferred",
+                    "wait_timeout"
+                ]
+            },
+            "SendMailResult": {
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "description": "Persisted sent-email attempt ID."
+                    },
+                    "status": {
+                        "$ref": "#/components/schemas/SentEmailStatus"
+                    },
+                    "queue_id": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "description": "Message identifier assigned by Primitive's outbound relay, when available."
+                    },
+                    "accepted": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        },
+                        "description": "Recipient addresses accepted by the relay."
+                    },
+                    "rejected": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        },
+                        "description": "Recipient addresses rejected by the relay."
+                    },
+                    "client_idempotency_key": {
+                        "type": "string",
+                        "description": "Effective idempotency key used for this send."
+                    },
+                    "request_id": {
+                        "type": "string",
+                        "description": "Server-issued request identifier for support and tracing."
+                    },
+                    "content_hash": {
+                        "type": "string",
+                        "description": "Stable hash of the canonical send payload."
+                    },
+                    "delivery_status": {
+                        "$ref": "#/components/schemas/DeliveryStatus"
+                    },
+                    "smtp_response_code": {
+                        "type": [
+                            "integer",
+                            "null"
+                        ],
+                        "description": "SMTP response code from the first downstream delivery outcome when wait is true."
+                    },
+                    "smtp_response_text": {
+                        "type": "string",
+                        "description": "SMTP response text from the first downstream delivery outcome when wait is true."
+                    }
+                },
+                "required": [
+                    "id",
+                    "status",
+                    "queue_id",
+                    "accepted",
+                    "rejected",
+                    "client_idempotency_key",
+                    "request_id",
+                    "content_hash"
+                ]
+            },
             "Endpoint": {
                 "type": "object",
                 "properties": {