@primitivedotdev/sdk 0.12.0 → 0.13.0

package/dist/api/generated/index.js

@@ -1,2 +1,2 @@
 // This file is auto-generated by @hey-api/openapi-ts
-export { addDomain, createEndpoint, createFilter, deleteDomain, deleteEmail, deleteEndpoint, deleteFilter, downloadAttachments, downloadRawEmail, getAccount, getEmail, getStorageStats, getWebhookSecret, listDeliveries, listDomains, listEmails, listEndpoints, listFilters, replayDelivery, replayEmailWebhooks, replyToEmail, rotateWebhookSecret, sendEmail, testEndpoint, updateAccount, updateDomain, updateEndpoint, updateFilter, verifyDomain } from './sdk.gen.js';
+export { addDomain, createEndpoint, createFilter, deleteDomain, deleteEmail, deleteEndpoint, deleteFilter, downloadAttachments, downloadRawEmail, getAccount, getEmail, getSendPermissions, getStorageStats, getWebhookSecret, listDeliveries, listDomains, listEmails, listEndpoints, listFilters, replayDelivery, replayEmailWebhooks, replyToEmail, rotateWebhookSecret, sendEmail, testEndpoint, updateAccount, updateDomain, updateEndpoint, updateFilter, verifyDomain } from './sdk.gen.js';

package/dist/api/generated/sdk.gen.js

