shipmail 0.5.6 → 0.5.8

package/README.md

@@ -93,15 +93,15 @@ const shipmail = new ShipmailClient({
 });
 ```
 
-| Option           | Type                     | Default                      | Description                                                     |
-| ---------------- | ------------------------ | ---------------------------- | --------------------------------------------------------------- |
-| `apiKey`         | `string`                 | required                     | Shipmail API key (`sm_live_...`).                               |
-| `baseUrl`        | `string`                 | `https://shipmail.to/api/v1` | API base URL.                                                   |
-| `maxRetries`     | `number`                 | `2`                          | Retry count on 5xx and 429. Total attempts is `maxRetries + 1`. |
-| `timeout`        | `number`                 | `30_000`                     | Per-request timeout in ms.                                      |
-| `fetch`          | `typeof fetch`           | `globalThis.fetch`           | Custom fetch implementation.                                    |
-| `defaultHeaders` | `Record<string, string>` | `{}`                         | Headers added to every request.                                 |
-| `organizationId` | `string`                 | none                         | Delegated child organization for approved infrastructure calls. |
+| Option           | Type                     | Default                      | Description                                                         |
+| ---------------- | ------------------------ | ---------------------------- | ------------------------------------------------------------------- |
+| `apiKey`         | `string`                 | required                     | Shipmail API key (`sm_live_...`).                                   |
+| `baseUrl`        | `string`                 | `https://shipmail.to/api/v1` | API base URL.                                                       |
+| `maxRetries`     | `number`                 | `2`                          | Retry count for eligible requests. Up to `maxRetries + 1` attempts. |
+| `timeout`        | `number`                 | `30_000`                     | Per-request timeout in ms.                                          |
+| `fetch`          | `typeof fetch`           | `globalThis.fetch`           | Custom fetch implementation.                                        |
+| `defaultHeaders` | `Record<string, string>` | `{}`                         | Headers added to every request.                                     |
+| `organizationId` | `string`                 | none                         | Delegated child organization for approved infrastructure calls.     |
 
 ## Domains
 
@@ -207,6 +207,13 @@ const draft = await shipmail.mailboxes.createInboxReplyDraft(mailboxId, candidat
 });
 // Apply your approval policy before sending. Stale versions fail with 409 without delivery.
 await shipmail.mailboxes.sendInboxReplyDraft(mailboxId, candidate.conversation_id, draft.id);
+
+// Save a new message to Drafts for a person to review and send. This never sends.
+const newDraft = await shipmail.mailboxes.createInboxDraft(mailboxId, {
+  to: ["jane@example.com"],
+  subject: "Quick intro",
+  text: "Hi Jane,",
+});
 ```
 
 ## Messages
@@ -730,21 +737,25 @@ try {
 }
 ```
 
-| Error                 | When                                                           |
-| --------------------- | -------------------------------------------------------------- |
-| `AuthenticationError` | 401. Bad or missing API key.                                   |
-| `AuthorizationError`  | 403. Key lacks permission for the resource.                    |
-| `ValidationError`     | 400 or 422. See `details` for per-field errors.                |
-| `NotFoundError`       | 404.                                                           |
-| `ConflictError`       | 409. Resource already exists or state conflict.                |
-| `RateLimitError`      | 429. Read `retryAfter` (seconds).                              |
-| `QuotaExceededError`  | 402. Plan or sending quota exceeded.                           |
-| `InternalServerError` | 5xx. Retried automatically up to `maxRetries`.                 |
-| `ConnectionError`     | Network error, timeout, or DNS failure. Retried automatically. |
+| Error                 | When                                                             |
+| --------------------- | ---------------------------------------------------------------- |
+| `AuthenticationError` | 401. Bad or missing API key.                                     |
+| `AuthorizationError`  | 403. Key lacks permission for the resource.                      |
+| `ValidationError`     | 400 or 422. See `details` for per-field errors.                  |
+| `NotFoundError`       | 404.                                                             |
+| `ConflictError`       | 409. Resource already exists or state conflict.                  |
+| `RateLimitError`      | 429. Read `retryAfter` (seconds).                                |
+| `QuotaExceededError`  | 402. Plan or sending quota exceeded.                             |
+| `InternalServerError` | 5xx. Eligible requests retry up to `maxRetries`.                 |
+| `ConnectionError`     | Network error, timeout, or DNS failure. Eligible requests retry. |
 
 ## Retries
 
