millionsend 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 Versions follow the MillionSend API they target; the API stays wire-compatible with Resend.
 
+## 0.9.0 — unreleased
+
+- `emails.receiving`: `list` (with `wait` long-polling and the `inboxId`, `to`, `from`, `since`, `subjectContains`, `unread`, `includeQuarantined` and `quarantined` filters), `get`, `reply`, `forward`, `remove`, and `attachments.list` / `attachments.get`.
+- `inboxes`: `create`, `list`, `get`, `update`, `remove`, plus `safety`, `codes.latest`, `quarantine`, `labels`, `threads` (with `threads.emails`) and `drafts` (with `send` and `reject`).
+- Replies, forwards and `drafts.send` resolve to `{ kind: "sent", email }`, or `{ kind: "draft", draft }` when the API holds the message for approval (HTTP 202).
+- A request with `wait` gets a deadline that outlasts it, so long-polls past `timeoutMs` no longer abort.
+- An id that is empty, `.` or `..` resolves to `{ error: { name: "validation_error", statusCode: null } }` without a request: URL normalization would have sent it to another resource.
+- The long-poll's `held` items carry `reason` (`pending` or `quarantined`) and `quarantine_reason`.
+- `WebhookEvent` names `email.received` and the 14 `inbox.*` events; webhooks take `inboxIds`; `apiKeys.create` takes `inboxId`; `domains.update` takes `receivingCatchAll`; `Domain`, `ApiKeyListItem`, `WebhookListItem` and `Usage.limits` gain `receiving_catch_all`, `inbox_id`, `inbox_ids` and `inboxes`.
+- `inboxes.create` takes `username` (the part before the @) and `domainId` (a `domains.list` row instead of `emailAddress`); `inboxes.codes.latest` takes `since`; thread list and search items carry an optional `quarantined` count.
+- Domains carry `shared`; the team's shared row, listed last by `domains.list`, adds `sending_mode` (`DomainSendingMode`) and `sending_mode_reason`.
+- Every `ErrorResponse` carries `retryAfter`: the `retry-after` header in seconds, or `null`. A deep-equality check on `error` needs the new key.
+- Contacts batch `errors` items are `BatchContactError`, with the `statusCode` and `name` strict mode would answer.
+- The README covers newest-first lists and their cursors, retries, the shared domain's row, sending rules and refusals, and the recipients the API refuses.
+
+Each feature needs this MillionSend version or later. Older instances answer 404 on paths they lack and ignore options they don't know, so an inbox created with `username` or `domainId` on one can get another address: check its `email_address`.
+
+| MillionSend | Features |
+|---|---|
+| v0.10.0 | `inboxes`; the receiving long-poll, inbox filters, `reply` and `forward` |
+| v0.11.0 | `422` for recipients that can never receive mail; a batch `idempotencyKey` replayed before validation |
+| v0.12.0 | `username`; inboxes that never expire by default; sends from the shared domain under its mode; `name_review_unavailable`; `statusCode` and `name` on contacts batch errors |
+| v0.13.0 | newest-first lists; `since` on `codes.latest`; `quarantined` on thread items; inbox names up to 320 characters; `unread` with an inbox-scoped key; a JSON 404 for unknown routes |
+| v0.14.0 | `shared`, `sending_mode` and `sending_mode_reason` on domains; `domainId` on `inboxes.create`; `subject` up to 998 characters |
+
+## 0.8.0 — 2026-09-08
+
+- `contacts.remove(address, { erase: true })` and `contacts.batch.remove({ ids | emails, erase: true })` also scrub the address from email history, event payloads and API logs (`?erase=true` on the single delete, body `erase` on the batch) — a GDPR/LGPD erasure. Without `erase` a delete keeps the contact's emails in the send log, as before. Responses are unchanged. Needs MillionSend v0.6.54.
+
 ## 0.7.0 — 2026-09-05
 
 - `contacts.list({ include: ["properties", "topics"] })` attaches the property map and the topic subscriptions to every item (`?include=`), on the team list and on `segmentId` lists alike. Without `include` the item is unchanged.

package/README.md

@@ -25,7 +25,7 @@ const ms = new MillionSend("ms_123"); // Cloud; self-hosted: { baseUrl: "https:/
 
 const { data, error } = await ms.emails.send({
   from: "Acme <onboarding@acme.dev>",
-  to: "delivered@resend.dev",
+  to: "success@simulator.amazonses.com",
   subject: "Hello from MillionSend",
   html: "<strong>It works!</strong>",
 });