@@ -122,11 +122,15 @@ export const verifyDomain = (options) => (options.client ?? client).post({
     ...options
 });
 /**
- * List emails
+ * List inbound emails
  *
- * Returns a paginated list of received emails. Supports filtering by
- * domain, status, date range, and free-text search across subject,
- * sender, and recipient fields.
+ * Returns a paginated list of INBOUND emails received at your
+ * verified domains. Outbound messages sent via /send-mail are not
+ * included; this endpoint is the inbox view, not a unified
+ * send/receive history.
+ *
+ * Supports filtering by domain, status, date range, and free-text
+ * search across subject, sender, and recipient fields.
  *
  */
 export const listEmails = (options) => (options?.client ?? client).get({
@@ -371,6 +375,46 @@ export const replayDelivery = (options) => (options.client ?? client).post({
     url: '/webhooks/deliveries/{id}/replay',
     ...options
 });
+/**
+ * List send-permission rules
+ *
+ * Returns a flat list of rules describing every recipient the
+ * caller may send to. Each rule has a `type`, a kind-specific
+ * payload, and a human-readable `description`. If any rule
+ * matches the recipient, /send-mail will accept the send under
+ * the recipient-scope check.
+ *
+ * The endpoint is the answer to "where can I send" without
+ * exposing internal entitlement names. Agents that don't
+ * recognize a `type` can still read the `description` prose
+ * and act on it.
+ *
+ * Rule kinds, ordered broadest-first so an agent can stop
+ * scanning at the first match:
+ *
+ * 1. `any_recipient` (one entry, only when the org can send
+ * anywhere): every other rule below it is redundant.
+ * 2. `managed_zone` (always emitted, one per Primitive-managed
+ * zone): sends to any address at *.primitive.email or
+ * *.email.works always succeed; no entitlement required.
+ * 3. `your_domain` (one per active verified outbound domain
+ * owned by the org): sends to that domain are approved.
+ * 4. `address` (one per address that has authenticated
+ * inbound mail to the org, capped at `meta.address_cap`):
+ * sends to that exact address are approved.
+ *
+ * The list is informational, not an authorization check.
+ * /send-mail remains the source of truth on whether an
+ * individual send will succeed (it also enforces the
+ * from-address and the `send_mail` entitlement, which are
+ * not recipient-scope concerns and are not represented here).
+ *
+ */
+export const getSendPermissions = (options) => (options?.client ?? client).get({
+    security: [{ scheme: 'bearer', type: 'http' }],
+    url: '/send-permissions',
+    ...options
+});
 /**
  * Send outbound email
  *

package/dist/api/index.d.ts

@@ -1,2 +1,2 @@
-import { $ as AddDomainResponse, $n as ReplayDeliveryErrors, $r as UpdateEndpointResponses, $t as ErrorResponse, A as getWebhookSecret, An as ListDomainsError, Ar as TestEndpointError, At as DeleteFilterData, B as sendEmail, Bn as ListEndpointsError, Br as UpdateAccountResponse, Bt as DownloadAttachmentsError, C as deleteEndpoint, Cn as Limit, Cr as SendEmailResponses, Ct as DeleteEmailResponse, D as getAccount, Dn as ListDeliveriesResponse, Dr as StorageStats, Dt as DeleteEndpointErrors, E as downloadRawEmail, En as ListDeliveriesErrors, Er as SentEmailStatus, Et as DeleteEndpointError, F as listFilters, Fn as ListEmailsError, Fr as UnverifiedDomain, Ft as DeliveryStatus, G as updateFilter, Gn as ListFiltersData, Gr as UpdateDomainInput, Gt as DownloadRawEmailError, H as updateAccount, Hn as ListEndpointsResponse, Hr as UpdateDomainData, Ht as DownloadAttachmentsResponse, I as replayDelivery, In as ListEmailsErrors, Ir as UpdateAccountData, It as DeliverySummary, J as AccountUpdated, Jn as ListFiltersResponse, Jr as UpdateEndpointData, Jt as DownloadRawEmailResponses, K as verifyDomain, Kn as ListFiltersError, Kr as UpdateDomainResponse, Kt as DownloadRawEmailErrors, L as replayEmailWebhooks, Ln as ListEmailsResponse, Lr as UpdateAccountError, Lt as Domain, M as listDomains, Mn as ListDomainsResponse, Mr as TestEndpointResponse, Mt as DeleteFilterErrors, N as listEmails, Nn as ListDomainsResponses, Nr as TestEndpointResponses, Nt as DeleteFilterResponse, O as getEmail, On as ListDeliveriesResponses, Or as SuccessEnvelope, Ot as DeleteEndpointResponse, P as listEndpoints, Pn as ListEmailsData, Pr as TestResult, Pt as DeleteFilterResponses, Q as AddDomainInput, Qn as ReplayDeliveryError, Qr as UpdateEndpointResponse, Qt as Endpoint, R as replyToEmail, Rn as ListEmailsResponses, Rr as UpdateAccountErrors, Rt as DomainVerifyResult, S as deleteEmail, Sn as GetWebhookSecretResponses, Sr as SendEmailResponse, St as DeleteEmailErrors, T as downloadAttachments, Tn as ListDeliveriesError, Tr as SendMailResult, Tt as DeleteEndpointData, U as updateDomain, Un as ListEndpointsResponses, Ur as UpdateDomainError, Ut as DownloadAttachmentsResponses, V as testEndpoint, Vn as ListEndpointsErrors, Vr as UpdateAccountResponses, Vt as DownloadAttachmentsErrors, W as updateEndpoint, Wn as ListEnvelope, Wr as UpdateDomainErrors, Wt as DownloadRawEmailData, X as AddDomainError, Xn as PaginationMeta, Xr as UpdateEndpointErrors, Xt as EmailDetailReply, Y as AddDomainData, Yn as ListFiltersResponses, Yr as UpdateEndpointError, Yt as EmailDetail, Z as AddDomainErrors, Zn as ReplayDeliveryData, Zr as UpdateEndpointInput, Zt as EmailSummary, _ as Options, _i as Options$1, _n as GetStorageStatsResponses, _r as RotateWebhookSecretResponse, _t as DeleteDomainErrors, a as PrimitiveApiError, ai as UpdateFilterResponses, an as GetAccountErrors, ar as ReplayEmailWebhooksResponse, at as CreateEndpointInput, b as createFilter, bi as ResponseStyle, bn as GetWebhookSecretErrors, br as SendEmailError, bt as DeleteEmailData, c as PrimitiveClientOptions, ci as VerifyDomainError, cn as GetEmailData, cr as ReplyToEmailData, ct as CreateFilterData, d as SendResult, di as VerifyDomainResponses, dn as GetEmailResponse, dr as ReplyToEmailResponse, dt as CreateFilterInput, ei as UpdateFilterData, en as Filter, er as ReplayDeliveryResponse, et as AddDomainResponses, f as SendThreadInput, fi as WebhookSecret, fn as GetEmailResponses, fr as ReplyToEmailResponses, ft as CreateFilterResponse, g as operations, gi as CreateClientConfig, gn as GetStorageStatsResponse, gr as RotateWebhookSecretErrors, gt as DeleteDomainError, h as createPrimitiveClient, hi as Config, hn as GetStorageStatsErrors, hr as RotateWebhookSecretError, ht as DeleteDomainData, i as PrimitiveApiClientOptions, ii as UpdateFilterResponse, in as GetAccountError, ir as ReplayEmailWebhooksErrors, it as CreateEndpointErrors, j as listDeliveries, jn as ListDomainsErrors, jr as TestEndpointErrors, jt as DeleteFilterError, k as getStorageStats, kn as ListDomainsData, kr as TestEndpointData, kt as DeleteEndpointResponses, l as ReplyInput, li as VerifyDomainErrors, ln as GetEmailError, lr as ReplyToEmailError, lt as CreateFilterError, m as createPrimitiveApiClient, mi as ClientOptions$1, mn as GetStorageStatsError, mr as RotateWebhookSecretData, mt as Cursor, n as ForwardInput, ni as UpdateFilterErrors, nn as GateFix, nr as ReplayEmailWebhooksData, nt as CreateEndpointData, o as PrimitiveApiErrorDetails, oi as VerifiedDomain, on as GetAccountResponse, or as ReplayEmailWebhooksResponses, ot as CreateEndpointResponse, p as client, pi as Client, pn as GetStorageStatsData, pr as ResourceId, pt as CreateFilterResponses, q as Account, qn as ListFiltersErrors, qr as UpdateDomainResponses, qt as DownloadRawEmailResponse, r as PrimitiveApiClient, ri as UpdateFilterInput, rn as GetAccountData, rr as ReplayEmailWebhooksError, rt as CreateEndpointError, s as PrimitiveClient, si as VerifyDomainData, sn as GetAccountResponses, sr as ReplayResult, st as CreateEndpointResponses, t as DEFAULT_BASE_URL, ti as UpdateFilterError, tn as GateDenial, tr as ReplayDeliveryResponses, tt as ClientOptions, u as SendInput, ui as VerifyDomainResponse, un as GetEmailErrors, ur as ReplyToEmailErrors, ut as CreateFilterErrors, v as addDomain, vi as RequestOptions, vn as GetWebhookSecretData, vr as RotateWebhookSecretResponses, vt as DeleteDomainResponse, w as deleteFilter, wn as ListDeliveriesData, wr as SendMailInput, wt as DeleteEmailResponses, x as deleteDomain, xi as Auth, xn as GetWebhookSecretResponse, xr as SendEmailErrors, xt as DeleteEmailError, y as createEndpoint, yi as RequestResult, yn as GetWebhookSecretError, yr as SendEmailData, yt as DeleteDomainResponses, z as rotateWebhookSecret, zn as ListEndpointsData, zr as UpdateAccountInput, zt as DownloadAttachmentsData } from "../index-K4KbjppU.js";
-export { Account, AccountUpdated, AddDomainData, AddDomainError, AddDomainErrors, AddDomainInput, AddDomainResponse, AddDomainResponses, Auth, ClientOptions, CreateClientConfig, CreateEndpointData, CreateEndpointError, CreateEndpointErrors, CreateEndpointInput, CreateEndpointResponse, CreateEndpointResponses, CreateFilterData, CreateFilterError, CreateFilterErrors, CreateFilterInput, CreateFilterResponse, CreateFilterResponses, Cursor, DEFAULT_BASE_URL, DeleteDomainData, DeleteDomainError, DeleteDomainErrors, DeleteDomainResponse, DeleteDomainResponses, DeleteEmailData, DeleteEmailError, DeleteEmailErrors, DeleteEmailResponse, DeleteEmailResponses, DeleteEndpointData, DeleteEndpointError, DeleteEndpointErrors, DeleteEndpointResponse, DeleteEndpointResponses, DeleteFilterData, DeleteFilterError, DeleteFilterErrors, DeleteFilterResponse, DeleteFilterResponses, DeliveryStatus, DeliverySummary, Domain, DomainVerifyResult, DownloadAttachmentsData, DownloadAttachmentsError, DownloadAttachmentsErrors, DownloadAttachmentsResponse, DownloadAttachmentsResponses, DownloadRawEmailData, DownloadRawEmailError, DownloadRawEmailErrors, DownloadRawEmailResponse, DownloadRawEmailResponses, EmailDetail, EmailDetailReply, EmailSummary, Endpoint, ErrorResponse, Filter, ForwardInput, GateDenial, GateFix, GetAccountData, GetAccountError, GetAccountErrors, GetAccountResponse, GetAccountResponses, GetEmailData, GetEmailError, GetEmailErrors, GetEmailResponse, GetEmailResponses, GetStorageStatsData, GetStorageStatsError, GetStorageStatsErrors, GetStorageStatsResponse, GetStorageStatsResponses, GetWebhookSecretData, GetWebhookSecretError, GetWebhookSecretErrors, GetWebhookSecretResponse, GetWebhookSecretResponses, Limit, ListDeliveriesData, ListDeliveriesError, ListDeliveriesErrors, ListDeliveriesResponse, ListDeliveriesResponses, ListDomainsData, ListDomainsError, ListDomainsErrors, ListDomainsResponse, ListDomainsResponses, ListEmailsData, ListEmailsError, ListEmailsErrors, ListEmailsResponse, ListEmailsResponses, ListEndpointsData, ListEndpointsError, ListEndpointsErrors, ListEndpointsResponse, ListEndpointsResponses, ListEnvelope, ListFiltersData, ListFiltersError, ListFiltersErrors, ListFiltersResponse, ListFiltersResponses, Options, PaginationMeta, PrimitiveApiClient, PrimitiveApiClientOptions, PrimitiveApiError, PrimitiveApiErrorDetails, PrimitiveClient, PrimitiveClientOptions, Client as PrimitiveGeneratedApiClient, ClientOptions$1 as PrimitiveGeneratedApiClientOptions, Config as PrimitiveGeneratedApiConfig, Options$1 as PrimitiveGeneratedApiOptions, RequestOptions as PrimitiveGeneratedApiRequestOptions, RequestResult as PrimitiveGeneratedApiRequestResult, ReplayDeliveryData, ReplayDeliveryError, ReplayDeliveryErrors, ReplayDeliveryResponse, ReplayDeliveryResponses, ReplayEmailWebhooksData, ReplayEmailWebhooksError, ReplayEmailWebhooksErrors, ReplayEmailWebhooksResponse, ReplayEmailWebhooksResponses, ReplayResult, ReplyInput, ReplyToEmailData, ReplyToEmailError, ReplyToEmailErrors, ReplyToEmailResponse, ReplyToEmailResponses, ResourceId, ResponseStyle, RotateWebhookSecretData, RotateWebhookSecretError, RotateWebhookSecretErrors, RotateWebhookSecretResponse, RotateWebhookSecretResponses, SendEmailData, SendEmailError, SendEmailErrors, SendEmailResponse, SendEmailResponses, SendInput, SendMailInput, SendMailResult, SendResult, SendThreadInput, SentEmailStatus, StorageStats, SuccessEnvelope, TestEndpointData, TestEndpointError, TestEndpointErrors, TestEndpointResponse, TestEndpointResponses, TestResult, UnverifiedDomain, UpdateAccountData, UpdateAccountError, UpdateAccountErrors, UpdateAccountInput, UpdateAccountResponse, UpdateAccountResponses, UpdateDomainData, UpdateDomainError, UpdateDomainErrors, UpdateDomainInput, UpdateDomainResponse, UpdateDomainResponses, UpdateEndpointData, UpdateEndpointError, UpdateEndpointErrors, UpdateEndpointInput, UpdateEndpointResponse, UpdateEndpointResponses, UpdateFilterData, UpdateFilterError, UpdateFilterErrors, UpdateFilterInput, UpdateFilterResponse, UpdateFilterResponses, VerifiedDomain, VerifyDomainData, VerifyDomainError, VerifyDomainErrors, VerifyDomainResponse, VerifyDomainResponses, WebhookSecret, addDomain, client, createEndpoint, createFilter, createPrimitiveApiClient, createPrimitiveClient, deleteDomain, deleteEmail, deleteEndpoint, deleteFilter, downloadAttachments, downloadRawEmail, getAccount, getEmail, getStorageStats, getWebhookSecret, listDeliveries, listDomains, listEmails, listEndpoints, listFilters, operations, replayDelivery, replayEmailWebhooks, replyToEmail, rotateWebhookSecret, sendEmail, testEndpoint, updateAccount, updateDomain, updateEndpoint, updateFilter, verifyDomain };
+import { $ as AddDomainInput, $n as ListFiltersErrors, $r as UpdateAccountResponses, $t as Endpoint, A as getStorageStats, Ai as RequestOptions, An as ListDeliveriesData, Ar as SendMailInput, At as DeleteEndpointResponses, B as rotateWebhookSecret, Bn as ListEmailsData, Br as SuccessEnvelope, Bt as DownloadAttachmentsData, C as deleteEndpoint, Ci as VerifyDomainResponses, Cn as GetStorageStatsResponses, Cr as RotateWebhookSecretResponse, Ct as DeleteEmailErrors, D as getAccount, Di as Config, Dn as GetWebhookSecretResponse, Dr as SendEmailErrors, Dt as DeleteEndpointError, E as downloadRawEmail, Ei as ClientOptions$1, En as GetWebhookSecretErrors, Er as SendEmailError, Et as DeleteEndpointData, F as listEndpoints, Fn as ListDomainsData, Fr as SendPermissionRule, Ft as DeleteFilterResponses, G as updateEndpoint, Gn as ListEndpointsData, Gr as TestEndpointResponses, Gt as DownloadRawEmailData, H as testEndpoint, Hn as ListEmailsErrors, Hr as TestEndpointError, Ht as DownloadAttachmentsErrors, I as listFilters, In as ListDomainsError, Ir as SendPermissionYourDomain, It as DeliveryStatus, J as Account, Jn as ListEndpointsResponse, Jr as UpdateAccountData, Jt as DownloadRawEmailResponse, K as updateFilter, Kn as ListEndpointsError, Kr as TestResult, Kt as DownloadRawEmailError, L as replayDelivery, Ln as ListDomainsErrors, Lr as SendPermissionsMeta, Lt as DeliverySummary, M as listDeliveries, Mi as ResponseStyle, Mn as ListDeliveriesErrors, Mr as SendPermissionAddress, Mt as DeleteFilterError, N as listDomains, Ni as Auth, Nn as ListDeliveriesResponse, Nr as SendPermissionAnyRecipient, Nt as DeleteFilterErrors, O as getEmail, Oi as CreateClientConfig, On as GetWebhookSecretResponses, Or as SendEmailResponse, Ot as DeleteEndpointErrors, P as listEmails, Pn as ListDeliveriesResponses, Pr as SendPermissionManagedZone, Pt as DeleteFilterResponse, Q as AddDomainErrors, Qn as ListFiltersError, Qr as UpdateAccountResponse, Qt as EmailSummary, R as replayEmailWebhooks, Rn as ListDomainsResponse, Rr as SentEmailStatus, Rt as Domain, S as deleteEmail, Si as VerifyDomainResponse, Sn as GetStorageStatsResponse, Sr as RotateWebhookSecretErrors, St as DeleteEmailError, T as downloadAttachments, Ti as Client, Tn as GetWebhookSecretError, Tr as SendEmailData, Tt as DeleteEmailResponses, U as updateAccount, Un as ListEmailsResponse, Ur as TestEndpointErrors, Ut as DownloadAttachmentsResponse, V as sendEmail, Vn as ListEmailsError, Vr as TestEndpointData, Vt as DownloadAttachmentsError, W as updateDomain, Wn as ListEmailsResponses, Wr as TestEndpointResponse, Wt as DownloadAttachmentsResponses, X as AddDomainData, Xn as ListEnvelope, Xr as UpdateAccountErrors, Xt as EmailDetail, Y as AccountUpdated, Yn as ListEndpointsResponses, Yr as UpdateAccountError, Yt as DownloadRawEmailResponses, Z as AddDomainError, Zn as ListFiltersData, Zr as UpdateAccountInput, Zt as EmailDetailReply, _ as Options, _i as UpdateFilterResponses, _n as GetSendPermissionsResponse, _r as ReplyToEmailResponse, _t as DeleteDomainError, a as PrimitiveApiError, ai as UpdateDomainResponses, an as GetAccountError, ar as ReplayDeliveryErrors, at as CreateEndpointErrors, b as createFilter, bi as VerifyDomainError, bn as GetStorageStatsError, br as RotateWebhookSecretData, bt as DeleteDomainResponses, c as PrimitiveClientOptions, ci as UpdateEndpointErrors, cn as GetAccountResponses, cr as ReplayEmailWebhooksData, ct as CreateEndpointResponses, d as SendResult, di as UpdateEndpointResponses, dn as GetEmailErrors, dr as ReplayEmailWebhooksResponse, dt as CreateFilterErrors, ei as UpdateDomainData, en as ErrorResponse, er as ListFiltersResponse, et as AddDomainResponse, f as SendThreadInput, fi as UpdateFilterData, fn as GetEmailResponse, fr as ReplayEmailWebhooksResponses, ft as CreateFilterInput, g as operations, gi as UpdateFilterResponse, gn as GetSendPermissionsErrors, gr as ReplyToEmailErrors, gt as DeleteDomainData, h as createPrimitiveClient, hi as UpdateFilterInput, hn as GetSendPermissionsError, hr as ReplyToEmailError, ht as Cursor, i as PrimitiveApiClientOptions, ii as UpdateDomainResponse, in as GetAccountData, ir as ReplayDeliveryError, it as CreateEndpointError, j as getWebhookSecret, ji as RequestResult, jn as ListDeliveriesError, jr as SendMailResult, jt as DeleteFilterData, k as getSendPermissions, ki as Options$1, kn as Limit, kr as SendEmailResponses, kt as DeleteEndpointResponse, l as ReplyInput, li as UpdateEndpointInput, ln as GetEmailData, lr as ReplayEmailWebhooksError, lt as CreateFilterData, m as createPrimitiveApiClient, mi as UpdateFilterErrors, mn as GetSendPermissionsData, mr as ReplyToEmailData, mt as CreateFilterResponses, n as ForwardInput, ni as UpdateDomainErrors, nn as GateDenial, nr as PaginationMeta, nt as ClientOptions, o as PrimitiveApiErrorDetails, oi as UpdateEndpointData, on as GetAccountErrors, or as ReplayDeliveryResponse, ot as CreateEndpointInput, p as client, pi as UpdateFilterError, pn as GetEmailResponses, pr as ReplayResult, pt as CreateFilterResponse, q as verifyDomain, qn as ListEndpointsErrors, qr as UnverifiedDomain, qt as DownloadRawEmailErrors, r as PrimitiveApiClient, ri as UpdateDomainInput, rn as GateFix, rr as ReplayDeliveryData, rt as CreateEndpointData, s as PrimitiveClient, si as UpdateEndpointError, sn as GetAccountResponse, sr as ReplayDeliveryResponses, st as CreateEndpointResponse, t as DEFAULT_BASE_URL, ti as UpdateDomainError, tn as Filter, tr as ListFiltersResponses, tt as AddDomainResponses, u as SendInput, ui as UpdateEndpointResponse, un as GetEmailError, ur as ReplayEmailWebhooksErrors, ut as CreateFilterError, v as addDomain, vi as VerifiedDomain, vn as GetSendPermissionsResponses, vr as ReplyToEmailResponses, vt as DeleteDomainErrors, w as deleteFilter, wi as WebhookSecret, wn as GetWebhookSecretData, wr as RotateWebhookSecretResponses, wt as DeleteEmailResponse, x as deleteDomain, xi as VerifyDomainErrors, xn as GetStorageStatsErrors, xr as RotateWebhookSecretError, xt as DeleteEmailData, y as createEndpoint, yi as VerifyDomainData, yn as GetStorageStatsData, yr as ResourceId, yt as DeleteDomainResponse, z as replyToEmail, zn as ListDomainsResponses, zr as StorageStats, zt as DomainVerifyResult } from "../index-ChLFXxTa.js";
+export { Account, AccountUpdated, AddDomainData, AddDomainError, AddDomainErrors, AddDomainInput, AddDomainResponse, AddDomainResponses, Auth, ClientOptions, CreateClientConfig, CreateEndpointData, CreateEndpointError, CreateEndpointErrors, CreateEndpointInput, CreateEndpointResponse, CreateEndpointResponses, CreateFilterData, CreateFilterError, CreateFilterErrors, CreateFilterInput, CreateFilterResponse, CreateFilterResponses, Cursor, DEFAULT_BASE_URL, DeleteDomainData, DeleteDomainError, DeleteDomainErrors, DeleteDomainResponse, DeleteDomainResponses, DeleteEmailData, DeleteEmailError, DeleteEmailErrors, DeleteEmailResponse, DeleteEmailResponses, DeleteEndpointData, DeleteEndpointError, DeleteEndpointErrors, DeleteEndpointResponse, DeleteEndpointResponses, DeleteFilterData, DeleteFilterError, DeleteFilterErrors, DeleteFilterResponse, DeleteFilterResponses, DeliveryStatus, DeliverySummary, Domain, DomainVerifyResult, DownloadAttachmentsData, DownloadAttachmentsError, DownloadAttachmentsErrors, DownloadAttachmentsResponse, DownloadAttachmentsResponses, DownloadRawEmailData, DownloadRawEmailError, DownloadRawEmailErrors, DownloadRawEmailResponse, DownloadRawEmailResponses, EmailDetail, EmailDetailReply, EmailSummary, Endpoint, ErrorResponse, Filter, ForwardInput, GateDenial, GateFix, GetAccountData, GetAccountError, GetAccountErrors, GetAccountResponse, GetAccountResponses, GetEmailData, GetEmailError, GetEmailErrors, GetEmailResponse, GetEmailResponses, GetSendPermissionsData, GetSendPermissionsError, GetSendPermissionsErrors, GetSendPermissionsResponse, GetSendPermissionsResponses, GetStorageStatsData, GetStorageStatsError, GetStorageStatsErrors, GetStorageStatsResponse, GetStorageStatsResponses, GetWebhookSecretData, GetWebhookSecretError, GetWebhookSecretErrors, GetWebhookSecretResponse, GetWebhookSecretResponses, Limit, ListDeliveriesData, ListDeliveriesError, ListDeliveriesErrors, ListDeliveriesResponse, ListDeliveriesResponses, ListDomainsData, ListDomainsError, ListDomainsErrors, ListDomainsResponse, ListDomainsResponses, ListEmailsData, ListEmailsError, ListEmailsErrors, ListEmailsResponse, ListEmailsResponses, ListEndpointsData, ListEndpointsError, ListEndpointsErrors, ListEndpointsResponse, ListEndpointsResponses, ListEnvelope, ListFiltersData, ListFiltersError, ListFiltersErrors, ListFiltersResponse, ListFiltersResponses, Options, PaginationMeta, PrimitiveApiClient, PrimitiveApiClientOptions, PrimitiveApiError, PrimitiveApiErrorDetails, PrimitiveClient, PrimitiveClientOptions, Client as PrimitiveGeneratedApiClient, ClientOptions$1 as PrimitiveGeneratedApiClientOptions, Config as PrimitiveGeneratedApiConfig, Options$1 as PrimitiveGeneratedApiOptions, RequestOptions as PrimitiveGeneratedApiRequestOptions, RequestResult as PrimitiveGeneratedApiRequestResult, ReplayDeliveryData, ReplayDeliveryError, ReplayDeliveryErrors, ReplayDeliveryResponse, ReplayDeliveryResponses, ReplayEmailWebhooksData, ReplayEmailWebhooksError, ReplayEmailWebhooksErrors, ReplayEmailWebhooksResponse, ReplayEmailWebhooksResponses, ReplayResult, ReplyInput, ReplyToEmailData, ReplyToEmailError, ReplyToEmailErrors, ReplyToEmailResponse, ReplyToEmailResponses, ResourceId, ResponseStyle, RotateWebhookSecretData, RotateWebhookSecretError, RotateWebhookSecretErrors, RotateWebhookSecretResponse, RotateWebhookSecretResponses, SendEmailData, SendEmailError, SendEmailErrors, SendEmailResponse, SendEmailResponses, SendInput, SendMailInput, SendMailResult, SendPermissionAddress, SendPermissionAnyRecipient, SendPermissionManagedZone, SendPermissionRule, SendPermissionYourDomain, SendPermissionsMeta, SendResult, SendThreadInput, SentEmailStatus, StorageStats, SuccessEnvelope, TestEndpointData, TestEndpointError, TestEndpointErrors, TestEndpointResponse, TestEndpointResponses, TestResult, UnverifiedDomain, UpdateAccountData, UpdateAccountError, UpdateAccountErrors, UpdateAccountInput, UpdateAccountResponse, UpdateAccountResponses, UpdateDomainData, UpdateDomainError, UpdateDomainErrors, UpdateDomainInput, UpdateDomainResponse, UpdateDomainResponses, UpdateEndpointData, UpdateEndpointError, UpdateEndpointErrors, UpdateEndpointInput, UpdateEndpointResponse, UpdateEndpointResponses, UpdateFilterData, UpdateFilterError, UpdateFilterErrors, UpdateFilterInput, UpdateFilterResponse, UpdateFilterResponses, VerifiedDomain, VerifyDomainData, VerifyDomainError, VerifyDomainErrors, VerifyDomainResponse, VerifyDomainResponses, WebhookSecret, addDomain, client, createEndpoint, createFilter, createPrimitiveApiClient, createPrimitiveClient, deleteDomain, deleteEmail, deleteEndpoint, deleteFilter, downloadAttachments, downloadRawEmail, getAccount, getEmail, getSendPermissions, getStorageStats, getWebhookSecret, listDeliveries, listDomains, listEmails, listEndpoints, listFilters, operations, replayDelivery, replayEmailWebhooks, replyToEmail, rotateWebhookSecret, sendEmail, testEndpoint, updateAccount, updateDomain, updateEndpoint, updateFilter, verifyDomain };

package/dist/{api-CLLpjjWy.js → api-DvJpdOJ8.js}

@@ -624,6 +624,7 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	downloadRawEmail: () => downloadRawEmail,
 	getAccount: () => getAccount,
 	getEmail: () => getEmail,
+	getSendPermissions: () => getSendPermissions,
 	getStorageStats: () => getStorageStats,
 	getWebhookSecret: () => getWebhookSecret,
 	listDeliveries: () => listDeliveries,
@@ -795,11 +796,15 @@ const verifyDomain = (options) => (options.client ?? client$1).post({
 	...options
 });
 /**
-* List emails
+* List inbound emails
 *
-* Returns a paginated list of received emails. Supports filtering by
-* domain, status, date range, and free-text search across subject,
-* sender, and recipient fields.
+* Returns a paginated list of INBOUND emails received at your
+* verified domains. Outbound messages sent via /send-mail are not
+* included; this endpoint is the inbox view, not a unified
+* send/receive history.
+*
+* Supports filtering by domain, status, date range, and free-text
+* search across subject, sender, and recipient fields.
 *
 */
 const listEmails = (options) => (options?.client ?? client$1).get({
@@ -1099,6 +1104,49 @@ const replayDelivery = (options) => (options.client ?? client$1).post({
 	...options
 });
 /**
+* List send-permission rules
+*
+* Returns a flat list of rules describing every recipient the
+* caller may send to. Each rule has a `type`, a kind-specific
+* payload, and a human-readable `description`. If any rule
+* matches the recipient, /send-mail will accept the send under
+* the recipient-scope check.
+*
+* The endpoint is the answer to "where can I send" without
+* exposing internal entitlement names. Agents that don't
+* recognize a `type` can still read the `description` prose
+* and act on it.
+*
+* Rule kinds, ordered broadest-first so an agent can stop
+* scanning at the first match:
+*
+* 1. `any_recipient` (one entry, only when the org can send
+* anywhere): every other rule below it is redundant.
+* 2. `managed_zone` (always emitted, one per Primitive-managed
+* zone): sends to any address at *.primitive.email or
+* *.email.works always succeed; no entitlement required.
+* 3. `your_domain` (one per active verified outbound domain
+* owned by the org): sends to that domain are approved.
+* 4. `address` (one per address that has authenticated
+* inbound mail to the org, capped at `meta.address_cap`):
+* sends to that exact address are approved.
+*
+* The list is informational, not an authorization check.
+* /send-mail remains the source of truth on whether an
+* individual send will succeed (it also enforces the
+* from-address and the `send_mail` entitlement, which are
+* not recipient-scope concerns and are not represented here).
+*
+*/
+const getSendPermissions = (options) => (options?.client ?? client$1).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/send-permissions",
+	...options
+});
+/**
 * Send outbound email
 *
 * Sends an outbound email through Primitive's outbound relay. By default
@@ -1364,4 +1412,4 @@ function client(options = {}) {
 }
 const operations = sdk_gen_exports;
 //#endregion
-export { rotateWebhookSecret as A, listDomains as C, replayDelivery as D, listFilters as E, updateEndpoint as F, updateFilter as I, verifyDomain as L, testEndpoint as M, updateAccount as N, replayEmailWebhooks as O, updateDomain as P, listDeliveries as S, listEndpoints as T, downloadRawEmail as _, client as a, getStorageStats as b, operations as c, createFilter as d, deleteDomain as f, downloadAttachments as g, deleteFilter as h, PrimitiveClient as i, sendEmail as j, replyToEmail as k, addDomain as l, deleteEndpoint as m, PrimitiveApiClient as n, createPrimitiveApiClient as o, deleteEmail as p, PrimitiveApiError as r, createPrimitiveClient as s, DEFAULT_BASE_URL as t, createEndpoint as u, getAccount as v, listEmails as w, getWebhookSecret as x, getEmail as y };
+export { replyToEmail as A, listDeliveries as C, listFilters as D, listEndpoints as E, updateDomain as F, updateEndpoint as I, updateFilter as L, sendEmail as M, testEndpoint as N, replayDelivery as O, updateAccount as P, verifyDomain as R, getWebhookSecret as S, listEmails as T, downloadRawEmail as _, client as a, getSendPermissions as b, operations as c, createFilter as d, deleteDomain as f, downloadAttachments as g, deleteFilter as h, PrimitiveClient as i, rotateWebhookSecret as j, replayEmailWebhooks as k, addDomain as l, deleteEndpoint as m, PrimitiveApiClient as n, createPrimitiveApiClient as o, deleteEmail as p, PrimitiveApiError as r, createPrimitiveClient as s, DEFAULT_BASE_URL as t, createEndpoint as u, getAccount as v, listDomains as w, getStorageStats as x, getEmail as y };

package/dist/{index-K4KbjppU.d.ts → index-ChLFXxTa.d.ts}

@@ -560,6 +560,18 @@ type EmailSummary = {
   domain_id?: string | null;
   org_id?: string | null;
   status: 'pending' | 'accepted' | 'completed' | 'rejected';
+  /**
+   * SMTP envelope sender (return-path) the inbound mail server
+   * accepted. For most legitimate mail this equals the bare
+   * address in the From header; for mailing lists, bounce
+   * handlers, and forwarders it is typically the bounce address
+   * rather than the human-visible sender.
+   *
+   * For the parsed From-header value (with display name handling
+   * and a sender-fallback when the header is unparseable), GET
+   * the email by id and use `from_email`.
+   *
+   */
   sender: string;
   recipient: string;
   subject?: string | null;
@@ -576,6 +588,20 @@ type EmailDetail = {
   message_id?: string | null;
   domain_id?: string | null;
   org_id?: string | null;
+  /**
+   * SMTP envelope sender (return-path) the inbound mail server
+   * accepted. Same value as `smtp_mail_from`; both fields exist
+   * so protocol-aware tooling can use whichever name it expects.
+   *
+   * For most legitimate mail this equals `from_email`; for
+   * mailing lists, bounce handlers, and forwarders it is
+   * typically the bounce-handling address rather than the
+   * human-visible sender.
+   *
+   * **For the canonical "who sent this email" value, use
+   * `from_email`.**
+   *
+   */
   sender: string;
   recipient: string;
   subject?: string | null;
@@ -602,13 +628,43 @@ type EmailDetail = {
   webhook_last_error?: string | null;
   webhook_fired_at?: string | null;
   smtp_helo?: string | null;
+  /**
+   * SMTP envelope MAIL FROM (return-path), as accepted by the
+   * inbound mail server. Same value as `sender`; both fields
+   * exist so protocol-aware tooling can use whichever name it
+   * expects.
+   *
+   * For the canonical "who sent this email" value (display name
+   * stripped, From-header preferred), use `from_email`.
+   *
+   */
   smtp_mail_from?: string | null;
   smtp_rcpt_to?: Array<string> | null;
+  /**
+   * Raw `From:` header from the message body, including any
+   * display name (e.g. `"Alice Example" <alice@example.com>`).
+   * Use this when you need the display name for rendering.
+   *
+   * For the bare email address (display name stripped), use
+   * `from_email`.
+   *
+   */
   from_header?: string | null;
   content_discarded_at?: string | null;
   content_discarded_by_delivery_id?: string | null;
   /**
-   * Parsed from address (from_header or sender fallback)
+   * Bare email address parsed from the `From:` header, with
+   * display name stripped (e.g. `alice@example.com`). Falls
+   * back to `sender` (the SMTP envelope MAIL FROM) when the
+   * `From:` header cannot be parsed.
+   *
+   * **This is the canonical "who sent this email" field for
+   * most use cases**, including comparing against allowlists,
+   * routing replies, or displaying the sender to a user. Use
+   * `from_header` when you specifically need the display name,
+   * or `sender`/`smtp_mail_from` when you need the SMTP
+   * envelope value (e.g. to follow a bounce).
+   *
    */
   from_email: string;
   /**
@@ -779,6 +835,135 @@ type SendMailResult = {
    */
   idempotent_replay: boolean;
 };
+/**
+ * One recipient-scope rule describing a destination the caller
+ * may send to. Discriminated on `type`. Each rule carries a
+ * human-prose `description` field intended for display.
+ *
+ * Rule kinds are stable within an SDK release. A response
+ * containing a `type` value not enumerated in this schema
+ * means the server is running a newer version than the SDK;
+ * upgrade the SDK to the release that matches the server's
+ * schema. Strict-parsing SDKs (Go, Python) will raise a
+ * decode error in that case rather than silently dropping
+ * the unknown rule, since silent drops would let an outbound
+ * agent reason from an incomplete view of its own permissions.
+ *
+ */
+type SendPermissionRule = ({
+  type: 'any_recipient';
+} & SendPermissionAnyRecipient) | ({
+  type: 'managed_zone';
+} & SendPermissionManagedZone) | ({
+  type: 'your_domain';
+} & SendPermissionYourDomain) | ({
+  type: 'address';
+} & SendPermissionAddress);
+/**
+ * The caller can send to any recipient. When this rule is
+ * present, every other rule in the response is redundant.
+ *
+ */
+type SendPermissionAnyRecipient = {
+  type: 'any_recipient';
+  /**
+   * Human-prose summary of the rule.
+   */
+  description: string;
+};
+/**
+ * The caller can send to any address at the named
+ * Primitive-managed zone. Always emitted (no entitlement
+ * required) because Primitive owns the zone and every mailbox
+ * belongs to a Primitive customer by construction.
+ *
+ */
+type SendPermissionManagedZone = {
+  type: 'managed_zone';
+  /**
+   * The managed apex domain. Sends are accepted to any
+   * address at the apex itself or any subdomain (e.g.
+   * `alice@primitive.email` and `alice@acme.primitive.email`
+   * both match the `primitive.email` zone rule).
+   *
+   */
+  zone: string;
+  /**
+   * Human-prose summary of the rule.
+   */
+  description: string;
+};
+/**
+ * The caller can send to any address at one of their own
+ * verified outbound domains. Emitted once per active row in
+ * the org's `domains` table.
+ *
+ */
+type SendPermissionYourDomain = {
+  type: 'your_domain';
+  /**
+   * A verified outbound domain owned by the caller's org.
+   */
+  domain: string;
+  /**
+   * Human-prose summary of the rule.
+   */
+  description: string;
+};
+/**
+ * The caller can send to a specific address that has
+ * authenticated inbound mail to the org. Emitted once per row
+ * in the org's `known_send_addresses` table, capped at
+ * `meta.address_cap`.
+ *
+ */
+type SendPermissionAddress = {
+  type: 'address';
+  /**
+   * The bare email address this rule grants sends to.
+   */
+  address: string;
+  /**
+   * Most recent inbound email from this address that
+   * authenticated successfully (DMARC pass + DKIM/SPF
+   * alignment). Updated on each new authenticated receipt.
+   *
+   */
+  last_received_at: string;
+  /**
+   * Total number of authenticated inbound emails from this
+   * address. Increments only when `last_received_at` advances.
+   *
+   */
+  received_count: number;
+  /**
+   * Human-prose summary of the rule.
+   */
+  description: string;
+};
+/**
+ * Response metadata for /send-permissions. The `address_cap`
+ * bounds the size of the `address` rule subset; orgs with more
+ * than `address_cap` known addresses almost always also hold a
+ * broader rule type (`any_recipient` or `your_domain`), so the
+ * cap is a response-size bound rather than a meaningful
+ * product limit.
+ *
+ */
+type SendPermissionsMeta = {
+  /**
+   * Maximum number of `address` rules included in `data`.
+   */
+  address_cap: number;
+  /**
+   * True when the org has more than `address_cap` known
+   * addresses and the list was truncated. False when every
+   * known address is represented or when the org holds no
+   * address rules at all.
+   *
+   */
+  truncated: boolean;
+};
 type Endpoint = {
   id: string;
   org_id: string;
@@ -1926,6 +2111,29 @@ type ReplayDeliveryResponses = {
   };
 };
 type ReplayDeliveryResponse = ReplayDeliveryResponses[keyof ReplayDeliveryResponses];
+type GetSendPermissionsData = {
+  body?: never;
+  path?: never;
+  query?: never;
+  url: '/send-permissions';
+};
+type GetSendPermissionsErrors = {
+  /**
+   * Invalid or missing API key
+   */
+  401: ErrorResponse;
+};
+type GetSendPermissionsError = GetSendPermissionsErrors[keyof GetSendPermissionsErrors];
+type GetSendPermissionsResponses = {
+  /**
+   * Send-permission rules for the caller's org
+   */
+  200: SuccessEnvelope & {
+    data: Array<SendPermissionRule>;
+    meta: SendPermissionsMeta;
+  };
+};
+type GetSendPermissionsResponse = GetSendPermissionsResponses[keyof GetSendPermissionsResponses];
 type SendEmailData = {
   body: SendMailInput;
   headers?: {
@@ -1982,7 +2190,7 @@ type SendEmailResponses = {
 };
 type SendEmailResponse = SendEmailResponses[keyof SendEmailResponses];
 declare namespace sdk_gen_d_exports {
-  export { Options, addDomain, createEndpoint, createFilter, deleteDomain, deleteEmail, deleteEndpoint, deleteFilter, downloadAttachments, downloadRawEmail, getAccount, getEmail, getStorageStats, getWebhookSecret, listDeliveries, listDomains, listEmails, listEndpoints, listFilters, replayDelivery, replayEmailWebhooks, replyToEmail, rotateWebhookSecret, sendEmail, testEndpoint, updateAccount, updateDomain, updateEndpoint, updateFilter, verifyDomain };
+  export { Options, addDomain, createEndpoint, createFilter, deleteDomain, deleteEmail, deleteEndpoint, deleteFilter, downloadAttachments, downloadRawEmail, getAccount, getEmail, getSendPermissions, getStorageStats, getWebhookSecret, listDeliveries, listDomains, listEmails, listEndpoints, listFilters, replayDelivery, replayEmailWebhooks, replyToEmail, rotateWebhookSecret, sendEmail, testEndpoint, updateAccount, updateDomain, updateEndpoint, updateFilter, verifyDomain };
 }
 type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options$1<TData, ThrowOnError, TResponse> & {
   /**
@@ -2067,11 +2275,15 @@ declare const updateDomain: <ThrowOnError extends boolean = false>(options: Opti
  */
 declare const verifyDomain: <ThrowOnError extends boolean = false>(options: Options<VerifyDomainData, ThrowOnError>) => RequestResult<VerifyDomainResponses, VerifyDomainErrors, ThrowOnError, "fields">;
 /**
- * List emails
+ * List inbound emails
+ *
+ * Returns a paginated list of INBOUND emails received at your
+ * verified domains. Outbound messages sent via /send-mail are not
+ * included; this endpoint is the inbox view, not a unified
+ * send/receive history.
  *
- * Returns a paginated list of received emails. Supports filtering by
- * domain, status, date range, and free-text search across subject,
- * sender, and recipient fields.
+ * Supports filtering by domain, status, date range, and free-text
+ * search across subject, sender, and recipient fields.
  *
  */
 declare const listEmails: <ThrowOnError extends boolean = false>(options?: Options<ListEmailsData, ThrowOnError>) => RequestResult<ListEmailsResponses, ListEmailsErrors, ThrowOnError, "fields">;
@@ -2216,6 +2428,42 @@ declare const listDeliveries: <ThrowOnError extends boolean = false>(options?: O
  *
  */
 declare const replayDelivery: <ThrowOnError extends boolean = false>(options: Options<ReplayDeliveryData, ThrowOnError>) => RequestResult<ReplayDeliveryResponses, ReplayDeliveryErrors, ThrowOnError, "fields">;
+/**
+ * List send-permission rules
+ *
+ * Returns a flat list of rules describing every recipient the
+ * caller may send to. Each rule has a `type`, a kind-specific
+ * payload, and a human-readable `description`. If any rule
+ * matches the recipient, /send-mail will accept the send under
+ * the recipient-scope check.
+ *
+ * The endpoint is the answer to "where can I send" without
+ * exposing internal entitlement names. Agents that don't
+ * recognize a `type` can still read the `description` prose
+ * and act on it.
+ *
+ * Rule kinds, ordered broadest-first so an agent can stop
+ * scanning at the first match:
+ *
+ * 1. `any_recipient` (one entry, only when the org can send
+ * anywhere): every other rule below it is redundant.
+ * 2. `managed_zone` (always emitted, one per Primitive-managed
+ * zone): sends to any address at *.primitive.email or
+ * *.email.works always succeed; no entitlement required.
+ * 3. `your_domain` (one per active verified outbound domain
+ * owned by the org): sends to that domain are approved.
+ * 4. `address` (one per address that has authenticated
+ * inbound mail to the org, capped at `meta.address_cap`):
+ * sends to that exact address are approved.
+ *
+ * The list is informational, not an authorization check.
+ * /send-mail remains the source of truth on whether an
+ * individual send will succeed (it also enforces the
+ * from-address and the `send_mail` entitlement, which are
+ * not recipient-scope concerns and are not represented here).
+ *
+ */
+declare const getSendPermissions: <ThrowOnError extends boolean = false>(options?: Options<GetSendPermissionsData, ThrowOnError>) => RequestResult<GetSendPermissionsResponses, GetSendPermissionsErrors, ThrowOnError, "fields">;
 /**
  * Send outbound email
  *
@@ -2352,4 +2600,4 @@ declare function createPrimitiveClient(options?: PrimitiveClientOptions): Primit
 declare function client(options?: PrimitiveClientOptions): PrimitiveClient;
 declare const operations: typeof sdk_gen_d_exports;
 //#endregion
-export { AddDomainResponse as $, ReplayDeliveryErrors as $n, UpdateEndpointResponses as $r, ErrorResponse as $t, getWebhookSecret as A, ListDomainsError as An, TestEndpointError as Ar, DeleteFilterData as At, sendEmail as B, ListEndpointsError as Bn, UpdateAccountResponse as Br, DownloadAttachmentsError as Bt, deleteEndpoint as C, Limit as Cn, SendEmailResponses as Cr, DeleteEmailResponse as Ct, getAccount as D, ListDeliveriesResponse as Dn, StorageStats as Dr, DeleteEndpointErrors as Dt, downloadRawEmail as E, ListDeliveriesErrors as En, SentEmailStatus as Er, DeleteEndpointError as Et, listFilters as F, ListEmailsError as Fn, UnverifiedDomain as Fr, DeliveryStatus as Ft, updateFilter as G, ListFiltersData as Gn, UpdateDomainInput as Gr, DownloadRawEmailError as Gt, updateAccount as H, ListEndpointsResponse as Hn, UpdateDomainData as Hr, DownloadAttachmentsResponse as Ht, replayDelivery as I, ListEmailsErrors as In, UpdateAccountData as Ir, DeliverySummary as It, AccountUpdated as J, ListFiltersResponse as Jn, UpdateEndpointData as Jr, DownloadRawEmailResponses as Jt, verifyDomain as K, ListFiltersError as Kn, UpdateDomainResponse as Kr, DownloadRawEmailErrors as Kt, replayEmailWebhooks as L, ListEmailsResponse as Ln, UpdateAccountError as Lr, Domain as Lt, listDomains as M, ListDomainsResponse as Mn, TestEndpointResponse as Mr, DeleteFilterErrors as Mt, listEmails as N, ListDomainsResponses as Nn, TestEndpointResponses as Nr, DeleteFilterResponse as Nt, getEmail as O, ListDeliveriesResponses as On, SuccessEnvelope as Or, DeleteEndpointResponse as Ot, listEndpoints as P, ListEmailsData as Pn, TestResult as Pr, DeleteFilterResponses as Pt, AddDomainInput as Q, ReplayDeliveryError as Qn, UpdateEndpointResponse as Qr, Endpoint as Qt, replyToEmail as R, ListEmailsResponses as Rn, UpdateAccountErrors as Rr, DomainVerifyResult as Rt, deleteEmail as S, GetWebhookSecretResponses as Sn, SendEmailResponse as Sr, DeleteEmailErrors as St, downloadAttachments as T, ListDeliveriesError as Tn, SendMailResult as Tr, DeleteEndpointData as Tt, updateDomain as U, ListEndpointsResponses as Un, UpdateDomainError as Ur, DownloadAttachmentsResponses as Ut, testEndpoint as V, ListEndpointsErrors as Vn, UpdateAccountResponses as Vr, DownloadAttachmentsErrors as Vt, updateEndpoint as W, ListEnvelope as Wn, UpdateDomainErrors as Wr, DownloadRawEmailData as Wt, AddDomainError as X, PaginationMeta as Xn, UpdateEndpointErrors as Xr, EmailDetailReply as Xt, AddDomainData as Y, ListFiltersResponses as Yn, UpdateEndpointError as Yr, EmailDetail as Yt, AddDomainErrors as Z, ReplayDeliveryData as Zn, UpdateEndpointInput as Zr, EmailSummary as Zt, Options as _, Options$1 as _i, GetStorageStatsResponses as _n, RotateWebhookSecretResponse as _r, DeleteDomainErrors as _t, PrimitiveApiError as a, UpdateFilterResponses as ai, GetAccountErrors as an, ReplayEmailWebhooksResponse as ar, CreateEndpointInput as at, createFilter as b, ResponseStyle as bi, GetWebhookSecretErrors as bn, SendEmailError as br, DeleteEmailData as bt, PrimitiveClientOptions as c, VerifyDomainError as ci, GetEmailData as cn, ReplyToEmailData as cr, CreateFilterData as ct, SendResult as d, VerifyDomainResponses as di, GetEmailResponse as dn, ReplyToEmailResponse as dr, CreateFilterInput as dt, UpdateFilterData as ei, Filter as en, ReplayDeliveryResponse as er, AddDomainResponses as et, SendThreadInput as f, WebhookSecret as fi, GetEmailResponses as fn, ReplyToEmailResponses as fr, CreateFilterResponse as ft, operations as g, CreateClientConfig as gi, GetStorageStatsResponse as gn, RotateWebhookSecretErrors as gr, DeleteDomainError as gt, createPrimitiveClient as h, Config as hi, GetStorageStatsErrors as hn, RotateWebhookSecretError as hr, DeleteDomainData as ht, PrimitiveApiClientOptions as i, UpdateFilterResponse as ii, GetAccountError as in, ReplayEmailWebhooksErrors as ir, CreateEndpointErrors as it, listDeliveries as j, ListDomainsErrors as jn, TestEndpointErrors as jr, DeleteFilterError as jt, getStorageStats as k, ListDomainsData as kn, TestEndpointData as kr, DeleteEndpointResponses as kt, ReplyInput as l, VerifyDomainErrors as li, GetEmailError as ln, ReplyToEmailError as lr, CreateFilterError as lt, createPrimitiveApiClient as m, ClientOptions$1 as mi, GetStorageStatsError as mn, RotateWebhookSecretData as mr, Cursor as mt, ForwardInput as n, UpdateFilterErrors as ni, GateFix as nn, ReplayEmailWebhooksData as nr, CreateEndpointData as nt, PrimitiveApiErrorDetails as o, VerifiedDomain as oi, GetAccountResponse as on, ReplayEmailWebhooksResponses as or, CreateEndpointResponse as ot, client as p, Client as pi, GetStorageStatsData as pn, ResourceId as pr, CreateFilterResponses as pt, Account as q, ListFiltersErrors as qn, UpdateDomainResponses as qr, DownloadRawEmailResponse as qt, PrimitiveApiClient as r, UpdateFilterInput as ri, GetAccountData as rn, ReplayEmailWebhooksError as rr, CreateEndpointError as rt, PrimitiveClient as s, VerifyDomainData as si, GetAccountResponses as sn, ReplayResult as sr, CreateEndpointResponses as st, DEFAULT_BASE_URL as t, UpdateFilterError as ti, GateDenial as tn, ReplayDeliveryResponses as tr, ClientOptions as tt, SendInput as u, VerifyDomainResponse as ui, GetEmailErrors as un, ReplyToEmailErrors as ur, CreateFilterErrors as ut, addDomain as v, RequestOptions as vi, GetWebhookSecretData as vn, RotateWebhookSecretResponses as vr, DeleteDomainResponse as vt, deleteFilter as w, ListDeliveriesData as wn, SendMailInput as wr, DeleteEmailResponses as wt, deleteDomain as x, Auth as xi, GetWebhookSecretResponse as xn, SendEmailErrors as xr, DeleteEmailError as xt, createEndpoint as y, RequestResult as yi, GetWebhookSecretError as yn, SendEmailData as yr, DeleteDomainResponses as yt, rotateWebhookSecret as z, ListEndpointsData as zn, UpdateAccountInput as zr, DownloadAttachmentsData as zt };
+export { AddDomainInput as $, ListFiltersErrors as $n, UpdateAccountResponses as $r, Endpoint as $t, getStorageStats as A, RequestOptions as Ai, ListDeliveriesData as An, SendMailInput as Ar, DeleteEndpointResponses as At, rotateWebhookSecret as B, ListEmailsData as Bn, SuccessEnvelope as Br, DownloadAttachmentsData as Bt, deleteEndpoint as C, VerifyDomainResponses as Ci, GetStorageStatsResponses as Cn, RotateWebhookSecretResponse as Cr, DeleteEmailErrors as Ct, getAccount as D, Config as Di, GetWebhookSecretResponse as Dn, SendEmailErrors as Dr, DeleteEndpointError as Dt, downloadRawEmail as E, ClientOptions$1 as Ei, GetWebhookSecretErrors as En, SendEmailError as Er, DeleteEndpointData as Et, listEndpoints as F, ListDomainsData as Fn, SendPermissionRule as Fr, DeleteFilterResponses as Ft, updateEndpoint as G, ListEndpointsData as Gn, TestEndpointResponses as Gr, DownloadRawEmailData as Gt, testEndpoint as H, ListEmailsErrors as Hn, TestEndpointError as Hr, DownloadAttachmentsErrors as Ht, listFilters as I, ListDomainsError as In, SendPermissionYourDomain as Ir, DeliveryStatus as It, Account as J, ListEndpointsResponse as Jn, UpdateAccountData as Jr, DownloadRawEmailResponse as Jt, updateFilter as K, ListEndpointsError as Kn, TestResult as Kr, DownloadRawEmailError as Kt, replayDelivery as L, ListDomainsErrors as Ln, SendPermissionsMeta as Lr, DeliverySummary as Lt, listDeliveries as M, ResponseStyle as Mi, ListDeliveriesErrors as Mn, SendPermissionAddress as Mr, DeleteFilterError as Mt, listDomains as N, Auth as Ni, ListDeliveriesResponse as Nn, SendPermissionAnyRecipient as Nr, DeleteFilterErrors as Nt, getEmail as O, CreateClientConfig as Oi, GetWebhookSecretResponses as On, SendEmailResponse as Or, DeleteEndpointErrors as Ot, listEmails as P, ListDeliveriesResponses as Pn, SendPermissionManagedZone as Pr, DeleteFilterResponse as Pt, AddDomainErrors as Q, ListFiltersError as Qn, UpdateAccountResponse as Qr, EmailSummary as Qt, replayEmailWebhooks as R, ListDomainsResponse as Rn, SentEmailStatus as Rr, Domain as Rt, deleteEmail as S, VerifyDomainResponse as Si, GetStorageStatsResponse as Sn, RotateWebhookSecretErrors as Sr, DeleteEmailError as St, downloadAttachments as T, Client as Ti, GetWebhookSecretError as Tn, SendEmailData as Tr, DeleteEmailResponses as Tt, updateAccount as U, ListEmailsResponse as Un, TestEndpointErrors as Ur, DownloadAttachmentsResponse as Ut, sendEmail as V, ListEmailsError as Vn, TestEndpointData as Vr, DownloadAttachmentsError as Vt, updateDomain as W, ListEmailsResponses as Wn, TestEndpointResponse as Wr, DownloadAttachmentsResponses as Wt, AddDomainData as X, ListEnvelope as Xn, UpdateAccountErrors as Xr, EmailDetail as Xt, AccountUpdated as Y, ListEndpointsResponses as Yn, UpdateAccountError as Yr, DownloadRawEmailResponses as Yt, AddDomainError as Z, ListFiltersData as Zn, UpdateAccountInput as Zr, EmailDetailReply as Zt, Options as _, UpdateFilterResponses as _i, GetSendPermissionsResponse as _n, ReplyToEmailResponse as _r, DeleteDomainError as _t, PrimitiveApiError as a, UpdateDomainResponses as ai, GetAccountError as an, ReplayDeliveryErrors as ar, CreateEndpointErrors as at, createFilter as b, VerifyDomainError as bi, GetStorageStatsError as bn, RotateWebhookSecretData as br, DeleteDomainResponses as bt, PrimitiveClientOptions as c, UpdateEndpointErrors as ci, GetAccountResponses as cn, ReplayEmailWebhooksData as cr, CreateEndpointResponses as ct, SendResult as d, UpdateEndpointResponses as di, GetEmailErrors as dn, ReplayEmailWebhooksResponse as dr, CreateFilterErrors as dt, UpdateDomainData as ei, ErrorResponse as en, ListFiltersResponse as er, AddDomainResponse as et, SendThreadInput as f, UpdateFilterData as fi, GetEmailResponse as fn, ReplayEmailWebhooksResponses as fr, CreateFilterInput as ft, operations as g, UpdateFilterResponse as gi, GetSendPermissionsErrors as gn, ReplyToEmailErrors as gr, DeleteDomainData as gt, createPrimitiveClient as h, UpdateFilterInput as hi, GetSendPermissionsError as hn, ReplyToEmailError as hr, Cursor as ht, PrimitiveApiClientOptions as i, UpdateDomainResponse as ii, GetAccountData as in, ReplayDeliveryError as ir, CreateEndpointError as it, getWebhookSecret as j, RequestResult as ji, ListDeliveriesError as jn, SendMailResult as jr, DeleteFilterData as jt, getSendPermissions as k, Options$1 as ki, Limit as kn, SendEmailResponses as kr, DeleteEndpointResponse as kt, ReplyInput as l, UpdateEndpointInput as li, GetEmailData as ln, ReplayEmailWebhooksError as lr, CreateFilterData as lt, createPrimitiveApiClient as m, UpdateFilterErrors as mi, GetSendPermissionsData as mn, ReplyToEmailData as mr, CreateFilterResponses as mt, ForwardInput as n, UpdateDomainErrors as ni, GateDenial as nn, PaginationMeta as nr, ClientOptions as nt, PrimitiveApiErrorDetails as o, UpdateEndpointData as oi, GetAccountErrors as on, ReplayDeliveryResponse as or, CreateEndpointInput as ot, client as p, UpdateFilterError as pi, GetEmailResponses as pn, ReplayResult as pr, CreateFilterResponse as pt, verifyDomain as q, ListEndpointsErrors as qn, UnverifiedDomain as qr, DownloadRawEmailErrors as qt, PrimitiveApiClient as r, UpdateDomainInput as ri, GateFix as rn, ReplayDeliveryData as rr, CreateEndpointData as rt, PrimitiveClient as s, UpdateEndpointError as si, GetAccountResponse as sn, ReplayDeliveryResponses as sr, CreateEndpointResponse as st, DEFAULT_BASE_URL as t, UpdateDomainError as ti, Filter as tn, ListFiltersResponses as tr, AddDomainResponses as tt, SendInput as u, UpdateEndpointResponse as ui, GetEmailError as un, ReplayEmailWebhooksErrors as ur, CreateFilterError as ut, addDomain as v, VerifiedDomain as vi, GetSendPermissionsResponses as vn, ReplyToEmailResponses as vr, DeleteDomainErrors as vt, deleteFilter as w, WebhookSecret as wi, GetWebhookSecretData as wn, RotateWebhookSecretResponses as wr, DeleteEmailResponse as wt, deleteDomain as x, VerifyDomainErrors as xi, GetStorageStatsErrors as xn, RotateWebhookSecretError as xr, DeleteEmailData as xt, createEndpoint as y, VerifyDomainData as yi, GetStorageStatsData as yn, ResourceId as yr, DeleteDomainResponse as yt, replyToEmail as z, ListDomainsResponses as zn, StorageStats as zr, DomainVerifyResult as zt };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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-K4KbjppU.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-ChLFXxTa.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

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-CLLpjjWy.js";
+import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-DvJpdOJ8.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/api-command.js

@@ -67,8 +67,22 @@ function extractBodyFields(schema) {
                 kind = "complex";
             }
         }
+        // Pull the first paragraph of the schema description for use
+        // as the CLI flag's --help string. We split on a blank line
+        // (paragraph break) and then collapse any soft line wraps
+        // inside that paragraph to spaces. This avoids the previous
+        // bug where `split("\n")[0]` truncated wrapped prose like
+        //   "Optional override for ... Defaults to\nthe inbound's..."
+        // to "Optional override for ... Defaults to" - a sentence
+        // ending with "to" with nothing after it, which read as
+        // ellipsis truncation in --help. The remaining paragraphs
+        // are intentionally dropped so multi-paragraph schemas don't
+        // blow out the per-flag help block.
         const description = typeof propSchema.description === "string"
-            ? propSchema.description.split("\n")[0].trim()
+            ? propSchema.description
+                .split(/\n\s*\n/)[0]
+                .replace(/\s*\n\s*/g, " ")
+                .trim()
             : "";
         const enumRaw = propSchema.enum;
         const enumValues = kind === "string" && Array.isArray(enumRaw)
@@ -242,6 +256,52 @@ export function formatErrorPayload(payload) {
     }
     return JSON.stringify(payload, null, 2);
 }
+// Pull the top-level error code out of either a server response
+// payload (`{ error: { code: '...' } }` or `{ code: '...' }`) or a
+// thrown Error whose `cause.code` carries the value. Used to drive
+// `--api-key` and similar hints in writeErrorWithHints below.
+// Also exported so individual commands (send, whoami) can branch
+// on auth failures and avoid surfacing misleading "fix this flag"
+// guidance when the real problem is the API key.
+export function extractErrorCode(payload) {
+    if (payload instanceof Error) {
+        const { code } = extractCauseDetails(payload.cause);
+        return code;
+    }
+    if (payload && typeof payload === "object") {
+        const inner = payload.error;
+        if (inner && typeof inner === "object" && typeof inner.code === "string") {
+            return inner.code;
+        }
+        const direct = payload.code;
+        if (typeof direct === "string")
+            return direct;
+    }
+    return undefined;
+}
+// Common-case actionable hints keyed by error code. The full
+// JSON envelope still goes to stderr unchanged for any caller
+// that wants to parse it; the hint is an extra trailing line so
+// a human reading the output sees "what to actually do next."
+// The AGX walkthrough flagged that an `unauthorized` envelope
+// alone left the agent without context for the env var or the
+// `--api-key` flag; this closes that gap without having to
+// special-case every command.
+const ERROR_CODE_HINTS = {
+    unauthorized: "Hint: pass --api-key explicitly, or set PRIMITIVE_API_KEY in your environment. `primitive whoami` is the fastest way to verify a key is live.",
+};
+// Write a server / SDK error to stderr in the canonical envelope
+// shape, plus an actionable hint when the code is one we know how
+// to advise on. Replaces the bare
+// `process.stderr.write(${formatErrorPayload(p)}\n)` dance every
+// command was doing.
+export function writeErrorWithHints(payload) {
+    process.stderr.write(`${formatErrorPayload(payload)}\n`);
+    const code = extractErrorCode(payload);
+    if (code && ERROR_CODE_HINTS[code]) {
+        process.stderr.write(`${ERROR_CODE_HINTS[code]}\n`);
+    }
+}
 // Reserved flag names the body-field expander must never overwrite.
 // `--raw-body` and `--body-file` are the JSON escape hatches.
 // `--api-key`, `--base-url`, `--output` are infra. Path and query
@@ -266,22 +326,23 @@ const RESERVED_FLAG_NAMES = new Set([
     "output",
 ]);
 function bodyFieldFlag(field) {
-    // Flag descriptions cap at 80 chars so oclif's --help output
-    // stays readable; the schema's full description is also visible
-    // via `primitive list-operations | jq`.
-    const descMax = 80;
-    const trimmedDesc = field.description.length > descMax
-        ? `${field.description.slice(0, descMax - 3)}...`
-        : field.description;
+    // Pass the full first-line description through. oclif's --help
+    // renderer wraps long values across multiple lines on its own,
+    // so a fixed character cap here just produces ellipsis-truncated
+    // sentences ("body_html is required. Th...") that mislead the
+    // reader. extractBodyFields already normalizes by taking only
+    // the first paragraph of the schema description, so multi-
+    // paragraph fields don't blow out the help.
+    //
     // Field-flag UX choice: do NOT mark scalar body fields as
     // required at the oclif level even when the JSON Schema marks
     // them required. Reason: a caller can satisfy the requirement
-    // either via the individual flag OR via --body / --body-file.
+    // either via the individual flag OR via --raw-body / --body-file.
     // Marking the flag required would force the individual-flag
     // form. The runtime body merger validates the final assembled
     // body against the same server-side schema either way.
     const common = {
-        description: trimmedDesc || field.name,
+        description: field.description || field.name,
     };
     if (field.kind === "boolean")
         return Flags.boolean(common);
@@ -460,8 +521,7 @@ export function createOperationCommand(operation) {
                 responseStyle: "fields",
             });
             if (result.error) {
-                const errorPayload = extractErrorPayload(result.error);
-                process.stderr.write(`${formatErrorPayload(errorPayload)}\n`);
+                writeErrorWithHints(extractErrorPayload(result.error));
                 process.exitCode = 1;
                 return;
             }

package/dist/oclif/commands/send.js

@@ -1,7 +1,7 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { listDomains, sendEmail } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, formatErrorPayload } from "../api-command.js";
+import { extractErrorCode, extractErrorPayload, formatErrorPayload, writeErrorWithHints, } from "../api-command.js";
 // `primitive send` is the agent-grade shortcut for the most common
 // case: send a fresh outbound email. It wraps `sending:send-email`
 // with two ergonomic defaults that the underlying operation can't
@@ -52,6 +52,20 @@ async function pickDefaultFromAddress(apiClient) {
     });
     if (result.error) {
         const errorPayload = extractErrorPayload(result.error);
+        // If the underlying failure is an auth problem, don't pretend
+        // --from will fix it: the actual sendEmail call would 401 too.
+        // Surface the auth hint via writeErrorWithHints and bail with
+        // a focused message instead of the verbose "underlying error"
+        // wrapping.
+        if (extractErrorCode(errorPayload) === "unauthorized") {
+            writeErrorWithHints(errorPayload);
+            // exit: 1 to match the run() unauthorized path (which uses
+            // `process.exitCode = 1`). oclif's CLIError defaults to 2,
+            // so without this override the same "unauthorized" condition
+            // exits 2 when surfaced from listDomains and 1 when surfaced
+            // from sendEmail, breaking callers that branch on exit code.
+            throw new Errors.CLIError("Cannot send: API key is missing or invalid (see hint above).", { exit: 1 });
+        }
         throw new Errors.CLIError(`Could not look up your verified domains to default --from. Pass --from explicitly. Underlying error: ${formatErrorPayload(errorPayload)}`);
     }
     const envelope = result.data;
@@ -147,8 +161,7 @@ class SendCommand extends Command {
             responseStyle: "fields",
         });
         if (result.error) {
-            const errorPayload = extractErrorPayload(result.error);
-            process.stderr.write(`${formatErrorPayload(errorPayload)}\n`);
+            writeErrorWithHints(extractErrorPayload(result.error));
             process.exitCode = 1;
             return;
         }

package/dist/oclif/commands/whoami.js

@@ -1,7 +1,7 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { getAccount } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, formatErrorPayload } from "../api-command.js";
+import { extractErrorPayload, writeErrorWithHints } from "../api-command.js";
 // `primitive whoami` is the credentials smoke-test the AGX
 // walkthrough kept asking for. Before this command, a user with a
 // suspect API key had no fast way to verify "is my key live and
@@ -40,8 +40,7 @@ class WhoamiCommand extends Command {
             responseStyle: "fields",
         });
         if (result.error) {
-            const errorPayload = extractErrorPayload(result.error);
-            process.stderr.write(`${formatErrorPayload(errorPayload)}\n`);
+            writeErrorWithHints(extractErrorPayload(result.error));
             process.exitCode = 1;
             return;
         }