-The SDK retries on `5xx`, `429`, and connection errors with exponential backoff and jitter. `Retry-After` is honored when present. Default is 2 retries (3 total attempts).
+The SDK retries eligible requests after connection errors, `429` responses, and retryable `5xx` errors. Automatic retries apply to `GET`, `HEAD`, and `OPTIONS`. Only POST, PATCH, and PUT mutations can retry, and they require an explicit `idempotencyKey` method option or an `Idempotency-Key` header. Reuse the same key for the same operation. DELETE requests and errors marked non-retryable are never retried.
+
+`maxRetries` defaults to 2 (up to 3 total attempts) and must be a non-negative integer. Set it to 0 to disable retries.
+
+A valid `Retry-After` header, in seconds or HTTP-date format, takes precedence over the rate-limit error body's `retry_after`. Otherwise, retries use exponential backoff with jitter. If the requested delay exceeds 60 seconds, the SDK returns the error without retrying automatically; schedule any later retry after that delay.
 
 ```ts
 new ShipmailClient({ apiKey, maxRetries: 0 }); // disable retries

package/dist/api-key-scopes.cjs

@@ -26,6 +26,7 @@ var API_KEY_SCOPES = [
   "messages:read",
   "messages:write",
   "drafts:write",
+  "drafts:compose",
   "messages:send",
   "newsletters:read",
   "newsletters:write",
@@ -65,6 +66,7 @@ var API_KEY_SCOPE_DESCRIPTIONS = {
   "messages:read": "List and retrieve messages.",
   "messages:write": "Update, move, delete, and inject sandbox messages.",
   "drafts:write": "Create agent-safe reply drafts with server-derived recipients.",
+  "drafts:compose": "Save new-message drafts to a mailbox's Drafts folder for review. Cannot send.",
   "messages:send": "Send messages, replies, and approved reply drafts.",
   "newsletters:read": "List and retrieve newsletter drafts and campaigns.",
   "newsletters:write": "Create, update, test, schedule, cancel, and resume newsletters.",

package/dist/api-key-scopes.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/api-key-scopes.ts"],"names":[],"mappings":"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","file":"api-key-scopes.cjs","sourcesContent":["export const API_KEY_SCOPES = [\n  \"*\",\n  \"audiences:read\",\n  \"audiences:write\",\n  \"automations:read\",\n  \"automations:write\",\n  \"booking_pages:read\",\n  \"booking_pages:write\",\n  \"calendar:read\",\n  \"calendar:write\",\n  \"domains:read\",\n  \"domains:write\",\n  \"mailboxes:read\",\n  \"mailboxes:export\",\n  \"mailboxes:write\",\n  \"mailbox_credentials:read\",\n  \"mailbox_credentials:write\",\n  \"mailbox_forwarding:read\",\n  \"mailbox_forwarding:write\",\n  \"mailbox_rules:read\",\n  \"mailbox_rules:write\",\n  \"members:read\",\n  \"messages:read\",\n  \"messages:write\",\n  \"drafts:write\",\n  \"messages:send\",\n  \"newsletters:read\",\n  \"newsletters:write\",\n  \"threads:read\",\n  \"webhooks:read\",\n  \"webhooks:write\",\n  \"suppressions:read\",\n  \"suppressions:write\",\n  \"partner:organizations:read\",\n  \"partner:organizations:write\",\n  \"partner:organizations:access\",\n  \"partner:mailbox_credentials:issue\",\n  \"partner:usage:read\",\n] as const;\n\nexport type ApiKeyScope = (typeof API_KEY_SCOPES)[number];\n\nexport const API_KEY_SCOPE_DESCRIPTIONS: Readonly<Record<ApiKeyScope, string>> = {\n  \"*\": \"All non-partner API endpoints in this organization.\",\n  \"audiences:read\": \"List and retrieve newsletter audiences and their subscribers.\",\n  \"audiences:write\": \"Create audiences and add, update, or remove their subscribers.\",\n  \"automations:read\": \"List and retrieve assistant automations.\",\n  \"automations:write\": \"Create, update, and manually run assistant automations.\",\n  \"booking_pages:read\": \"List and retrieve booking pages.\",\n  \"booking_pages:write\": \"Create, update, and delete booking pages.\",\n  \"calendar:read\": \"List and retrieve calendar events and open availability.\",\n  \"calendar:write\": \"Create, update, and delete calendar events.\",\n  \"domains:read\": \"List, retrieve, and verify domains.\",\n  \"domains:write\": \"Create, update, and delete domains.\",\n  \"mailboxes:read\": \"List and retrieve mailboxes.\",\n  \"mailboxes:export\": \"Create and download mailbox content exports.\",\n  \"mailboxes:write\": \"Create, update, suspend, resume, and delete mailboxes.\",\n  \"mailbox_credentials:read\": \"List revocable app passwords for allowed mailboxes.\",\n  \"mailbox_credentials:write\": \"Create and revoke app passwords for allowed mailboxes.\",\n  \"mailbox_forwarding:read\": \"List forwarding destinations for allowed mailboxes.\",\n  \"mailbox_forwarding:write\": \"Create and remove forwarding destinations for allowed mailboxes.\",\n  \"mailbox_rules:read\": \"List deterministic server-side rules for allowed mailboxes.\",\n  \"mailbox_rules:write\": \"Create, replace, and remove deterministic rules for allowed mailboxes.\",\n  \"members:read\": \"List and retrieve organization members.\",\n  \"messages:read\": \"List and retrieve messages.\",\n  \"messages:write\": \"Update, move, delete, and inject sandbox messages.\",\n  \"drafts:write\": \"Create agent-safe reply drafts with server-derived recipients.\",\n  \"messages:send\": \"Send messages, replies, and approved reply drafts.\",\n  \"newsletters:read\": \"List and retrieve newsletter drafts and campaigns.\",\n  \"newsletters:write\": \"Create, update, test, schedule, cancel, and resume newsletters.\",\n  \"threads:read\": \"List threads and retrieve thread messages.\",\n  \"webhooks:read\": \"List webhooks, retrieve webhooks, and list deliveries.\",\n  \"webhooks:write\": \"Create, update, delete, test, and rotate webhooks.\",\n  \"suppressions:read\": \"List suppressed recipient addresses.\",\n  \"suppressions:write\": \"Remove addresses from the suppression list.\",\n  \"partner:organizations:read\": \"List and retrieve this partner's child organizations.\",\n  \"partner:organizations:write\": \"Create and manage this partner's child organizations.\",\n  \"partner:organizations:access\": \"Act on an active child using the delegated organization header.\",\n  \"partner:mailbox_credentials:issue\":\n    \"List and consume operator-approved grants for embedded-webmail credentials.\",\n  \"partner:usage:read\": \"Read consolidated child and mailbox usage for this partner.\",\n};\n\nexport function isApiKeyScope(value: string): value is ApiKeyScope {\n  return API_KEY_SCOPES.some((scope) => scope === value);\n}\n\nexport function apiKeyScopesGrant(\n  grantedScopes: readonly string[],\n  requiredScope: ApiKeyScope | \"public\",\n): boolean {\n  if (requiredScope === \"public\") return true;\n  if (requiredScope.startsWith(\"partner:\")) return grantedScopes.includes(requiredScope);\n  return grantedScopes.includes(\"*\") || grantedScopes.includes(requiredScope);\n}\n"]}
+{"version":3,"sources":["../src/api-key-scopes.ts"],"names":[],"mappings":"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","file":"api-key-scopes.cjs","sourcesContent":["export const API_KEY_SCOPES = [\n  \"*\",\n  \"audiences:read\",\n  \"audiences:write\",\n  \"automations:read\",\n  \"automations:write\",\n  \"booking_pages:read\",\n  \"booking_pages:write\",\n  \"calendar:read\",\n  \"calendar:write\",\n  \"domains:read\",\n  \"domains:write\",\n  \"mailboxes:read\",\n  \"mailboxes:export\",\n  \"mailboxes:write\",\n  \"mailbox_credentials:read\",\n  \"mailbox_credentials:write\",\n  \"mailbox_forwarding:read\",\n  \"mailbox_forwarding:write\",\n  \"mailbox_rules:read\",\n  \"mailbox_rules:write\",\n  \"members:read\",\n  \"messages:read\",\n  \"messages:write\",\n  \"drafts:write\",\n  \"drafts:compose\",\n  \"messages:send\",\n  \"newsletters:read\",\n  \"newsletters:write\",\n  \"threads:read\",\n  \"webhooks:read\",\n  \"webhooks:write\",\n  \"suppressions:read\",\n  \"suppressions:write\",\n  \"partner:organizations:read\",\n  \"partner:organizations:write\",\n  \"partner:organizations:access\",\n  \"partner:mailbox_credentials:issue\",\n  \"partner:usage:read\",\n] as const;\n\nexport type ApiKeyScope = (typeof API_KEY_SCOPES)[number];\n\nexport const API_KEY_SCOPE_DESCRIPTIONS: Readonly<Record<ApiKeyScope, string>> = {\n  \"*\": \"All non-partner API endpoints in this organization.\",\n  \"audiences:read\": \"List and retrieve newsletter audiences and their subscribers.\",\n  \"audiences:write\": \"Create audiences and add, update, or remove their subscribers.\",\n  \"automations:read\": \"List and retrieve assistant automations.\",\n  \"automations:write\": \"Create, update, and manually run assistant automations.\",\n  \"booking_pages:read\": \"List and retrieve booking pages.\",\n  \"booking_pages:write\": \"Create, update, and delete booking pages.\",\n  \"calendar:read\": \"List and retrieve calendar events and open availability.\",\n  \"calendar:write\": \"Create, update, and delete calendar events.\",\n  \"domains:read\": \"List, retrieve, and verify domains.\",\n  \"domains:write\": \"Create, update, and delete domains.\",\n  \"mailboxes:read\": \"List and retrieve mailboxes.\",\n  \"mailboxes:export\": \"Create and download mailbox content exports.\",\n  \"mailboxes:write\": \"Create, update, suspend, resume, and delete mailboxes.\",\n  \"mailbox_credentials:read\": \"List revocable app passwords for allowed mailboxes.\",\n  \"mailbox_credentials:write\": \"Create and revoke app passwords for allowed mailboxes.\",\n  \"mailbox_forwarding:read\": \"List forwarding destinations for allowed mailboxes.\",\n  \"mailbox_forwarding:write\": \"Create and remove forwarding destinations for allowed mailboxes.\",\n  \"mailbox_rules:read\": \"List deterministic server-side rules for allowed mailboxes.\",\n  \"mailbox_rules:write\": \"Create, replace, and remove deterministic rules for allowed mailboxes.\",\n  \"members:read\": \"List and retrieve organization members.\",\n  \"messages:read\": \"List and retrieve messages.\",\n  \"messages:write\": \"Update, move, delete, and inject sandbox messages.\",\n  \"drafts:write\": \"Create agent-safe reply drafts with server-derived recipients.\",\n  \"drafts:compose\": \"Save new-message drafts to a mailbox's Drafts folder for review. Cannot send.\",\n  \"messages:send\": \"Send messages, replies, and approved reply drafts.\",\n  \"newsletters:read\": \"List and retrieve newsletter drafts and campaigns.\",\n  \"newsletters:write\": \"Create, update, test, schedule, cancel, and resume newsletters.\",\n  \"threads:read\": \"List threads and retrieve thread messages.\",\n  \"webhooks:read\": \"List webhooks, retrieve webhooks, and list deliveries.\",\n  \"webhooks:write\": \"Create, update, delete, test, and rotate webhooks.\",\n  \"suppressions:read\": \"List suppressed recipient addresses.\",\n  \"suppressions:write\": \"Remove addresses from the suppression list.\",\n  \"partner:organizations:read\": \"List and retrieve this partner's child organizations.\",\n  \"partner:organizations:write\": \"Create and manage this partner's child organizations.\",\n  \"partner:organizations:access\": \"Act on an active child using the delegated organization header.\",\n  \"partner:mailbox_credentials:issue\":\n    \"List and consume operator-approved grants for embedded-webmail credentials.\",\n  \"partner:usage:read\": \"Read consolidated child and mailbox usage for this partner.\",\n};\n\nexport function isApiKeyScope(value: string): value is ApiKeyScope {\n  return API_KEY_SCOPES.some((scope) => scope === value);\n}\n\nexport function apiKeyScopesGrant(\n  grantedScopes: readonly string[],\n  requiredScope: ApiKeyScope | \"public\",\n): boolean {\n  if (requiredScope === \"public\") return true;\n  if (requiredScope.startsWith(\"partner:\")) return grantedScopes.includes(requiredScope);\n  return grantedScopes.includes(\"*\") || grantedScopes.includes(requiredScope);\n}\n"]}

package/dist/api-key-scopes.d.cts

@@ -1,4 +1,4 @@
-declare const API_KEY_SCOPES: readonly ["*", "audiences:read", "audiences:write", "automations:read", "automations:write", "booking_pages:read", "booking_pages:write", "calendar:read", "calendar:write", "domains:read", "domains:write", "mailboxes:read", "mailboxes:export", "mailboxes:write", "mailbox_credentials:read", "mailbox_credentials:write", "mailbox_forwarding:read", "mailbox_forwarding:write", "mailbox_rules:read", "mailbox_rules:write", "members:read", "messages:read", "messages:write", "drafts:write", "messages:send", "newsletters:read", "newsletters:write", "threads:read", "webhooks:read", "webhooks:write", "suppressions:read", "suppressions:write", "partner:organizations:read", "partner:organizations:write", "partner:organizations:access", "partner:mailbox_credentials:issue", "partner:usage:read"];
+declare const API_KEY_SCOPES: readonly ["*", "audiences:read", "audiences:write", "automations:read", "automations:write", "booking_pages:read", "booking_pages:write", "calendar:read", "calendar:write", "domains:read", "domains:write", "mailboxes:read", "mailboxes:export", "mailboxes:write", "mailbox_credentials:read", "mailbox_credentials:write", "mailbox_forwarding:read", "mailbox_forwarding:write", "mailbox_rules:read", "mailbox_rules:write", "members:read", "messages:read", "messages:write", "drafts:write", "drafts:compose", "messages:send", "newsletters:read", "newsletters:write", "threads:read", "webhooks:read", "webhooks:write", "suppressions:read", "suppressions:write", "partner:organizations:read", "partner:organizations:write", "partner:organizations:access", "partner:mailbox_credentials:issue", "partner:usage:read"];
 type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
 declare const API_KEY_SCOPE_DESCRIPTIONS: Readonly<Record<ApiKeyScope, string>>;
 declare function isApiKeyScope(value: string): value is ApiKeyScope;

package/dist/api-key-scopes.d.ts

@@ -1,4 +1,4 @@
-declare const API_KEY_SCOPES: readonly ["*", "audiences:read", "audiences:write", "automations:read", "automations:write", "booking_pages:read", "booking_pages:write", "calendar:read", "calendar:write", "domains:read", "domains:write", "mailboxes:read", "mailboxes:export", "mailboxes:write", "mailbox_credentials:read", "mailbox_credentials:write", "mailbox_forwarding:read", "mailbox_forwarding:write", "mailbox_rules:read", "mailbox_rules:write", "members:read", "messages:read", "messages:write", "drafts:write", "messages:send", "newsletters:read", "newsletters:write", "threads:read", "webhooks:read", "webhooks:write", "suppressions:read", "suppressions:write", "partner:organizations:read", "partner:organizations:write", "partner:organizations:access", "partner:mailbox_credentials:issue", "partner:usage:read"];
+declare const API_KEY_SCOPES: readonly ["*", "audiences:read", "audiences:write", "automations:read", "automations:write", "booking_pages:read", "booking_pages:write", "calendar:read", "calendar:write", "domains:read", "domains:write", "mailboxes:read", "mailboxes:export", "mailboxes:write", "mailbox_credentials:read", "mailbox_credentials:write", "mailbox_forwarding:read", "mailbox_forwarding:write", "mailbox_rules:read", "mailbox_rules:write", "members:read", "messages:read", "messages:write", "drafts:write", "drafts:compose", "messages:send", "newsletters:read", "newsletters:write", "threads:read", "webhooks:read", "webhooks:write", "suppressions:read", "suppressions:write", "partner:organizations:read", "partner:organizations:write", "partner:organizations:access", "partner:mailbox_credentials:issue", "partner:usage:read"];
 type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
 declare const API_KEY_SCOPE_DESCRIPTIONS: Readonly<Record<ApiKeyScope, string>>;
 declare function isApiKeyScope(value: string): value is ApiKeyScope;

package/dist/api-key-scopes.js

@@ -24,6 +24,7 @@ var API_KEY_SCOPES = [
   "messages:read",
   "messages:write",
   "drafts:write",
+  "drafts:compose",
   "messages:send",
   "newsletters:read",
   "newsletters:write",
@@ -63,6 +64,7 @@ var API_KEY_SCOPE_DESCRIPTIONS = {
   "messages:read": "List and retrieve messages.",
   "messages:write": "Update, move, delete, and inject sandbox messages.",
   "drafts:write": "Create agent-safe reply drafts with server-derived recipients.",
+  "drafts:compose": "Save new-message drafts to a mailbox's Drafts folder for review. Cannot send.",
   "messages:send": "Send messages, replies, and approved reply drafts.",
   "newsletters:read": "List and retrieve newsletter drafts and campaigns.",
   "newsletters:write": "Create, update, test, schedule, cancel, and resume newsletters.",

package/dist/api-key-scopes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/api-key-scopes.ts"],"names":[],"mappings":"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","file":"api-key-scopes.js","sourcesContent":["export const API_KEY_SCOPES = [\n  \"*\",\n  \"audiences:read\",\n  \"audiences:write\",\n  \"automations:read\",\n  \"automations:write\",\n  \"booking_pages:read\",\n  \"booking_pages:write\",\n  \"calendar:read\",\n  \"calendar:write\",\n  \"domains:read\",\n  \"domains:write\",\n  \"mailboxes:read\",\n  \"mailboxes:export\",\n  \"mailboxes:write\",\n  \"mailbox_credentials:read\",\n  \"mailbox_credentials:write\",\n  \"mailbox_forwarding:read\",\n  \"mailbox_forwarding:write\",\n  \"mailbox_rules:read\",\n  \"mailbox_rules:write\",\n  \"members:read\",\n  \"messages:read\",\n  \"messages:write\",\n  \"drafts:write\",\n  \"messages:send\",\n  \"newsletters:read\",\n  \"newsletters:write\",\n  \"threads:read\",\n  \"webhooks:read\",\n  \"webhooks:write\",\n  \"suppressions:read\",\n  \"suppressions:write\",\n  \"partner:organizations:read\",\n  \"partner:organizations:write\",\n  \"partner:organizations:access\",\n  \"partner:mailbox_credentials:issue\",\n  \"partner:usage:read\",\n] as const;\n\nexport type ApiKeyScope = (typeof API_KEY_SCOPES)[number];\n\nexport const API_KEY_SCOPE_DESCRIPTIONS: Readonly<Record<ApiKeyScope, string>> = {\n  \"*\": \"All non-partner API endpoints in this organization.\",\n  \"audiences:read\": \"List and retrieve newsletter audiences and their subscribers.\",\n  \"audiences:write\": \"Create audiences and add, update, or remove their subscribers.\",\n  \"automations:read\": \"List and retrieve assistant automations.\",\n  \"automations:write\": \"Create, update, and manually run assistant automations.\",\n  \"booking_pages:read\": \"List and retrieve booking pages.\",\n  \"booking_pages:write\": \"Create, update, and delete booking pages.\",\n  \"calendar:read\": \"List and retrieve calendar events and open availability.\",\n  \"calendar:write\": \"Create, update, and delete calendar events.\",\n  \"domains:read\": \"List, retrieve, and verify domains.\",\n  \"domains:write\": \"Create, update, and delete domains.\",\n  \"mailboxes:read\": \"List and retrieve mailboxes.\",\n  \"mailboxes:export\": \"Create and download mailbox content exports.\",\n  \"mailboxes:write\": \"Create, update, suspend, resume, and delete mailboxes.\",\n  \"mailbox_credentials:read\": \"List revocable app passwords for allowed mailboxes.\",\n  \"mailbox_credentials:write\": \"Create and revoke app passwords for allowed mailboxes.\",\n  \"mailbox_forwarding:read\": \"List forwarding destinations for allowed mailboxes.\",\n  \"mailbox_forwarding:write\": \"Create and remove forwarding destinations for allowed mailboxes.\",\n  \"mailbox_rules:read\": \"List deterministic server-side rules for allowed mailboxes.\",\n  \"mailbox_rules:write\": \"Create, replace, and remove deterministic rules for allowed mailboxes.\",\n  \"members:read\": \"List and retrieve organization members.\",\n  \"messages:read\": \"List and retrieve messages.\",\n  \"messages:write\": \"Update, move, delete, and inject sandbox messages.\",\n  \"drafts:write\": \"Create agent-safe reply drafts with server-derived recipients.\",\n  \"messages:send\": \"Send messages, replies, and approved reply drafts.\",\n  \"newsletters:read\": \"List and retrieve newsletter drafts and campaigns.\",\n  \"newsletters:write\": \"Create, update, test, schedule, cancel, and resume newsletters.\",\n  \"threads:read\": \"List threads and retrieve thread messages.\",\n  \"webhooks:read\": \"List webhooks, retrieve webhooks, and list deliveries.\",\n  \"webhooks:write\": \"Create, update, delete, test, and rotate webhooks.\",\n  \"suppressions:read\": \"List suppressed recipient addresses.\",\n  \"suppressions:write\": \"Remove addresses from the suppression list.\",\n  \"partner:organizations:read\": \"List and retrieve this partner's child organizations.\",\n  \"partner:organizations:write\": \"Create and manage this partner's child organizations.\",\n  \"partner:organizations:access\": \"Act on an active child using the delegated organization header.\",\n  \"partner:mailbox_credentials:issue\":\n    \"List and consume operator-approved grants for embedded-webmail credentials.\",\n  \"partner:usage:read\": \"Read consolidated child and mailbox usage for this partner.\",\n};\n\nexport function isApiKeyScope(value: string): value is ApiKeyScope {\n  return API_KEY_SCOPES.some((scope) => scope === value);\n}\n\nexport function apiKeyScopesGrant(\n  grantedScopes: readonly string[],\n  requiredScope: ApiKeyScope | \"public\",\n): boolean {\n  if (requiredScope === \"public\") return true;\n  if (requiredScope.startsWith(\"partner:\")) return grantedScopes.includes(requiredScope);\n  return grantedScopes.includes(\"*\") || grantedScopes.includes(requiredScope);\n}\n"]}
+{"version":3,"sources":["../src/api-key-scopes.ts"],"names":[],"mappings":"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","file":"api-key-scopes.js","sourcesContent":["export const API_KEY_SCOPES = [\n  \"*\",\n  \"audiences:read\",\n  \"audiences:write\",\n  \"automations:read\",\n  \"automations:write\",\n  \"booking_pages:read\",\n  \"booking_pages:write\",\n  \"calendar:read\",\n  \"calendar:write\",\n  \"domains:read\",\n  \"domains:write\",\n  \"mailboxes:read\",\n  \"mailboxes:export\",\n  \"mailboxes:write\",\n  \"mailbox_credentials:read\",\n  \"mailbox_credentials:write\",\n  \"mailbox_forwarding:read\",\n  \"mailbox_forwarding:write\",\n  \"mailbox_rules:read\",\n  \"mailbox_rules:write\",\n  \"members:read\",\n  \"messages:read\",\n  \"messages:write\",\n  \"drafts:write\",\n  \"drafts:compose\",\n  \"messages:send\",\n  \"newsletters:read\",\n  \"newsletters:write\",\n  \"threads:read\",\n  \"webhooks:read\",\n  \"webhooks:write\",\n  \"suppressions:read\",\n  \"suppressions:write\",\n  \"partner:organizations:read\",\n  \"partner:organizations:write\",\n  \"partner:organizations:access\",\n  \"partner:mailbox_credentials:issue\",\n  \"partner:usage:read\",\n] as const;\n\nexport type ApiKeyScope = (typeof API_KEY_SCOPES)[number];\n\nexport const API_KEY_SCOPE_DESCRIPTIONS: Readonly<Record<ApiKeyScope, string>> = {\n  \"*\": \"All non-partner API endpoints in this organization.\",\n  \"audiences:read\": \"List and retrieve newsletter audiences and their subscribers.\",\n  \"audiences:write\": \"Create audiences and add, update, or remove their subscribers.\",\n  \"automations:read\": \"List and retrieve assistant automations.\",\n  \"automations:write\": \"Create, update, and manually run assistant automations.\",\n  \"booking_pages:read\": \"List and retrieve booking pages.\",\n  \"booking_pages:write\": \"Create, update, and delete booking pages.\",\n  \"calendar:read\": \"List and retrieve calendar events and open availability.\",\n  \"calendar:write\": \"Create, update, and delete calendar events.\",\n  \"domains:read\": \"List, retrieve, and verify domains.\",\n  \"domains:write\": \"Create, update, and delete domains.\",\n  \"mailboxes:read\": \"List and retrieve mailboxes.\",\n  \"mailboxes:export\": \"Create and download mailbox content exports.\",\n  \"mailboxes:write\": \"Create, update, suspend, resume, and delete mailboxes.\",\n  \"mailbox_credentials:read\": \"List revocable app passwords for allowed mailboxes.\",\n  \"mailbox_credentials:write\": \"Create and revoke app passwords for allowed mailboxes.\",\n  \"mailbox_forwarding:read\": \"List forwarding destinations for allowed mailboxes.\",\n  \"mailbox_forwarding:write\": \"Create and remove forwarding destinations for allowed mailboxes.\",\n  \"mailbox_rules:read\": \"List deterministic server-side rules for allowed mailboxes.\",\n  \"mailbox_rules:write\": \"Create, replace, and remove deterministic rules for allowed mailboxes.\",\n  \"members:read\": \"List and retrieve organization members.\",\n  \"messages:read\": \"List and retrieve messages.\",\n  \"messages:write\": \"Update, move, delete, and inject sandbox messages.\",\n  \"drafts:write\": \"Create agent-safe reply drafts with server-derived recipients.\",\n  \"drafts:compose\": \"Save new-message drafts to a mailbox's Drafts folder for review. Cannot send.\",\n  \"messages:send\": \"Send messages, replies, and approved reply drafts.\",\n  \"newsletters:read\": \"List and retrieve newsletter drafts and campaigns.\",\n  \"newsletters:write\": \"Create, update, test, schedule, cancel, and resume newsletters.\",\n  \"threads:read\": \"List threads and retrieve thread messages.\",\n  \"webhooks:read\": \"List webhooks, retrieve webhooks, and list deliveries.\",\n  \"webhooks:write\": \"Create, update, delete, test, and rotate webhooks.\",\n  \"suppressions:read\": \"List suppressed recipient addresses.\",\n  \"suppressions:write\": \"Remove addresses from the suppression list.\",\n  \"partner:organizations:read\": \"List and retrieve this partner's child organizations.\",\n  \"partner:organizations:write\": \"Create and manage this partner's child organizations.\",\n  \"partner:organizations:access\": \"Act on an active child using the delegated organization header.\",\n  \"partner:mailbox_credentials:issue\":\n    \"List and consume operator-approved grants for embedded-webmail credentials.\",\n  \"partner:usage:read\": \"Read consolidated child and mailbox usage for this partner.\",\n};\n\nexport function isApiKeyScope(value: string): value is ApiKeyScope {\n  return API_KEY_SCOPES.some((scope) => scope === value);\n}\n\nexport function apiKeyScopesGrant(\n  grantedScopes: readonly string[],\n  requiredScope: ApiKeyScope | \"public\",\n): boolean {\n  if (requiredScope === \"public\") return true;\n  if (requiredScope.startsWith(\"partner:\")) return grantedScopes.includes(requiredScope);\n  return grantedScopes.includes(\"*\") || grantedScopes.includes(requiredScope);\n}\n"]}

package/dist/index.cjs

@@ -28,6 +28,7 @@ var API_KEY_SCOPES = [
   "messages:read",
   "messages:write",
   "drafts:write",
+  "drafts:compose",
   "messages:send",
   "newsletters:read",
   "newsletters:write",
@@ -67,6 +68,7 @@ var API_KEY_SCOPE_DESCRIPTIONS = {
   "messages:read": "List and retrieve messages.",
   "messages:write": "Update, move, delete, and inject sandbox messages.",
   "drafts:write": "Create agent-safe reply drafts with server-derived recipients.",
+  "drafts:compose": "Save new-message drafts to a mailbox's Drafts folder for review. Cannot send.",
   "messages:send": "Send messages, replies, and approved reply drafts.",
   "newsletters:read": "List and retrieve newsletter drafts and campaigns.",
   "newsletters:write": "Create, update, test, schedule, cancel, and resume newsletters.",
@@ -879,6 +881,15 @@ var Mailboxes = class extends ApiResource {
       methodOptions: options
     });
   }
+  /** Saves a new message to the mailbox's Drafts folder. It is never sent by this call. */
+  createInboxDraft(id, params, options) {
+    return this.client.request({
+      method: "POST",
+      path: `/mailboxes/${encodeURIComponent(id)}/inbox/drafts`,
+      body: params,
+      methodOptions: options
+    });
+  }
   createInboxReplyDraft(id, threadId, params, options) {
     return this.client.request({
       method: "POST",
@@ -1699,17 +1710,26 @@ var Webhooks = class extends ApiResource {
 };
 
 // src/version.ts
-var VERSION = "0.5.6";
+var VERSION = "0.5.8";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
 var DEFAULT_MAX_RETRIES = 2;
 var DEFAULT_TIMEOUT = 3e4;
+var MAX_RETRY_AFTER_MS = 6e4;
+function parseRetryAfter(value) {
+  if (!value?.trim()) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  if (/^[+-]?[\d.]+$/.test(value.trim())) return void 0;
+  const date = Date.parse(value);
+  return Number.isFinite(date) ? Math.max(0, date - Date.now()) : void 0;
+}
 function isRetryableStatus(status) {
   return status === 429 || status >= 500;
 }
 function calculateBackoff(attempt, retryAfterMs) {
-  if (retryAfterMs !== void 0 && retryAfterMs > 0) {
+  if (retryAfterMs !== void 0 && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) {
     return retryAfterMs;
   }
   const base2 = Math.min(2 ** attempt * 500, 8e3);
@@ -1752,6 +1772,9 @@ var ShipmailClient = class {
       this.defaultHeaders = config.defaultHeaders ? { ...config.defaultHeaders } : {};
       this.organizationId = config.organizationId;
     }
+    if (!Number.isSafeInteger(this.maxRetries) || this.maxRetries < 0) {
+      throw new RangeError("maxRetries must be a non-negative safe integer");
+    }
     this.audiences = new Audiences(this);
     this.automations = new Automations(this);
     this.bookingPages = new BookingPages(this);
@@ -1787,9 +1810,13 @@ var ShipmailClient = class {
     const url = this.buildUrl(options.path, options.query);
     let lastError;
     const methodOpts = options.methodOptions;
+    const retryHeaders = new Headers({ ...this.defaultHeaders, ...methodOpts?.headers });
+    const method = options.method.toUpperCase();
+    const idempotencyKey = methodOpts?.idempotencyKey || retryHeaders.get("Idempotency-Key");
+    const canRetry = ["GET", "HEAD", "OPTIONS"].includes(method) || ["POST", "PATCH", "PUT"].includes(method) && Boolean(idempotencyKey?.trim());
+    let retryAfterMs;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       if (attempt > 0) {
-        const retryAfterMs = lastError instanceof RateLimitError && lastError.retryAfter !== void 0 ? lastError.retryAfter * 1e3 : void 0;
         const delay = calculateBackoff(attempt - 1, retryAfterMs);
         await new Promise((resolve) => setTimeout(resolve, delay));
       }
@@ -1826,7 +1853,10 @@ var ShipmailClient = class {
         });
       } catch (err) {
         lastError = new ConnectionError(err instanceof Error ? err.message : "Request failed");
-        if (attempt < this.maxRetries) continue;
+        if (canRetry && !methodOpts?.signal?.aborted && attempt < this.maxRetries) {
+          retryAfterMs = void 0;
+          continue;
+        }
         throw lastError;
       }
       if (response.ok) {
@@ -1846,7 +1876,14 @@ var ShipmailClient = class {
           retryable: isRetryableStatus(response.status)
         });
       }
-      if (!lastError.retryable || attempt >= this.maxRetries) {
+      retryAfterMs = parseRetryAfter(response.headers.get("Retry-After"));
+      if (retryAfterMs === void 0 && lastError instanceof RateLimitError) {
+        const seconds = lastError.retryAfter;
+        if (typeof seconds === "number" && Number.isFinite(seconds) && seconds >= 0) {
+          retryAfterMs = seconds * 1e3;
+        }
+      }
+      if (!canRetry || !lastError.retryable || attempt >= this.maxRetries || retryAfterMs !== void 0 && retryAfterMs > MAX_RETRY_AFTER_MS) {
         throw lastError;
       }
     }