shipmail 0.2.1 → 0.2.3

package/README.md

@@ -20,6 +20,7 @@ Official TypeScript SDK for the [Shipmail](https://shipmail.to) API. Zero runtim
 - [Messages](#messages)
 - [Sandbox](#sandbox)
 - [Threads](#threads)
+- [Reply scans](#reply-scans)
 - [Webhooks](#webhooks)
 - [Suppressions](#suppressions)
 - [Audiences](#audiences)
@@ -170,6 +171,26 @@ await shipmail.mailboxes.updateAutoReply("mbx_...", {
   from_date: "2026-06-01",
   to_date: "2026-06-07",
 });
+
+const mailboxId = "550e8400-e29b-41d4-a716-446655440000";
+const inbox = await shipmail.mailboxes.listInboxMessages(mailboxId, {
+  after: "2025-07-20T00:00:00.000Z",
+  before: "2026-07-20T00:00:00.000Z",
+  limit: 50,
+});
+const exact = await shipmail.mailboxes.getInboxMessage(mailboxId, inbox.data[0].id);
+
+const queue = await shipmail.mailboxes.listInboxThreads(mailboxId, {
+  reply_state: "needs_reply",
+  after: "2025-07-20T00:00:00.000Z",
+});
+const candidate = queue.data[0];
+const draft = await shipmail.mailboxes.createInboxReplyDraft(mailboxId, candidate.thread_id, {
+  text: "Thanks for the note.",
+  expected_reply_version: candidate.reply_version,
+});
+// Apply your approval policy before sending. Stale versions fail with 409 without delivery.
+await shipmail.mailboxes.sendInboxReplyDraft(mailboxId, candidate.thread_id, draft.id);
 ```
 
 ## Messages
@@ -220,13 +241,30 @@ await testClient.mailboxes.injectSandboxInbound("mbx_...", {
 ```ts
 const threads = await shipmail.threads.list({ mailbox_id: "mbx_..." });
 const threadId = threads.data[0].id;
-const thread = await shipmail.threads.get(threadId);
+const thread = await shipmail.threads.get(threadId, { mailbox_id: "mbx_..." });
 
 await shipmail.threads.reply(threadId, {
+  mailbox_id: "mbx_...",
+  to: ["customer@example.com"],
   text: "Thanks for your email.",
 });
 ```
 
+## Reply scans
+
+Use a durable, atomically captured scan for a historical window. Creation returns a completed
+snapshot; retry a `409` with bounded backoff while historical classification finishes, then follow
+every opaque `next_cursor`; never parse or fabricate cursors. Scans are retained for 30 days.
+
+```ts
+const scan = await shipmail.replyScans.create({
+  mailbox_ids: ["550e8400-e29b-41d4-a716-446655440000"],
+  after: new Date(Date.now() - 365 * 86_400_000).toISOString(),
+});
+const results = await shipmail.replyScans.listResults(scan.id, { limit: 100 });
+console.log(results.data);
+```
+
 ## Webhooks
 
 ```ts
@@ -259,6 +297,7 @@ message.sent
 message.delivered
 message.bounced
 message.complained
+thread.needs_reply
 domain.verified
 domain.verification_failed
 domain.degraded
@@ -356,6 +395,8 @@ Preflight responses include `url_breakdown` so you can see which links, image
 URLs, and video thumbnails contribute to deliverability checks.
 Block prose fields are plain text in API requests. Use newlines for paragraph
 breaks, and use `body_html` or `custom_html` only when you need raw HTML.
+Concurrent newsletter updates can throw `ConflictError` (409). Fetch the latest
+newsletter, merge your changes, and retry the update.
 
 ## Partner beta
 
@@ -424,6 +465,10 @@ if (page.pagination.has_more) {
 }
 ```
 
+Cursors are opaque and operation-specific. Return them unchanged to the same operation. Inbox and
+reply-queue cursors are bound to their mailbox, time window, sort, and filters; omit those filters on
+later pages or repeat them exactly.
+
 Auto-paginate over all pages:
 
 ```ts

package/dist/index.cjs

@@ -624,7 +624,9 @@ var Mailboxes = class extends ApiResource {
         folder_id: params?.folder_id,
         folder_role: params?.folder_role,
         search_text: params?.search_text,
-        position: params?.position,
+        cursor: params?.cursor,
+        after: params?.after,
+        before: params?.before,
         limit: params?.limit,
         has_keyword: params?.has_keyword,
         not_keyword: params?.not_keyword
@@ -632,6 +634,29 @@ var Mailboxes = class extends ApiResource {
       methodOptions: options
     });
   }
+  getInboxMessage(id, messageId, options) {
+    return this.client.request({
+      method: "GET",
+      path: `/mailboxes/${encodeURIComponent(id)}/inbox/messages/${encodeURIComponent(messageId)}`,
+      methodOptions: options
+    });
+  }
+  listInboxThreads(id, params, options) {
+    return this.client.request({
+      method: "GET",
+      path: `/mailboxes/${encodeURIComponent(id)}/inbox/threads`,
+      query: {
+        reply_state: params?.reply_state,
+        sort_by: params?.sort_by,
+        order: params?.order,
+        after: params?.after,
+        before: params?.before,
+        cursor: params?.cursor,
+        limit: params?.limit
+      },
+      methodOptions: options
+    });
+  }
   getInboxThread(id, threadId, options) {
     return this.client.request({
       method: "GET",
@@ -639,6 +664,45 @@ var Mailboxes = class extends ApiResource {
       methodOptions: options
     });
   }
+  updateInboxThreadReplyState(id, threadId, params, options) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/mailboxes/${encodeURIComponent(id)}/inbox/threads/${encodeURIComponent(threadId)}`,
+      body: params,
+      methodOptions: options
+    });
+  }
+  createInboxReplyDraft(id, threadId, params, options) {
+    return this.client.request({
+      method: "POST",
+      path: `/mailboxes/${encodeURIComponent(id)}/inbox/threads/${encodeURIComponent(threadId)}/drafts`,
+      body: params,
+      methodOptions: options
+    });
+  }
+  sendInboxReplyDraft(id, threadId, draftId, options) {
+    return this.client.request({
+      method: "POST",
+      path: `/mailboxes/${encodeURIComponent(id)}/inbox/threads/${encodeURIComponent(threadId)}/drafts/${encodeURIComponent(draftId)}/send`,
+      methodOptions: options
+    });
+  }
+  replyToInboxMessage(id, messageId, params, options) {
+    return this.client.request({
+      method: "POST",
+      path: `/mailboxes/${encodeURIComponent(id)}/inbox/messages/${encodeURIComponent(messageId)}/reply`,
+      body: params,
+      methodOptions: options
+    });
+  }
+  replyToInboxThread(id, threadId, params, options) {
+    return this.client.request({
+      method: "POST",
+      path: `/mailboxes/${encodeURIComponent(id)}/inbox/threads/${encodeURIComponent(threadId)}/reply`,
+      body: params,
+      methodOptions: options
+    });
+  }
   updateInboxMessage(id, messageId, params, options) {
     return this.client.request({
       method: "PATCH",
@@ -1081,6 +1145,33 @@ var Partner = class extends ApiResource {
   }
 };
 
+// src/resources/reply-scans.ts
+var ReplyScans = class extends ApiResource {
+  create(params, options) {
+    return this.client.request({
+      method: "POST",
+      path: "/reply-scans",
+      body: params,
+      methodOptions: options
+    });
+  }
+  get(id, options) {
+    return this.client.request({
+      method: "GET",
+      path: `/reply-scans/${encodeURIComponent(id)}`,
+      methodOptions: options
+    });
+  }
+  listResults(id, params, options) {
+    return this.client.request({
+      method: "GET",
+      path: `/reply-scans/${encodeURIComponent(id)}/results`,
+      query: { cursor: params?.cursor, limit: params?.limit },
+      methodOptions: options
+    });
+  }
+};
+
 // src/resources/status.ts
 var Status = class extends ApiResource {
   get(options) {
@@ -1144,8 +1235,9 @@ var Threads = class extends ApiResource {
       method: "GET",
       path: `/threads/${encodeURIComponent(id)}`,
       query: {
-        cursor: params?.cursor,
-        limit: params?.limit
+        mailbox_id: params.mailbox_id,
+        cursor: params.cursor,
+        limit: params.limit
       },
       methodOptions: options
     });
@@ -1263,7 +1355,7 @@ var Webhooks = class extends ApiResource {
 };
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.2.3";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://shipmail.to/api/v1";
@@ -1324,6 +1416,7 @@ var ShipMailClient = class {
     this.messages = new Messages(this);
     this.newsletters = new Newsletters(this);
     this.partner = new Partner(this);
+    this.replyScans = new ReplyScans(this);
     this.suppressions = new Suppressions(this);
     this.threads = new Threads(this);
     this.webhooks = new Webhooks(this);
@@ -1434,6 +1527,7 @@ var WEBHOOK_EVENT_TYPES = [
   "message.delivered",
   "message.bounced",
   "message.complained",
+  "thread.needs_reply",
   "mailbox.rule_matched",
   "domain.verified",
   "domain.verification_failed",
@@ -1456,7 +1550,14 @@ var MESSAGE_STATUSES = [
   "suppressed",
   "cancelled"
 ];
-var MESSAGE_SOURCES = ["api", "newsletter", "dashboard", "inbound", "smtp"];
+var MESSAGE_SOURCES = [
+  "api",
+  "newsletter",
+  "dashboard",
+  "inbound",
+  "smtp",
+  "agent"
+];
 var WEBHOOK_DELIVERY_STATUSES = ["pending", "delivered", "failed"];
 
 // src/webhook-verification.ts