package/dist/openapi/openapi.generated.js

@@ -532,8 +532,8 @@ export const openapiDocument = {
         "/emails": {
             "get": {
                 "operationId": "listEmails",
-                "summary": "List emails",
-                "description": "Returns a paginated list of received emails. Supports filtering by\ndomain, status, date range, and free-text search across subject,\nsender, and recipient fields.\n",
+                "summary": "List inbound emails",
+                "description": "Returns a paginated list of INBOUND emails received at your\nverified domains. Outbound messages sent via /send-mail are not\nincluded; this endpoint is the inbox view, not a unified\nsend/receive history.\n\nSupports filtering by domain, status, date range, and free-text\nsearch across subject, sender, and recipient fields.\n",
                 "tags": [
                     "Emails"
                 ],
@@ -1522,6 +1522,53 @@ export const openapiDocument = {
                 }
             }
         },
+        "/send-permissions": {
+            "get": {
+                "operationId": "getSendPermissions",
+                "summary": "List send-permission rules",
+                "description": "Returns a flat list of rules describing every recipient the\ncaller may send to. Each rule has a `type`, a kind-specific\npayload, and a human-readable `description`. If any rule\nmatches the recipient, /send-mail will accept the send under\nthe recipient-scope check.\n\nThe endpoint is the answer to \"where can I send\" without\nexposing internal entitlement names. Agents that don't\nrecognize a `type` can still read the `description` prose\nand act on it.\n\nRule kinds, ordered broadest-first so an agent can stop\nscanning at the first match:\n\n  1. `any_recipient` (one entry, only when the org can send\n     anywhere): every other rule below it is redundant.\n  2. `managed_zone` (always emitted, one per Primitive-managed\n     zone): sends to any address at *.primitive.email or\n     *.email.works always succeed; no entitlement required.\n  3. `your_domain` (one per active verified outbound domain\n     owned by the org): sends to that domain are approved.\n  4. `address` (one per address that has authenticated\n     inbound mail to the org, capped at `meta.address_cap`):\n     sends to that exact address are approved.\n\nThe list is informational, not an authorization check.\n/send-mail remains the source of truth on whether an\nindividual send will succeed (it also enforces the\nfrom-address and the `send_mail` entitlement, which are\nnot recipient-scope concerns and are not represented here).\n",
+                "tags": [
+                    "Sending"
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Send-permission rules for the caller's org",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "type": "array",
+                                                    "items": {
+                                                        "$ref": "#/components/schemas/SendPermissionRule"
+                                                    }
+                                                },
+                                                "meta": {
+                                                    "$ref": "#/components/schemas/SendPermissionsMeta"
+                                                }
+                                            },
+                                            "required": [
+                                                "data",
+                                                "meta"
+                                            ]
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    }
+                }
+            }
+        },
         "/send-mail": {
             "post": {
                 "operationId": "sendEmail",
@@ -2432,7 +2479,8 @@ export const openapiDocument = {
                         ]
                     },
                     "sender": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "SMTP envelope sender (return-path) the inbound mail server\naccepted. For most legitimate mail this equals the bare\naddress in the From header; for mailing lists, bounce\nhandlers, and forwarders it is typically the bounce address\nrather than the human-visible sender.\n\nFor the parsed From-header value (with display name handling\nand a sender-fallback when the header is unparseable), GET\nthe email by id and use `from_email`.\n"
                     },
                     "recipient": {
                         "type": "string"
@@ -2523,7 +2571,8 @@ export const openapiDocument = {
                         "format": "uuid"
                     },
                     "sender": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "SMTP envelope sender (return-path) the inbound mail server\naccepted. Same value as `smtp_mail_from`; both fields exist\nso protocol-aware tooling can use whichever name it expects.\n\nFor most legitimate mail this equals `from_email`; for\nmailing lists, bounce handlers, and forwarders it is\ntypically the bounce-handling address rather than the\nhuman-visible sender.\n\n**For the canonical \"who sent this email\" value, use\n`from_email`.**\n"
                     },
                     "recipient": {
                         "type": "string"
@@ -2645,7 +2694,8 @@ export const openapiDocument = {
                         "type": [
                             "string",
                             "null"
-                        ]
+                        ],
+                        "description": "SMTP envelope MAIL FROM (return-path), as accepted by the\ninbound mail server. Same value as `sender`; both fields\nexist so protocol-aware tooling can use whichever name it\nexpects.\n\nFor the canonical \"who sent this email\" value (display name\nstripped, From-header preferred), use `from_email`.\n"
                     },
                     "smtp_rcpt_to": {
                         "type": [
@@ -2660,7 +2710,8 @@ export const openapiDocument = {
                         "type": [
                             "string",
                             "null"
-                        ]
+                        ],
+                        "description": "Raw `From:` header from the message body, including any\ndisplay name (e.g. `\"Alice Example\" <alice@example.com>`).\nUse this when you need the display name for rendering.\n\nFor the bare email address (display name stripped), use\n`from_email`.\n"
                     },
                     "content_discarded_at": {
                         "type": [
@@ -2677,7 +2728,7 @@ export const openapiDocument = {
                     },
                     "from_email": {
                         "type": "string",
-                        "description": "Parsed from address (from_header or sender fallback)"
+                        "description": "Bare email address parsed from the `From:` header, with\ndisplay name stripped (e.g. `alice@example.com`). Falls\nback to `sender` (the SMTP envelope MAIL FROM) when the\n`From:` header cannot be parsed.\n\n**This is the canonical \"who sent this email\" field for\nmost use cases**, including comparing against allowlists,\nrouting replies, or displaying the sender to a user. Use\n`from_header` when you specifically need the display name,\nor `sender`/`smtp_mail_from` when you need the SMTP\nenvelope value (e.g. to follow a bounce).\n"
                     },
                     "to_email": {
                         "type": "string",
@@ -2935,6 +2986,156 @@ export const openapiDocument = {
                     "idempotent_replay"
                 ]
             },
+            "SendPermissionRule": {
+                "description": "One recipient-scope rule describing a destination the caller\nmay send to. Discriminated on `type`. Each rule carries a\nhuman-prose `description` field intended for display.\n\nRule kinds are stable within an SDK release. A response\ncontaining a `type` value not enumerated in this schema\nmeans the server is running a newer version than the SDK;\nupgrade the SDK to the release that matches the server's\nschema. Strict-parsing SDKs (Go, Python) will raise a\ndecode error in that case rather than silently dropping\nthe unknown rule, since silent drops would let an outbound\nagent reason from an incomplete view of its own permissions.\n",
+                "discriminator": {
+                    "propertyName": "type",
+                    "mapping": {
+                        "any_recipient": "#/components/schemas/SendPermissionAnyRecipient",
+                        "managed_zone": "#/components/schemas/SendPermissionManagedZone",
+                        "your_domain": "#/components/schemas/SendPermissionYourDomain",
+                        "address": "#/components/schemas/SendPermissionAddress"
+                    }
+                },
+                "oneOf": [
+                    {
+                        "$ref": "#/components/schemas/SendPermissionAnyRecipient"
+                    },
+                    {
+                        "$ref": "#/components/schemas/SendPermissionManagedZone"
+                    },
+                    {
+                        "$ref": "#/components/schemas/SendPermissionYourDomain"
+                    },
+                    {
+                        "$ref": "#/components/schemas/SendPermissionAddress"
+                    }
+                ]
+            },
+            "SendPermissionAnyRecipient": {
+                "type": "object",
+                "description": "The caller can send to any recipient. When this rule is\npresent, every other rule in the response is redundant.\n",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": [
+                            "any_recipient"
+                        ]
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Human-prose summary of the rule."
+                    }
+                },
+                "required": [
+                    "type",
+                    "description"
+                ]
+            },
+            "SendPermissionManagedZone": {
+                "type": "object",
+                "description": "The caller can send to any address at the named\nPrimitive-managed zone. Always emitted (no entitlement\nrequired) because Primitive owns the zone and every mailbox\nbelongs to a Primitive customer by construction.\n",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": [
+                            "managed_zone"
+                        ]
+                    },
+                    "zone": {
+                        "type": "string",
+                        "description": "The managed apex domain. Sends are accepted to any\naddress at the apex itself or any subdomain (e.g.\n`alice@primitive.email` and `alice@acme.primitive.email`\nboth match the `primitive.email` zone rule).\n"
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Human-prose summary of the rule."
+                    }
+                },
+                "required": [
+                    "type",
+                    "zone",
+                    "description"
+                ]
+            },
+            "SendPermissionYourDomain": {
+                "type": "object",
+                "description": "The caller can send to any address at one of their own\nverified outbound domains. Emitted once per active row in\nthe org's `domains` table.\n",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": [
+                            "your_domain"
+                        ]
+                    },
+                    "domain": {
+                        "type": "string",
+                        "description": "A verified outbound domain owned by the caller's org."
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Human-prose summary of the rule."
+                    }
+                },
+                "required": [
+                    "type",
+                    "domain",
+                    "description"
+                ]
+            },
+            "SendPermissionAddress": {
+                "type": "object",
+                "description": "The caller can send to a specific address that has\nauthenticated inbound mail to the org. Emitted once per row\nin the org's `known_send_addresses` table, capped at\n`meta.address_cap`.\n",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": [
+                            "address"
+                        ]
+                    },
+                    "address": {
+                        "type": "string",
+                        "description": "The bare email address this rule grants sends to."
+                    },
+                    "last_received_at": {
+                        "type": "string",
+                        "format": "date-time",
+                        "description": "Most recent inbound email from this address that\nauthenticated successfully (DMARC pass + DKIM/SPF\nalignment). Updated on each new authenticated receipt.\n"
+                    },
+                    "received_count": {
+                        "type": "integer",
+                        "description": "Total number of authenticated inbound emails from this\naddress. Increments only when `last_received_at` advances.\n"
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Human-prose summary of the rule."
+                    }
+                },
+                "required": [
+                    "type",
+                    "address",
+                    "last_received_at",
+                    "received_count",
+                    "description"
+                ]
+            },
+            "SendPermissionsMeta": {
+                "type": "object",
+                "description": "Response metadata for /send-permissions. The `address_cap`\nbounds the size of the `address` rule subset; orgs with more\nthan `address_cap` known addresses almost always also hold a\nbroader rule type (`any_recipient` or `your_domain`), so the\ncap is a response-size bound rather than a meaningful\nproduct limit.\n",
+                "properties": {
+                    "address_cap": {
+                        "type": "integer",
+                        "description": "Maximum number of `address` rules included in `data`."
+                    },
+                    "truncated": {
+                        "type": "boolean",
+                        "description": "True when the org has more than `address_cap` known\naddresses and the list was truncated. False when every\nknown address is represented or when the org holds no\naddress rules at all.\n"
+                    }
+                },
+                "required": [
+                    "address_cap",
+                    "truncated"
+                ]
+            },
             "Endpoint": {
                 "type": "object",
                 "properties": {

package/dist/openapi/operations.generated.js

@@ -371,7 +371,7 @@ export const operationManifest = [
         "binaryResponse": false,
         "bodyRequired": false,
         "command": "list-emails",
-        "description": "Returns a paginated list of received emails. Supports filtering by\ndomain, status, date range, and free-text search across subject,\nsender, and recipient fields.\n",
+        "description": "Returns a paginated list of INBOUND emails received at your\nverified domains. Outbound messages sent via /send-mail are not\nincluded; this endpoint is the inbox view, not a unified\nsend/receive history.\n\nSupports filtering by domain, status, date range, and free-text\nsearch across subject, sender, and recipient fields.\n",
         "hasJsonBody": false,
         "method": "GET",
         "operationId": "listEmails",
@@ -435,7 +435,7 @@ export const operationManifest = [
         ],
         "requestSchema": null,
         "sdkName": "listEmails",
-        "summary": "List emails",
+        "summary": "List inbound emails",
         "tag": "Emails",
         "tagCommand": "emails"
     },
@@ -752,6 +752,23 @@ export const operationManifest = [
         "tag": "Filters",
         "tagCommand": "filters"
     },
+    {
+        "binaryResponse": false,
+        "bodyRequired": false,
+        "command": "get-send-permissions",
+        "description": "Returns a flat list of rules describing every recipient the\ncaller may send to. Each rule has a `type`, a kind-specific\npayload, and a human-readable `description`. If any rule\nmatches the recipient, /send-mail will accept the send under\nthe recipient-scope check.\n\nThe endpoint is the answer to \"where can I send\" without\nexposing internal entitlement names. Agents that don't\nrecognize a `type` can still read the `description` prose\nand act on it.\n\nRule kinds, ordered broadest-first so an agent can stop\nscanning at the first match:\n\n  1. `any_recipient` (one entry, only when the org can send\n     anywhere): every other rule below it is redundant.\n  2. `managed_zone` (always emitted, one per Primitive-managed\n     zone): sends to any address at *.primitive.email or\n     *.email.works always succeed; no entitlement required.\n  3. `your_domain` (one per active verified outbound domain\n     owned by the org): sends to that domain are approved.\n  4. `address` (one per address that has authenticated\n     inbound mail to the org, capped at `meta.address_cap`):\n     sends to that exact address are approved.\n\nThe list is informational, not an authorization check.\n/send-mail remains the source of truth on whether an\nindividual send will succeed (it also enforces the\nfrom-address and the `send_mail` entitlement, which are\nnot recipient-scope concerns and are not represented here).\n",
+        "hasJsonBody": false,
+        "method": "GET",
+        "operationId": "getSendPermissions",
+        "path": "/send-permissions",
+        "pathParams": [],
+        "queryParams": [],
+        "requestSchema": null,
+        "sdkName": "getSendPermissions",
+        "summary": "List send-permission rules",
+        "tag": "Sending",
+        "tagCommand": "sending"
+    },
     {
         "binaryResponse": false,
         "bodyRequired": true,

package/oclif.manifest.json

@@ -342,7 +342,7 @@
           "type": "boolean"
         },
         "spam-threshold": {
-          "description": "Global spam score threshold (0-15). Emails scoring above this are rejected. S...",
+          "description": "Global spam score threshold (0-15). Emails scoring above this are rejected. Set to null to disable.",
           "name": "spam-threshold",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -784,7 +784,7 @@
     "emails:list-emails": {
       "aliases": [],
       "args": {},
-      "description": "Returns a paginated list of received emails. Supports filtering by\ndomain, status, date range, and free-text search across subject,\nsender, and recipient fields.\n",
+      "description": "Returns a paginated list of INBOUND emails received at your\nverified domains. Outbound messages sent via /send-mail are not\nincluded; this endpoint is the inbox view, not a unified\nsend/receive history.\n\nSupports filtering by domain, status, date range, and free-text\nsearch across subject, sender, and recipient fields.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
@@ -872,7 +872,7 @@
       "pluginName": "@primitivedotdev/sdk",
       "pluginType": "core",
       "strict": true,
-      "summary": "List emails",
+      "summary": "List inbound emails",
       "enableJsonFlag": false
     },
     "emails:replay-email-webhooks": {
@@ -1370,6 +1370,38 @@
       "summary": "Update a filter rule",
       "enableJsonFlag": false
     },
+    "sending:get-send-permissions": {
+      "aliases": [],
+      "args": {},
+      "description": "Returns a flat list of rules describing every recipient the\ncaller may send to. Each rule has a `type`, a kind-specific\npayload, and a human-readable `description`. If any rule\nmatches the recipient, /send-mail will accept the send under\nthe recipient-scope check.\n\nThe endpoint is the answer to \"where can I send\" without\nexposing internal entitlement names. Agents that don't\nrecognize a `type` can still read the `description` prose\nand act on it.\n\nRule kinds, ordered broadest-first so an agent can stop\nscanning at the first match:\n\n  1. `any_recipient` (one entry, only when the org can send\n     anywhere): every other rule below it is redundant.\n  2. `managed_zone` (always emitted, one per Primitive-managed\n     zone): sends to any address at *.primitive.email or\n     *.email.works always succeed; no entitlement required.\n  3. `your_domain` (one per active verified outbound domain\n     owned by the org): sends to that domain are approved.\n  4. `address` (one per address that has authenticated\n     inbound mail to the org, capped at `meta.address_cap`):\n     sends to that exact address are approved.\n\nThe list is informational, not an authorization check.\n/send-mail remains the source of truth on whether an\nindividual send will succeed (it also enforces the\nfrom-address and the `send_mail` entitlement, which are\nnot recipient-scope concerns and are not represented here).\n",
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base-url": {
+          "description": "API base URL (defaults to PRIMITIVE_API_URL or production)",
+          "env": "PRIMITIVE_API_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "sending:get-send-permissions",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "List send-permission rules",
+      "enableJsonFlag": false
+    },
     "sending:reply-to-email": {
       "aliases": [],
       "args": {},
@@ -1421,21 +1453,21 @@
           "type": "option"
         },
         "body-text": {
-          "description": "Plain-text reply body. At least one of body_text or body_html is required. Th...",
+          "description": "Plain-text reply 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 (same cap as send-mail).",
           "name": "body-text",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "from": {
-          "description": "Optional override for the reply's From header. Defaults to",
+          "description": "Optional override for the reply's From header. Defaults to the inbound's recipient. Use to add a display name (`\"Acme Support\" <agent@company.com>`) or to reply from a different verified outbound address (e.g. multi-team routing where support@ triages to billing@). The from-domain must be a verified outbound domain for your org, same as send-mail.",
           "name": "from",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "wait": {
-          "description": "When true, wait for the first downstream SMTP delivery outcome before returni...",
+          "description": "When true, wait for the first downstream SMTP delivery outcome before returning, mirroring the send-mail `wait` semantics.",
           "name": "wait",
           "allowNo": false,
           "type": "boolean"
@@ -1487,7 +1519,7 @@
           "type": "option"
         },
         "from": {
-          "description": "RFC 5322 From header. The sender domain must be a verified outbound domain fo...",
+          "description": "RFC 5322 From header. The sender domain must be a verified outbound domain for your organization.",
           "name": "from",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1501,21 +1533,21 @@
           "type": "option"
         },
         "to": {
-          "description": "Recipient address. Recipient eligibility depends on your account's outbound e...",
+          "description": "Recipient address. Recipient eligibility depends on your account's outbound entitlements.",
           "name": "to",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-html": {
-          "description": "HTML message body. At least one of body_text or body_html is required. The co...",
+          "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.",
           "name": "body-html",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "body-text": {
-          "description": "Plain-text message body. At least one of body_text or body_html is required. ...",
+          "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.",
           "name": "body-text",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1535,7 +1567,7 @@
           "type": "boolean"
         },
         "wait-timeout-ms": {
-          "description": "Maximum time to wait for a delivery outcome when wait is true. Defaults to 30...",
+          "description": "Maximum time to wait for a delivery outcome when wait is true. Defaults to 30000.",
           "name": "wait-timeout-ms",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1679,5 +1711,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.12.0"
+  "version": "0.13.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Official Primitive Node.js SDK — webhook, api, openapi, contract, and parser modules",
   "type": "module",
   "module": "./dist/index.js",