@@ -56,27 +56,68 @@ new MillionSend(apiKey?, {
 ## Errors
 
 No method throws for an API error — every call resolves to `{ data, error }`.
-`error` is `null` on success; otherwise `{ name, message, statusCode }` where
+`error` is `null` on success; otherwise `{ name, message, statusCode, retryAfter }` where
 `name` is a stable snake_case code you can switch on (`validation_error`,
-`not_found`, `restricted_api_key`, `sending_paused`,
+`not_found`, `forbidden`, `restricted_api_key`, `rate_limit_exceeded`, `sending_paused`,
 `all_recipients_suppressed`, …). Client-side and transport failures carry
-`statusCode: null`.
+`statusCode: null`. `retryAfter` is the response's `retry-after` header in seconds, or
+`null` when it has none.
 
 `emails.send` and `batch.send` answer `422 all_recipients_suppressed` when every
 `to` recipient is on the suppression list or opted out of the send's `topicId`.
 
+Inboxes add `inbox_send_policy` (403, a send the inbox's rules or the shared domain hold),
+`inbox_send_cap_reached` (429, the inbox's or the team's daily cap), `approval_required` (403),
+`email_quarantined` (403), `email_blocked` (410, a download of an email that carries malware),
+`too_many_waits` (429, too many concurrent long-polls) and `name_review_unavailable` (503, a
+name on the shared domain can't be reviewed yet).
+
 ```ts
 const { data, error } = await ms.emails.get(id);
 if (error?.name === "not_found") { /* … */ }
 ```
 
+### Retries
+
+The SDK never retries on its own. Worth retrying after `retryAfter` seconds:
+`503 name_review_unavailable`, `429 too_many_waits`, and `429 rate_limit_exceeded` when
+`retryAfter` is 60 or less (the per-minute limits). Not worth retrying in the same process:
+`429 inbox_send_cap_reached` and the daily name-review budget (`429 rate_limit_exceeded`
+with a `retryAfter` that runs to the next UTC midnight), and any 403, 404, 409 or 422. An
+unknown route answers `404 not_found` (`application_error` from servers before v0.13.0).
+
+Resend a send with the same `idempotencyKey`: a batch the API already accepted gets its
+stored response back. A held draft (`kind: "draft"`) is not a failure; never resend it.
+`inboxes.create` takes no idempotency key: after a 429 or 503 nothing was created, but
+after a timeout a resend can create a second inbox. With a chosen `username`, a 409 on the
+resend usually means the first attempt succeeded: read it with `inboxes.get(address)`.
+
 ## Resources
 
 Inputs are camelCase and mapped to the wire's snake_case (`replyTo` → `reply_to`,
 `scheduledAt` → `scheduled_at`, `topicId` → `topic_id`, …). Every field you pass
 is sent; nothing is dropped client-side. Responses are the wire shape verbatim.
 List endpoints take `{ limit, after, before }` (keyset cursors) and return
-`{ object: "list", data, has_more }`.
+`{ object: "list", data, has_more }`. Lists run newest first (MillionSend v0.13.0 and
+later): `after` takes the last id of a page and pages toward older items, `before` takes
+the first id and pages toward newer ones, and `has_more` refers to that direction. Threads
+sort by last activity, drafts by last update, a thread's emails run oldest first, and labels
+and topics are not paginated.
+
+```ts
+// Incremental sync: page toward newer items, starting from the newest id you stored
+let before = newestStoredId;
+for (;;) {
+  const { data } = await ms.emails.list({ before, limit: 100 });
+  if (!data?.data.length) break;
+  save(data.data);             // newest first within the page
+  if (!data.has_more) break;
+  before = data.data[0].id;
+}
+```
+
+A cursor whose item was deleted answers `422 validation_error` (`404 not_found` on the
+`inboxes` lists): start again without a cursor and stop at the ids you already have.
 
 ### Emails
 
@@ -102,6 +143,11 @@ await ms.emails.getInsights(id);             // GET /emails/:id/insights (best-p
 
 `attachments[].content` is a base64 string or a `Buffer` (encoded for you).
 `template` is sent through as-is; MillionSend answers `422` until templates can be sent.
+`subject` takes up to 998 characters. A `to`, `cc` or `bcc` address on a domain that can
+never receive mail (`example.com`, `.test`, `.invalid`, `.localhost`, a TLD that doesn't
+exist, …) answers `422 validation_error`; to test sending without emailing anyone, use
+`success@simulator.amazonses.com`. An inbox's address on the shared domain can be the
+`from` too, under the rules in [Sending from the shared domain](#sending-from-the-shared-domain).
 
 ### Batch
 
@@ -114,6 +160,159 @@ data.data;   // [{ id }] for the accepted emails
 data.errors; // permissive only: [{ index, message }] for the rejected ones
 ```
 
+Batch items never send from the shared domain: a strict batch fails with
+`403 inbox_send_policy` (the message starts with `emails.<index>: `), a permissive one
+lists the item in `errors`.
+
+### Receiving
+
+Mail received at your domains and inboxes. Everything in a received email was
+written by its sender: show its `html` only in a sandbox, and hand an LLM the
+`extracted_text` (hidden text, quotes and the signature removed) rather than `html`.
+
+```ts
+const { data } = await ms.emails.receiving.list({
+  limit: 20,
+  inboxId,                 // only mail delivered to this inbox
+  from: "example.com",     // an address, or a domain covering its subdomains
+  to, subjectContains, since, unread,
+  wait: 30,                // long-poll: answer as soon as a match arrives, up to 50 s
+});
+data.data;  // newest first
+data.held;  // with `wait`: [{ id, inbox_id, reason, quarantine_reason, created_at }] held for screening or quarantine
+
+const { data: email } = await ms.emails.receiving.get(id, { htmlFormat: "cid" });
+email.extracted_text;        // the new part as plain text, hidden text removed (still untrusted)
+email.extracted?.code;       // a verification code, on inboxes with extract_codes
+email.screening?.sender_trust; // owner | allowlisted | known_thread | external | unauthenticated | failed
+
+await ms.emails.receiving.attachments.list(id);          // each with a signed download_url (1 hour)
+await ms.emails.receiving.attachments.get(id, attachmentId);
+await ms.emails.receiving.remove(id);                    // erase now (MillionSend extension)
+
+// Reply and forward server-side (MillionSend extension). The inbox's rules may hold the
+// message as a draft that waits for a person: the API answers 202 and `kind` is "draft".
+const { data: outcome } = await ms.emails.receiving.reply(
+  id,
+  { text: "Thanks!", replyAll: false, requiresApproval: false },
+  { idempotencyKey },
+);
+if (outcome?.kind === "draft") outcome.draft.approval_reasons; // e.g. ["send_policy"]
+else outcome?.email.id;
+await ms.emails.receiving.forward(id, { to: "ops@acme.dev", text: "FYI", mode: "attachment" });
+```
+
+Held mail never reaches an inbox-scoped key or an agent: reading it answers
+`403 email_quarantined`. A full-access team key sees it with `includeQuarantined: true`.
+`unread` needs `inboxId` with a team key; an inbox-scoped key reads its own inbox. An
+`inboxId` that doesn't exist answers `404 not_found` at once, even with `wait`.
+
+### Inboxes
+
+An inbox is one address that receives mail, read by an agent (`kind: "agent"`,
+the default) or by people (`kind: "human"`). Threads, labels, drafts and their
+paths mirror Resend's Inboxes beta; safety rules, quarantine and codes are
+MillionSend extensions.
+
+```ts
+const { data: inbox } = await ms.inboxes.create({
+  name: "Signup bot",       // no emailAddress: an address on the shared domain
+  username: "signup-bot",   // signup-bot@<team>.<shared domain>; omit it for a random one
+  expiresIn: "24h",         // "1h" to "365d"; omitted or null, it never expires
+  safety: { acceptFrom: "anyone" },
+});
+await ms.inboxes.create({ emailAddress: "support@acme.dev", name: "Support", kind: "human" });
+await ms.inboxes.create({ domainId, username: "orders" }); // a domains.list id: orders@ that domain
+await ms.inboxes.list({ kind: "agent" });
+await ms.inboxes.get("support@acme.dev");                 // by id or address
+await ms.inboxes.update(inbox.id, { fromName: "Acme", expiresIn: "7d" });
+await ms.inboxes.remove(inbox.id);                        // also revokes its inbox-scoped keys
+
+// Codes and sign-in links, without parsing HTML (wait long-polls up to 50 s)
+const { data: code } = await ms.inboxes.codes.latest(inbox.id, { from: "github.com", wait: 30 });
+code.status; // "found" | "none" | "ambiguous" | "timeout"; code.code, code.url
+// The next sign-in: only a code received after the one already used
+await ms.inboxes.codes.latest(inbox.id, { since: code.received_at, wait: 30 });
+
+// Safety rules: who can write in, what the inbox may send
+await ms.inboxes.safety.get(inbox.id);
+await ms.inboxes.safety.update(inbox.id, { acceptFrom: "allowlist", allowlist: ["*@acme.dev"], sendCap: 50 });
+
+// Quarantine: held mail, kept until a person releases it
+await ms.inboxes.quarantine.list(inbox.id);
+await ms.inboxes.quarantine.release(inbox.id, emailId, { trustSender: true });
+
+// Threads and their messages
+await ms.inboxes.threads.list(inbox.id, { folders: ["inbox", "archive"], read: false });
+await ms.inboxes.threads.list(inbox.id, { includeQuarantined: true }); // owner views: a `quarantined` count per thread
+await ms.inboxes.threads.search(inbox.id, { query: "invoice", from: ["example.com"] });
+await ms.inboxes.threads.get(inbox.id, threadId);
+await ms.inboxes.threads.update(inbox.id, threadId, { read: true, folder: "archive", labelId });
+await ms.inboxes.threads.remove(inbox.id, threadId);      // to trash, purged after 30 days
+await ms.inboxes.threads.emails.list(inbox.id, threadId); // oldest first; includeQuarantined for owner views
+await ms.inboxes.threads.emails.get(inbox.id, threadId, emailId);
+await ms.inboxes.threads.emails.reply(inbox.id, threadId, emailId, { text: "Done." }, { idempotencyKey });
+await ms.inboxes.threads.emails.forward(inbox.id, threadId, emailId, { to: "ops@acme.dev" });
+
+// Labels (up to 100 per inbox)
+await ms.inboxes.labels.create(inbox.id, { name: "Billing", color: "#FF8800" });
+await ms.inboxes.labels.list(inbox.id);
+await ms.inboxes.labels.update(inbox.id, labelId, { name: "Invoices" });
+await ms.inboxes.labels.remove(inbox.id, labelId);
+
+// Drafts, and the ones that wait for approval
+await ms.inboxes.drafts.create(inbox.id, { to: "ada@acme.dev", subject: "Hi", text: "…" });
+await ms.inboxes.drafts.list(inbox.id);
+await ms.inboxes.drafts.get(inbox.id, draftId);
+await ms.inboxes.drafts.update(inbox.id, draftId, { cc: null });  // null clears
+await ms.inboxes.drafts.send(inbox.id, draftId, { idempotencyKey }); // { kind: "sent" | "draft" }
+await ms.inboxes.drafts.reject(inbox.id, draftId);
+await ms.inboxes.drafts.remove(inbox.id, draftId);
+```
+
+Replies, forwards and `drafts.send` resolve to `{ kind: "sent", email }` or, when
+the inbox's rules hold the message for a person (HTTP 202), `{ kind: "draft", draft }`.
+An agent's reply to a Reply-To at another organization is held that way too, with
+`"reply_to_redirect"` among its `approval_reasons`.
+A key restricted to the inbox cannot send a draft that waits for approval
+(`403 approval_required`); a person in the dashboard or a full-access team key approves it.
+Hosted agent settings (`/inboxes/:id/agent`) are not exposed: MillionSend runs no agent of its own.
+
+An inbox never expires unless `expiresIn` says so, and its `name` takes up to 320
+characters. `domainId` takes a `domains.list` row instead of `emailAddress`: the
+`shared: true` row works like leaving both out, and one of your own domains needs a
+`username`.
+
+On the shared domain, an inbox unused for 90 days (no mail in or out, no API call on it)
+is deleted, which fires `inbox.expired`, then `inbox.deleted`. A chosen `username` or
+`fromName` there is reviewed first: reserved names (`postmaster`, `admin`, `support`,
+`noreply`, …), a `fwd-` prefix and look-alikes of brands answer `422`, a username in use
+`409`, and `429` means today's review budget is spent. `503 name_review_unavailable`
+means try again after `retryAfter` seconds: the review is down, or the team's new
+subdomain still waits for its own, and then every shared or forwarding create gets it.
+Safety rules differ there too: `sendPolicy: "allowlist"` answers `422`, and so does
+`"open"` unless the team's `sending_mode` is `open`; `ownerAddresses` don't make senders
+trusted; `forwardTo` takes team members only.
+
+#### Sending from the shared domain
+
+What the team's shared addresses may send is the `sending_mode` of the `shared: true` row
+of `domains.list`: `open` starts conversations, `reply_only` only answers inside a thread
+to its own correspondents, and `receive_only` sends nothing. The same answers come back
+from `emails.send`, replies, forwards and drafts:
+
+- `403 inbox_send_policy`: the mode doesn't allow this send (or the inbox's name looks
+  like a brand, which only replies even under `open`);
+- `429 inbox_send_cap_reached`: the team's daily cap for the shared domain, with a
+  `retryAfter` that runs to the next UTC midnight;
+- `422 validation_error`: more than 10 distinct recipients across `to`, `cc` and `bcc`.
+
+`emails.send` takes a shared address in `open` mode only: the inbox's exact
+`email_address` (no +tag), a display name left out or equal to its `from_name`, and no
+`replyTo`, `attachments`, `headers` or `scheduledAt`. A key restricted to a domain gets
+`403 restricted_api_key`. Batch items and broadcasts never send from the shared domain.
+Switch on `name` and `statusCode`; the messages may change.
+
 ### Contacts
 
 Contacts are team-global — one list per team, no audiences.
@@ -128,7 +327,9 @@ await ms.contacts.create({
 await ms.contacts.get({ email });                  // by id or email (email wins)
 await ms.contacts.get(contactId);                  // bare string works too
 await ms.contacts.update({ id, unsubscribed: true, firstName: null }); // null clears
-await ms.contacts.remove({ email });
+await ms.contacts.remove({ email });               // the contact's emails stay in the send log
+await ms.contacts.remove({ email }, { erase: true }); // ?erase=true also scrubs the address from
+                                                      // email history, events and API logs (GDPR/LGPD)
 await ms.contacts.list({ limit: 50 });
 await ms.contacts.list({ segmentId });             // GET /segments/:id/contacts
 // Bulk read (MillionSend extension): attach properties and topic subscriptions to every item,
@@ -147,7 +348,7 @@ const { data } = await ms.contacts.batch.create(items, {
 });
 data.data;   // [{ index, id, status: "created" | "updated" | "skipped" }]
 data.counts; // { created, updated, skipped, failed }
-data.errors; // permissive only
+data.errors; // permissive only: [{ index, statusCode, name, message }], as strict mode would answer
 
 // Bulk lookup (MillionSend extension): up to 1000 contacts by id or email in one request,
 // in request order; unknown entries are listed, not errors — one request against the rate limit
@@ -155,8 +356,9 @@ const { data } = await ms.contacts.batch.get([contactId, { email }], { include:
 data.data;    // [{ object: "contact", id, email, ..., topics }] — the contacts found
 data.missing; // [{ index, email }] — request entries that matched nobody
 
-// Bulk delete (MillionSend extension): up to 1000 per call, by ids or by emails
-const { data } = await ms.contacts.batch.remove({ emails }); // or { ids }
+// Bulk delete (MillionSend extension): up to 1000 per call, by ids or by emails.
+// Their emails stay in the send log; erase: true also scrubs each address from email history
+const { data } = await ms.contacts.batch.remove({ emails, erase: true }); // or { ids }
 data.data; // [{ object: "contact", contact, deleted: true }] — only the rows actually deleted
 
 // Segment membership
@@ -210,6 +412,9 @@ await ms.broadcasts.cancel(id);   // scheduled only
 await ms.broadcasts.remove(id);   // draft only
 ```
 
+`subject` takes up to 998 characters. A broadcast never sends from the shared domain:
+`create({ send: true })` and `send` answer `403 inbox_send_policy`.
+
 ### Suppressions
 
 ```ts
@@ -233,9 +438,27 @@ await ms.domains.list();
 await ms.domains.get(id);
 await ms.domains.verify(id);
 await ms.domains.update({ id, clickTracking: false, trackingSubdomain: null }); // null clears
+await ms.domains.update({ id, receivingCatchAll: true }); // accept mail for addresses without an inbox
 await ms.domains.remove(id);
 ```
 
+On an instance with a shared inbox domain, the team's subdomain of it is the last row of
+`domains.list` (`shared: true`; MillionSend v0.14.0 and later). It is verified, has no DNS
+records, and its id is the `domainId` of the team's shared inboxes. Its `sending_mode`
+(`open`, `reply_only` or `receive_only`) says what those inboxes may send, and
+`sending_mode_reason` (`plan` or `instance`, `null` under `open`) why it is held below
+`open`. It is read-only: `update`, `verify` and `remove` answer `403 forbidden`, and an API
+key can't be restricted to it. It comes after every own domain whatever its `created_at`,
+alone on the next page when they exactly fill one. A team whose new subdomain still waits
+for its name review has no such row yet. Older servers send no `shared`: read it as `false`.
+
+It sends only from its inboxes' own addresses, so leave it out when picking a domain to send from:
+
+```ts
+const { data } = await ms.domains.list({ limit: 100 });
+const sender = data?.data.find((d) => d.status === "verified" && !d.shared);
+```
+
 ### Webhooks
 
 ```ts
@@ -256,19 +479,32 @@ const { data } = await ms.webhooks.rotate(id, { overlapHours: 24 }); // or { sig
 data.signing_secret; data.previous_secret_expires_at; // null when the old secret is dropped at once
 ```
 
-Subscribable events include `email.*`, `deliverability.*`, `quota.*`, `contact.*`
-(`created`, `updated`, `deleted`, `unsubscribed`, `resubscribed`, `topic_opt_in`,
-`topic_opt_out`) and `suppression.added` / `suppression.removed`.
+Subscribable events include `email.*` (with `email.received`), `deliverability.*`,
+`quota.*`, `contact.*` (`created`, `updated`, `deleted`, `unsubscribed`,
+`resubscribed`, `topic_opt_in`, `topic_opt_out`), `suppression.added` /
+`suppression.removed`, and the `inbox.*` events (`inbox.created`, `inbox.updated`,
+`inbox.deleted`, `inbox.expired`, `inbox.thread.created`, `inbox.thread.folder.updated`,
+`inbox.thread.labels.updated`, `inbox.email.received`, `inbox.email.sent`,
+`inbox.email.quarantined`, `inbox.draft.created`, `inbox.draft.updated`,
+`inbox.draft.sent`, `inbox.draft.deleted`). Inbox events reach only endpoints that
+list them by name. `inboxIds` limits an endpoint's inbox events and `email.received`
+to those inboxes (`null` = every inbox). Inbox events from sends made in the dashboard
+carry `data.source: "dashboard"`.
 
 ### API keys
 
 ```ts
 const { data } = await ms.apiKeys.create({ name: "ci", permission: "sending_access", domainId });
 data.token; // shown once
+await ms.apiKeys.create({ name: "signup-agent", permission: "full_access", inboxId }); // one inbox only
 await ms.apiKeys.list();
 await ms.apiKeys.remove(id);
 ```
 
+An inbox-scoped key reads only its inbox and sends only from its address; any other
+route answers `403 restricted_api_key`. `domainId` takes one of your own domains: the
+`shared: true` row of `domains.list` answers `422 validation_error`.
+
 ### Templates
 
 `id` arguments accept the template id or its alias.
@@ -337,8 +573,15 @@ match `resend`. Notes:
   answered with `422`. `templates.publish` is a no-op (every save is live).
 - **MillionSend extensions** (no Resend counterpart): `segments`,
   `deliverability`, `usage`, `emails.getInsights`, `contacts.batch`,
-  `contacts.preferencesLink`, `webhooks.rotate`, and the `origin` field on
-  suppressions.
+  `contacts.preferencesLink`, `webhooks.rotate`, the `origin` field on
+  suppressions, `emails.receiving.reply` / `remove`, `inboxes.safety`,
+  `inboxes.codes`, `inboxes.quarantine`, `inboxes.drafts.reject`, the `username` and
+  `domainId` of `inboxes.create`, and `error.retryAfter`.
+- **`emails.receiving.forward(id, payload)`** forwards server-side, from your
+  inbox or domain, instead of Resend's client-side re-send of the raw message.
+- **Inboxes** follow Resend's preview shapes with ids as positional arguments
+  (`ms.inboxes.threads.emails.reply(inboxId, threadId, emailId, payload)`), and
+  return the full object on create.
 
 ## License
 

package/dist/error.d.ts

@@ -10,6 +10,11 @@ export interface ErrorResponse {
     message: string;
     /** HTTP status; null when the request never reached the API. */
     statusCode: number | null;
+    /**
+     * Seconds the response's `retry-after` header asks to wait before trying
+     * again; null when it sent none (and on client-side failures).
+     */
+    retryAfter: number | null;
 }
 /** Every method resolves to this — it never throws for an API error. */
 export type Result<T> = {
@@ -20,5 +25,5 @@ export type Result<T> = {
     error: ErrorResponse;
 };
 /** Coerce an arbitrary parsed error body into the canonical shape. */
-export declare function toErrorResponse(body: unknown, status: number): ErrorResponse;
+export declare function toErrorResponse(body: unknown, status: number, retryAfter: number | null): ErrorResponse;
 //# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wEAAwE;AACxE,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAExF,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAa5E"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wEAAwE;AACxE,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAExF,sEAAsE;AACtE,wBAAgB,eAAe,CAC7B,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,aAAa,CAef"}

package/dist/error.js

@@ -1,16 +1,17 @@
 /** Coerce an arbitrary parsed error body into the canonical shape. */
-export function toErrorResponse(body, status) {
+export function toErrorResponse(body, status, retryAfter) {
     if (body && typeof body === "object") {
         const b = body;
         const name = typeof b.name === "string" ? b.name : "application_error";
         const message = typeof b.message === "string" ? b.message : `Request failed with status ${status}`;
         const statusCode = typeof b.statusCode === "number" ? b.statusCode : status;
-        return { name, message, statusCode };
+        return { name, message, statusCode, retryAfter };
     }
     return {
         name: "application_error",
         message: `Request failed with status ${status}`,
         statusCode: status,
+        retryAfter,
     };
 }
 //# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAiBA,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,IAAa,EAAE,MAAc;IAC3D,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAA+B,CAAC;QAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC;QACvE,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,8BAA8B,MAAM,EAAE,CAAC;QACnG,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC;QAC5E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IACvC,CAAC;IACD,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,8BAA8B,MAAM,EAAE;QAC/C,UAAU,EAAE,MAAM;KACnB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAsBA,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAC7B,IAAa,EACb,MAAc,EACd,UAAyB;IAEzB,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAA+B,CAAC;QAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC;QACvE,MAAM,OAAO,GACX,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,8BAA8B,MAAM,EAAE,CAAC;QACrF,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC;QAC5E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;IACnD,CAAC;IACD,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,8BAA8B,MAAM,EAAE;QAC/C,UAAU,EAAE,MAAM;QAClB,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import { type Result } from "./error.js";
-import type { BatchValidation } from "./types.js";
+import type { BatchValidation, InboxSendOutcome } from "./types.js";
 export interface MillionSendOptions {
     /**
      * Your MillionSend instance URL (no trailing slash needed). Falls back to
@@ -21,7 +21,7 @@ export interface MillionSendOptions {
     allowInsecureHttp?: boolean;
 }
 export interface RequestOptions {
-    /** POST-only idempotency key (emails.send, batch.send). */
+    /** POST-only idempotency key (emails.send, batch.send, replies, forwards, drafts.send). */
     idempotencyKey?: string;
 }
 export interface BatchRequestOptions extends RequestOptions {
@@ -48,7 +48,14 @@ export declare class HttpClient {
     private readonly timeoutMs;
     private readonly userAgent;
     constructor(apiKey: string, options?: MillionSendOptions);
-    request<T>({ method, path, body, query, idempotencyKey, headers: extraHeaders, }: DoRequest): Promise<Result<T>>;
+    request<T>(req: DoRequest): Promise<Result<T>>;
+    /**
+     * A send a person may have to approve (replies, forwards, drafts.send): an
+     * HTTP 202 answer is the draft the API held for approval, any other success
+     * the sent email.
+     */
+    requestOutcome<T>(req: DoRequest): Promise<Result<InboxSendOutcome<T>>>;
+    private call;
 }
 export {};
 //# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,MAAM,EAAmB,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMlD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED,UAAU,SAAS;IACjB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IAChE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CAC1D;AA0BD,qBAAa,UAAU;;IAErB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IA2BtD,OAAO,CAAC,CAAC,EAAE,EACf,MAAM,EACN,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,cAAc,EACd,OAAO,EAAE,YAAY,GACtB,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;CA6ClC"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,MAAM,EAAmB,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAS,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAQ3E,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED,UAAU,SAAS;IACjB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IAChE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CAC1D;AA2CD,qBAAa,UAAU;;IAErB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IA4BtD,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAIpD;;;;OAIG;IACG,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;YAU/D,IAAI;CAqEnB"}

package/dist/http.js

@@ -1,7 +1,9 @@
 import { toErrorResponse } from "./error.js";
 const DEFAULT_BASE_URL = "https://api.millionsend.com";
 const DEFAULT_TIMEOUT_MS = 30_000;
-const SDK_VERSION = "0.6.0";
+/** Time a long-poll answer may take to arrive after the server's own `wait` deadline. */
+const LONG_POLL_MARGIN_MS = 10_000;
+const SDK_VERSION = "0.9.0";
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 /** True for an `http://` URL whose host is not loopback. Unparseable URLs are left to fetch. */
 function isInsecureHttpUrl(url) {
@@ -16,6 +18,21 @@ function isInsecureHttpUrl(url) {
         return false;
     return !LOOPBACK_HOSTS.has(parsed.hostname) && !parsed.hostname.startsWith("127.");
 }
+/**
+ * Whether a path has an empty, "." or ".." segment: URL normalization
+ * resolves those away, so an id such as ".." would send the request to
+ * another resource (DELETE /inboxes/{id}/labels/.. deletes the inbox).
+ */
+function hasDotSegment(path) {
+    return path
+        .split("/")
+        .slice(1)
+        .some((segment) => segment === "" || segment === "." || segment === "..");
+}
+/** `retry-after` in seconds; null when absent or not a whole number of seconds (the API sends only those). */
+function retryAfterSeconds(header) {
+    return header !== null && /^\s*\d+\s*$/.test(header) ? Number(header) : null;
+}
 function queryString(query) {
     if (!query)
         return "";
@@ -35,7 +52,9 @@ export class HttpClient {
     userAgent;
     constructor(apiKey, options = {}) {
         this.#apiKey = apiKey;
-        this.baseUrl = (options.baseUrl ?? process.env.MILLIONSEND_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.baseUrl = (options.baseUrl ??
+            process.env.MILLIONSEND_BASE_URL ??
+            DEFAULT_BASE_URL).replace(/\/+$/, "");
         if (!options.allowInsecureHttp && isInsecureHttpUrl(this.baseUrl)) {
             throw new Error(`Refusing to send the API key over plain http to ${this.baseUrl}. Use https, or set allowInsecureHttp: true.`);
         }
@@ -52,7 +71,33 @@ export class HttpClient {
         const base = `millionsend-node/${SDK_VERSION}`;
         this.userAgent = options.userAgent ? `${base} ${options.userAgent}` : base;
     }
-    async request({ method, path, body, query, idempotencyKey, headers: extraHeaders, }) {
+    async request(req) {
+        return (await this.call(req)).result;
+    }
+    /**
+     * A send a person may have to approve (replies, forwards, drafts.send): an
+     * HTTP 202 answer is the draft the API held for approval, any other success
+     * the sent email.
+     */
+    async requestOutcome(req) {
+        const { status, result } = await this.call(req);
+        if (result.error)
+            return result;
+        const data = status === 202
+            ? { kind: "draft", draft: result.data }
+            : { kind: "sent", email: result.data };
+        return { data, error: null };
+    }
+    async call({ method, path, body, query, idempotencyKey, headers: extraHeaders, }) {
+        if (hasDotSegment(path)) {
+            const error = {
+                name: "validation_error",
+                message: 'An id in the request path is empty, "." or "..".',
+                statusCode: null,
+                retryAfter: null,
+            };
+            return { status: null, result: { data: null, error } };
+        }
         const url = `${this.baseUrl}${path}${queryString(query)}`;
         const headers = {
             Authorization: `Bearer ${this.#apiKey}`,
@@ -63,7 +108,11 @@ export class HttpClient {
             if (value !== undefined)
                 headers[key] = value;
         }
-        const init = { method, headers, signal: AbortSignal.timeout(this.timeoutMs) };
+        // A `wait` query asks the API to hold its answer up to that many seconds
+        // (long-poll), so the deadline has to outlast it.
+        const wait = Number(query?.wait ?? 0);
+        const timeoutMs = wait > 0 ? Math.max(this.timeoutMs, wait * 1000 + LONG_POLL_MARGIN_MS) : this.timeoutMs;
+        const init = { method, headers, signal: AbortSignal.timeout(timeoutMs) };
         if (body !== undefined && method !== "GET" && method !== "DELETE") {
             headers["Content-Type"] = "application/json";
             init.body = JSON.stringify(body);
@@ -80,8 +129,9 @@ export class HttpClient {
                 name: "application_error",
                 message: cause instanceof Error ? cause.message : String(cause),
                 statusCode: null,
+                retryAfter: null,
             };
-            return { data: null, error };
+            return { status: null, result: { data: null, error } };
         }
         const text = await response.text();
         let parsed = null;
@@ -93,10 +143,12 @@ export class HttpClient {
                 parsed = text;
             }
         }
+        const status = response.status;
         if (!response.ok) {
-            return { data: null, error: toErrorResponse(parsed, response.status) };
+            const retryAfter = retryAfterSeconds(response.headers.get("retry-after"));
+            return { status, result: { data: null, error: toErrorResponse(parsed, status, retryAfter) } };
         }
-        return { data: parsed, error: null };
+        return { status, result: { data: parsed, error: null } };
     }
 }
 //# sourceMappingURL=http.js.map