shipmail 0.2.2__tar.gz → 0.2.3__tar.gz

{shipmail-0.2.2 → shipmail-0.2.3}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.3](https://github.com/jcoulaud/ShipMail/compare/shipmail-python-v0.2.2...shipmail-python-v0.2.3) (2026-07-20)
+
+
+### Features
+
+* **api:** add agent-safe reply queue workflows ([#890](https://github.com/jcoulaud/ShipMail/issues/890)) ([62dd211](https://github.com/jcoulaud/ShipMail/commit/62dd2118cd68b27dfb6481cb20cb35b98913ad97))
+
 ## [0.2.2](https://github.com/jcoulaud/ShipMail/compare/shipmail-python-v0.2.1...shipmail-python-v0.2.2) (2026-07-19)
 
 

{shipmail-0.2.2 → shipmail-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shipmail
-Version: 0.2.2
+Version: 0.2.3
 Summary: Official Python SDK for the ShipMail API
 Project-URL: Homepage, https://shipmail.to
 Project-URL: Documentation, https://shipmail.to/docs/sdks/python
@@ -135,6 +135,20 @@ rules = client.mailboxes.get_rules("mbx_...")
 rules = client.mailboxes.update_rules("mbx_...", {"rules": rules["rules"]})
 updated = client.mailboxes.update_spam_filter("mbx_...", {"threshold": 8})
 client.mailboxes.delete("mbx_...")
+
+mailbox_id = "550e8400-e29b-41d4-a716-446655440000"
+queue = client.mailboxes.list_inbox_threads(mailbox_id, {
+    "reply_state": "needs_reply",
+    "after": "2025-07-20T00:00:00.000Z",
+})
+candidate = queue["data"][0]
+draft = client.mailboxes.create_inbox_reply_draft(
+    mailbox_id,
+    candidate["thread_id"],
+    {"text": "Thanks for the note.", "expected_reply_version": candidate["reply_version"]},
+)
+# Apply your approval policy first. Stale versions fail with 409 without delivery.
+client.mailboxes.send_inbox_reply_draft(mailbox_id, candidate["thread_id"], draft["id"])
 ```
 
 ### Messages
@@ -184,6 +198,23 @@ reply = client.threads.reply(threads["data"][0]["id"], {
 })
 ```
 
+### Reply scans
+
+Use a durable, atomically captured scan for a historical window, then page every result using the
+opaque cursor unchanged. Creation returns the completed snapshot; retry a `409` with bounded
+backoff while historical header classification finishes. Scans are retained for 30 days.
+
+```python
+from datetime import datetime, timedelta, timezone
+
+scan = client.reply_scans.create({
+    "mailbox_ids": ["550e8400-e29b-41d4-a716-446655440000"],
+    "after": (datetime.now(timezone.utc) - timedelta(days=365)).isoformat(),
+})
+results = client.reply_scans.list_results(scan["id"], {"limit": 100})
+print(results["data"])
+```
+
 ### Audiences
 
 ```python
@@ -349,6 +380,9 @@ if page["pagination"]["has_more"]:
     })
 ```
 
+Cursors are opaque and operation-specific. Never parse, modify, or fabricate them. Inbox and reply
+queue cursors are bound to their mailbox, time window, sort, and filters.
+
 Auto-pagination iterates through all pages automatically:
 
 ```python

{shipmail-0.2.2 → shipmail-0.2.3}/README.md

@@ -108,6 +108,20 @@ rules = client.mailboxes.get_rules("mbx_...")
 rules = client.mailboxes.update_rules("mbx_...", {"rules": rules["rules"]})
 updated = client.mailboxes.update_spam_filter("mbx_...", {"threshold": 8})
 client.mailboxes.delete("mbx_...")
+
+mailbox_id = "550e8400-e29b-41d4-a716-446655440000"
+queue = client.mailboxes.list_inbox_threads(mailbox_id, {
+    "reply_state": "needs_reply",
+    "after": "2025-07-20T00:00:00.000Z",
+})
+candidate = queue["data"][0]
+draft = client.mailboxes.create_inbox_reply_draft(
+    mailbox_id,
+    candidate["thread_id"],
+    {"text": "Thanks for the note.", "expected_reply_version": candidate["reply_version"]},
+)
+# Apply your approval policy first. Stale versions fail with 409 without delivery.
+client.mailboxes.send_inbox_reply_draft(mailbox_id, candidate["thread_id"], draft["id"])
 ```
 
 ### Messages
@@ -157,6 +171,23 @@ reply = client.threads.reply(threads["data"][0]["id"], {
 })
 ```
 
+### Reply scans
+
+Use a durable, atomically captured scan for a historical window, then page every result using the
+opaque cursor unchanged. Creation returns the completed snapshot; retry a `409` with bounded
+backoff while historical header classification finishes. Scans are retained for 30 days.
+
+```python
+from datetime import datetime, timedelta, timezone
+
+scan = client.reply_scans.create({
+    "mailbox_ids": ["550e8400-e29b-41d4-a716-446655440000"],
+    "after": (datetime.now(timezone.utc) - timedelta(days=365)).isoformat(),
+})
+results = client.reply_scans.list_results(scan["id"], {"limit": 100})
+print(results["data"])
+```
+
 ### Audiences
 
 ```python
@@ -322,6 +353,9 @@ if page["pagination"]["has_more"]:
     })
 ```
 
+Cursors are opaque and operation-specific. Never parse, modify, or fabricate them. Inbox and reply
+queue cursors are bound to their mailbox, time window, sort, and filters.
+
 Auto-pagination iterates through all pages automatically:
 
 ```python

{shipmail-0.2.2 → shipmail-0.2.3}/shipmail/__init__.py

@@ -45,6 +45,7 @@ from ._types import (
     CreateDomainParams,
     CreatedPartnerOrganization,
     CreateImportUploadParams,
+    CreateInboxReplyDraftParams,
     CreateMailboxAppPasswordParams,
     CreateMailboxFolderParams,
     CreateMailboxImportParams,
@@ -52,6 +53,7 @@ from ._types import (
     CreateNewsletterFromChangelogParams,
     CreateNewsletterParams,
     CreatePartnerOrganizationParams,
+    CreateReplyScanParams,
     CreateWebhookParams,
     DataMode,
     DeleteCalendarEventParams,
@@ -81,7 +83,13 @@ from ._types import (
     InboxMessage,
     InboxMessageAction,
     InboxMessages,
+    InboxReplyDraft,
+    InboxReplyDraftSend,
     InboxThread,
+    InboxThreadReplyState,
+    InboxThreadReplyStateResult,
+    InboxThreads,
+    InboxThreadSummary,
     InjectSandboxInboundParams,
     ListAudiencesParams,
     ListBookingPagesParams,
@@ -89,11 +97,13 @@ from ._types import (
     ListDeliveriesParams,
     ListDomainsParams,
     ListInboxMessagesParams,
+    ListInboxThreadsParams,
     ListMailboxesParams,
     ListMessagesParams,
     ListNewsletterAssetsParams,
     ListNewsletterDomainsParams,
     ListNewslettersParams,
+    ListReplyScanResultsParams,
     ListSubscribersParams,
     ListSuppressionsParams,
     ListThreadsParams,
@@ -139,7 +149,6 @@ from ._types import (
     MessageSource,
     MessageStatus,
     MethodOptions,
-    OneTimeSecretMethodOptions,
     MoveInboxMessageParams,
     Newsletter,
     NewsletterArchiveVisibility,
@@ -186,6 +195,7 @@ from ._types import (
     NewsletterUrlBreakdown,
     NewsletterUrlSource,
     NewsletterVideoBlock,
+    OneTimeSecretMethodOptions,
     OutboundHeader,
     PaginatedResponse,
     PaginationParams,
@@ -205,6 +215,10 @@ from ._types import (
     RegisterNewsletterAssetFromUrlParams,
     RegistrationContact,
     Reminder,
+    ReplyScan,
+    ReplyScanCandidate,
+    ReplyScanResults,
+    ReplyScanStatus,
     ReplyToMessageParams,
     ReplyToThreadParams,
     ResetMailboxPasswordParams,
@@ -229,6 +243,7 @@ from ._types import (
     UpdateCalendarEventParams,
     UpdateDomainParams,
     UpdateInboxMessageParams,
+    UpdateInboxThreadReplyStateParams,
     UpdateMailboxFolderParams,
     UpdateMailboxParams,
     UpdateMailboxRulesParams,
@@ -321,6 +336,8 @@ __all__ = [
     "UpdateSubscriberParams",
     "CreateDomainParams",
     "CreatedMailboxAppPassword",
+    "CreateInboxReplyDraftParams",
+    "CreateReplyScanParams",
     "CreateMailboxAppPasswordParams",
     "CreateImportUploadParams",
     "CreateMailboxFolderParams",
@@ -357,10 +374,18 @@ __all__ = [
     "InboxMessage",
     "InboxMessageAction",
     "InboxMessages",
+    "InboxReplyDraft",
+    "InboxReplyDraftSend",
     "InboxThread",
+    "InboxThreadReplyState",
+    "InboxThreadReplyStateResult",
+    "InboxThreadSummary",
+    "InboxThreads",
     "ListDeliveriesParams",
     "ListDomainsParams",
     "ListInboxMessagesParams",
+    "ListInboxThreadsParams",
+    "ListReplyScanResultsParams",
     "ListMailboxesParams",
     "ListMessagesParams",
     "ListNewsletterAssetsParams",
@@ -472,6 +497,10 @@ __all__ = [
     "RegistrationContact",
     "ResetMailboxPasswordParams",
     "ReplyToMessageParams",
+    "ReplyScan",
+    "ReplyScanCandidate",
+    "ReplyScanResults",
+    "ReplyScanStatus",
     "ReplyToThreadParams",
     "RotateSecretResponse",
     "ScheduleNewsletterParams",
@@ -485,6 +514,7 @@ __all__ = [
     "Thread",
     "RegisterNewsletterAssetFromUrlParams",
     "UpdateInboxMessageParams",
+    "UpdateInboxThreadReplyStateParams",
     "UpdateDomainParams",
     "UpdateMailboxFolderParams",
     "UpdateMailboxRulesParams",

{shipmail-0.2.2 → shipmail-0.2.3}/shipmail/_client.py

@@ -23,6 +23,7 @@ from .resources.mailboxes import AsyncMailboxes, SyncMailboxes
 from .resources.messages import AsyncMessages, SyncMessages
 from .resources.newsletters import AsyncNewsletters, SyncNewsletters
 from .resources.partner import AsyncPartner, SyncPartner
+from .resources.reply_scans import AsyncReplyScans, SyncReplyScans
 from .resources.status import AsyncStatus, SyncStatus
 from .resources.suppressions import AsyncSuppressions, SyncSuppressions
 from .resources.threads import AsyncThreads, SyncThreads
@@ -40,6 +41,7 @@ class ShipMail(BaseClient):
     messages: SyncMessages
     newsletters: SyncNewsletters
     partner: SyncPartner
+    reply_scans: SyncReplyScans
     suppressions: SyncSuppressions
     threads: SyncThreads
     webhooks: SyncWebhooks
@@ -75,6 +77,7 @@ class ShipMail(BaseClient):
         self.messages = SyncMessages(self)
         self.newsletters = SyncNewsletters(self)
         self.partner = SyncPartner(self)
+        self.reply_scans = SyncReplyScans(self)
         self.suppressions = SyncSuppressions(self)
         self.threads = SyncThreads(self)
         self.webhooks = SyncWebhooks(self)
@@ -225,6 +228,7 @@ class AsyncShipMail(BaseClient):
     messages: AsyncMessages
     newsletters: AsyncNewsletters
     partner: AsyncPartner
+    reply_scans: AsyncReplyScans
     suppressions: AsyncSuppressions
     threads: AsyncThreads
     webhooks: AsyncWebhooks
@@ -260,6 +264,7 @@ class AsyncShipMail(BaseClient):
         self.messages = AsyncMessages(self)
         self.newsletters = AsyncNewsletters(self)
         self.partner = AsyncPartner(self)
+        self.reply_scans = AsyncReplyScans(self)
         self.suppressions = AsyncSuppressions(self)
         self.threads = AsyncThreads(self)
         self.webhooks = AsyncWebhooks(self)

{shipmail-0.2.2 → shipmail-0.2.3}/shipmail/_types/__init__.py

@@ -95,6 +95,7 @@ from .mailbox import (
     AutoReply,
     CreatedMailboxAppPassword,
     CreateImportUploadParams,
+    CreateInboxReplyDraftParams,
     CreateMailboxAppPasswordParams,
     CreateMailboxFolderParams,
     CreateMailboxForwardingParams,
@@ -111,8 +112,15 @@ from .mailbox import (
     InboxMessage,
     InboxMessageAction,
     InboxMessages,
+    InboxReplyDraft,
+    InboxReplyDraftSend,
     InboxThread,
+    InboxThreadReplyState,
+    InboxThreadReplyStateResult,
+    InboxThreads,
+    InboxThreadSummary,
     ListInboxMessagesParams,
+    ListInboxThreadsParams,
     ListMailboxesParams,
     Mailbox,
     MailboxAppPassword,
@@ -156,6 +164,7 @@ from .mailbox import (
     ResetMailboxPasswordParams,
     UpdateAutoReplyParams,
     UpdateInboxMessageParams,
+    UpdateInboxThreadReplyStateParams,
     UpdateMailboxFolderParams,
     UpdateMailboxParams,
     UpdateMailboxRulesParams,
@@ -243,6 +252,14 @@ from .partner import (
     PartnerUsage,
     UpdatePartnerOrganizationParams,
 )
+from .reply_scan import (
+    CreateReplyScanParams,
+    ListReplyScanResultsParams,
+    ReplyScan,
+    ReplyScanCandidate,
+    ReplyScanResults,
+    ReplyScanStatus,
+)
 from .suppression import (
     ListSuppressionsParams,
     Suppression,
@@ -325,6 +342,8 @@ __all__ = [
     "CreateDomainParams",
     "AutoReply",
     "CreatedMailboxAppPassword",
+    "CreateInboxReplyDraftParams",
+    "CreateReplyScanParams",
     "CreateMailboxAppPasswordParams",
     "CreateImportUploadParams",
     "CreateMailboxFolderParams",
@@ -360,10 +379,18 @@ __all__ = [
     "InboxMessage",
     "InboxMessageAction",
     "InboxMessages",
+    "InboxReplyDraft",
+    "InboxReplyDraftSend",
     "InboxThread",
+    "InboxThreadReplyState",
+    "InboxThreadReplyStateResult",
+    "InboxThreadSummary",
+    "InboxThreads",
     "ListDeliveriesParams",
     "ListDomainsParams",
     "ListInboxMessagesParams",
+    "ListInboxThreadsParams",
+    "ListReplyScanResultsParams",
     "ListMailboxesParams",
     "ListMessagesParams",
     "ListNewsletterAssetsParams",
@@ -482,6 +509,10 @@ __all__ = [
     "RegistrationContact",
     "ResetMailboxPasswordParams",
     "ReplyToMessageParams",
+    "ReplyScan",
+    "ReplyScanCandidate",
+    "ReplyScanResults",
+    "ReplyScanStatus",
     "ReplyToThreadParams",
     "RotateSecretResponse",
     "ScheduleNewsletterParams",
@@ -495,6 +526,7 @@ __all__ = [
     "Thread",
     "RegisterNewsletterAssetFromUrlParams",
     "UpdateInboxMessageParams",
+    "UpdateInboxThreadReplyStateParams",
     "UpdateDomainParams",
     "UpdateAutoReplyParams",
     "UpdateMailboxFolderParams",

{shipmail-0.2.2 → shipmail-0.2.3}/shipmail/_types/common.py

@@ -43,8 +43,8 @@ MessageStatus = Literal[
     "cancelled",
 ]
 
-MESSAGE_SOURCES = ("api", "newsletter", "dashboard", "inbound", "smtp")
-MessageSource = Literal["api", "newsletter", "dashboard", "inbound", "smtp"]
+MESSAGE_SOURCES = ("api", "newsletter", "dashboard", "inbound", "smtp", "agent")
+MessageSource = Literal["api", "newsletter", "dashboard", "inbound", "smtp", "agent"]
 
 WEBHOOK_EVENT_TYPES = (
     "message.received",
@@ -52,6 +52,7 @@ WEBHOOK_EVENT_TYPES = (
     "message.delivered",
     "message.bounced",
     "message.complained",
+    "thread.needs_reply",
     "mailbox.rule_matched",
     "domain.verified",
     "domain.verification_failed",
@@ -67,6 +68,7 @@ WebhookEventType = Literal[
     "message.delivered",
     "message.bounced",
     "message.complained",
+    "thread.needs_reply",
     "mailbox.rule_matched",
     "domain.verified",
     "domain.verification_failed",
@@ -85,6 +87,7 @@ WebhookDeliveryEventType = Literal[
     "message.delivered",
     "message.bounced",
     "message.complained",
+    "thread.needs_reply",
     "mailbox.rule_matched",
     "domain.verified",
     "domain.verification_failed",

{shipmail-0.2.2 → shipmail-0.2.3}/shipmail/_types/mailbox.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import Literal, TypedDict
 
 from .common import PaginationParams
+from .message import Message
 
 
 class AutoReply(TypedDict):
@@ -198,12 +199,11 @@ InboxFullMessage = TypedDict(
 )
 
 
-class InboxPositionPagination(TypedDict):
-    position: int
+class InboxCursorPagination(TypedDict):
     limit: int
     total: int
     has_more: bool
-    next_position: int | None
+    next_cursor: str | None
 
 
 class InboxMessages(TypedDict):
@@ -211,7 +211,77 @@ class InboxMessages(TypedDict):
     mailbox_id: str
     address: str
     data: list[InboxFullMessage]
-    pagination: InboxPositionPagination
+    pagination: InboxCursorPagination
+
+
+InboxThreadReplyState = Literal["needs_reply", "waiting_on_contact", "resolved", "no_reply_expected"]
+
+
+class InboxThreadSummary(TypedDict):
+    object: Literal["inbox_thread_summary"]
+    id: str
+    thread_id: str
+    reply_state: InboxThreadReplyState
+    reply_version: int
+    needs_reply_since: str | None
+    subject: str | None
+    latest_from_address: str | None
+    message_count: int
+    first_message_at: str
+    last_message_at: str
+    latest_message_id: str | None
+    latest_email_id: str | None
+    latest_inbound_message_id: str | None
+    latest_inbound_email_id: str | None
+    latest_inbound_at: str | None
+    latest_outbound_message_id: str | None
+    latest_outbound_email_id: str | None
+    latest_outbound_at: str | None
+
+
+class InboxThreadsPagination(TypedDict):
+    limit: int
+    has_more: bool
+    next_cursor: str | None
+    snapshot_at: str
+
+
+class InboxThreads(TypedDict):
+    object: Literal["inbox_threads"]
+    mailbox_id: str
+    data: list[InboxThreadSummary]
+    summary: dict[InboxThreadReplyState, int]
+    pagination: InboxThreadsPagination
+
+
+class InboxThreadReplyStateResult(TypedDict):
+    object: Literal["inbox_thread_reply_state"]
+    id: str
+    thread_id: str
+    reply_state: InboxThreadReplyState
+    reply_version: int
+    needs_reply_since: str | None
+
+
+class InboxReplyDraft(TypedDict):
+    object: Literal["inbox_reply_draft"]
+    id: str
+    mailbox_id: str
+    thread_id: str
+    based_on_message_id: str | None
+    expected_reply_version: int
+    reply_mode: Literal["reply", "reply_all"]
+    status: Literal["draft", "sending", "sent", "invalidated", "failed"]
+    to: list[dict[str, str | None]]
+    cc: list[dict[str, str | None]]
+    created_at: str
+
+
+class InboxReplyDraftSend(TypedDict):
+    object: Literal["inbox_reply_draft_send"]
+    draft_id: str
+    status: Literal["draft", "sending", "sent", "invalidated", "failed"]
+    message: Message
 
 
 class InboxThread(TypedDict):
@@ -373,12 +443,39 @@ class ListInboxMessagesParams(TypedDict, total=False):
     folder_id: str
     folder_role: Literal["inbox", "starred", "sent", "drafts", "archive", "junk", "trash"]
     search_text: str
-    position: int
+    cursor: str
+    after: str
+    before: str
     limit: int
     has_keyword: InboxKeyword
     not_keyword: InboxKeyword
 
 
+class ListInboxThreadsParams(TypedDict, total=False):
+    reply_state: InboxThreadReplyState
+    sort_by: Literal["needs_reply_since", "last_message_at"]
+    order: Literal["asc", "desc"]
+    after: str
+    before: str
+    cursor: str
+    limit: int
+
+
+class _CreateInboxReplyDraftParamsRequired(TypedDict):
+    expected_reply_version: int
+
+
+class CreateInboxReplyDraftParams(_CreateInboxReplyDraftParamsRequired, total=False):
+    text: str
+    html: str
+    reply_mode: Literal["reply", "reply_all"]
+
+
+class UpdateInboxThreadReplyStateParams(TypedDict):
+    reply_state: Literal["needs_reply", "resolved", "no_reply_expected"]
+    expected_reply_version: int
+
+
 class _DownloadInboxAttachmentParamsRequired(TypedDict):
     blob_id: str
 

shipmail-0.2.3/shipmail/_types/reply_scan.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+ReplyScanStatus = Literal["completed"]
+
+
+class ReplyScan(TypedDict):
+    object: Literal["reply_scan"]
+    id: str
+    mailbox_ids: list[str]
+    after: str
+    before: str
+    snapshot_at: str
+    status: ReplyScanStatus
+    candidate_count: int
+    completed_at: str
+    created_at: str
+
+
+class ReplyScanCandidate(TypedDict):
+    object: Literal["reply_scan_candidate"]
+    id: str
+    mailbox_id: str
+    thread_id: str
+    tracked_thread_id: str
+    latest_message_id: str | None
+    latest_email_id: str | None
+    latest_inbound_message_id: str | None
+    latest_inbound_email_id: str | None
+    reply_version: int
+    needs_reply_since: str
+    subject: str | None
+
+
+class ReplyScanResultsPagination(TypedDict):
+    limit: int
+    has_more: bool
+    next_cursor: str | None
+
+
+class ReplyScanResults(TypedDict):
+    object: Literal["reply_scan_results"]
+    scan_id: str
+    data: list[ReplyScanCandidate]
+    pagination: ReplyScanResultsPagination
+
+
+class _CreateReplyScanParamsRequired(TypedDict):
+    mailbox_ids: list[str]
+    after: str
+
+
+class CreateReplyScanParams(_CreateReplyScanParamsRequired, total=False):
+    before: str
+
+
+class ListReplyScanResultsParams(TypedDict, total=False):
+    cursor: str
+    limit: int

{shipmail-0.2.2 → shipmail-0.2.3}/shipmail/_types/webhook.py

@@ -80,7 +80,7 @@ class ListDeliveriesParams(PaginationParams, total=False):
 
 
 class WebhookEvent(TypedDict):
-    version: Literal["2026-07-12"]
+    version: Literal["2026-07-20"]
     event_id: str
     event_type: WebhookEventType
     created_at: str

shipmail-0.2.3/shipmail/_version.py

@@ -0,0 +1 @@
+VERSION = "0.2.3"  # x-release-please-version

{shipmail-0.2.2 → shipmail-0.2.3}/shipmail/resources/__init__.py

@@ -1,6 +1,7 @@
 from .booking_page import AsyncBookingPages, SyncBookingPages
 from .calendar import AsyncCalendar, AsyncCalendarEvents, SyncCalendar, SyncCalendarEvents
 from .partner import AsyncPartner, SyncPartner
+from .reply_scans import AsyncReplyScans, SyncReplyScans
 
 __all__ = [
     "AsyncBookingPages",
@@ -10,5 +11,7 @@ __all__ = [
     "SyncCalendar",
     "SyncCalendarEvents",
     "AsyncPartner",
+    "AsyncReplyScans",
     "SyncPartner",
+    "SyncReplyScans",
 ]