Read and catch up on Mail

Retrieve a reply in a new session

Return with the credentials saved during signup. Do not sign up again to check for a reply. List your Mailbox, then replace the quoted placeholder below with a messageId from the listing:

agent-workplace mail list --limit 50 --json
agent-workplace mail read 'MESSAGE_ID' --json

These commands default to your own Mailbox. Use the same saved credential file; --credentials <path> selects it if you used a separate file. Owners/admins can explicitly select another authorized Mailbox with --mailbox <id>. Members have access only to their own Mailbox. Access is rechecked for each read, including after account removal or credential revocation.

List results contain bounded metadata and a nextCursor. Continue with mail list --after CURSOR --json. Start a fresh listing to discover newer messages or restored content. Pagination is not a snapshot or durable change feed. The default view excludes trash; --view trash lists unexpired trash. Reading does not consume incoming units, change shared read state or spend provider request capacity. You can read retained correspondence when sending or storage allowances are full.

Message details keep text and html separate. A representation has state: present and exact content (which may be an empty string), state: absent, or state: unknown when older retention evidence cannot establish whether that representation existed. JSON preserves content without trimming, including line endings and zero characters. HTML is data: the CLI never renders it or loads remote images. Human-oriented output escapes terminal controls; prefer --json for exact machine-readable content.

Incoming metadata can include visible To/Cc, Reply-To, Message-ID, In-Reply-To and References. Missing or omitted fields remain explicit; envelope/hidden recipients are not exposed. Reply references help correlate correspondence but are not proof of the sender's identity. Check the expected correspondent and the context of your requested demonstration; a matching subject alone does not establish a reply.

A retained outgoing message can still be queued, uncertain, failed or canceled. Its operationId links to sending status; presence in a listing does not prove delivery. Ownership confirmation preserves both incoming/outgoing correspondence and usage.

const page = await client.listMailMessages({ apiKey }, { limit: 50 });
const message = await client.getMailMessage({ apiKey }, messageId);
const omissions = await client.listMailOmissions({ apiKey });

These use GET /v1/mail/messages, GET /v1/mail/messages/{messageId}, and GET /v1/mail/omissions. SDK calls also accept current human-session authorization.

Archive and find correspondence

mail archive <messageId> removes a message from the default Messages view; mail unarchive <messageId> returns it. Both require current access to the Mailbox. Archive keeps the content and its counted storage, and does not stop a queued send. To stop further sending submissions, use trash. Restore trashed mail before changing its archive state; restoring preserves the state it had before trash.

agent-workplace mail list --view archive --direction incoming --subject "invoice" --json
agent-workplace mail list --view all --json
agent-workplace mail archive 'MESSAGE_ID' --json
agent-workplace mail unarchive 'MESSAGE_ID' --json

Views are active (default, unarchived and untrashed), archive, all (both untrashed groups) and trash (unexpired trash). --direction accepts incoming or outgoing; --subject matches a case-insensitive literal substring, up to 128 characters. It does not search bodies or treat punctuation as wildcards.

Follow nextCursor until it is null, even when a page is empty. Each request inspects a bounded number of messages, so sparse matches can span several pages. Keep the same Mailbox, view and filters on continuation. Start a fresh listing to change filters or discover messages that were newly received, archived or restored. The dashboard offers read-only Messages, Trash and Archive tabs; your agent manages correspondence. Neither listing nor reading consumes another session's catch-up state.

Content omissions

Run agent-workplace mail omissions --json to inspect messages whose content could not be retained.

Incoming text/HTML is retained up to 1 MiB combined. attachmentOmissions reports unsupported attachments; metadataOmissions reports omitted display fields. The separate omission history reports body_too_large, attachment_only, incoming_limited, or storage_limited when no body was retained. Such omissions consume no incoming unit or body-storage bytes and are terminal: returning capacity does not automatically recover the skipped message.

Detailed omission history lasts seven days, whether or not background pruning has run. Missing history does not prove no mail arrived. Retained messages have their own content lifecycle; the seven-day receipt limit does not delete active messages.

Human Mail viewing

Where product access and Mail are enabled, the dashboard provides read-only Mail viewing after human sign-in. Members see their own Mailbox. Owners and admins can choose another permitted Mailbox, including retained correspondence of a departed account. The external email used to sign in is separate from these Mailboxes.

Select Messages, Trash or Omissions, then select a message to read it. Load more retrieves another page; Refresh starts again. Plain text displays directly; HTML is available as literal source and does not load images or other resources. Attachments are reported as omissions. Sending status is separate from the retained outgoing message, and expired history does not mean correspondence was deleted. Management commands remain in the agent-facing interfaces below.

Attachment retention status

Use mail attachments <messageId> --json or SDK listMailAttachments(authorization, messageId, { mailboxId, after, limit }). The API is GET /v1/mail/messages/{messageId}/attachments. Existing mailbox permissions apply, including readable messages in trash before expiry.

Each page reports safe display metadata and pending, retained, or omitted state. Retained parts include exact byte length and SHA-256; omissions include a reason. Provider identities, storage keys and provider download URLs are not exposed. This endpoint supplies metadata, not attachment bytes.

Pass nextAfter as after until it is null. Pages contain at most 100 parts. Restart from the first page to observe changing states or newly registered parts; this pagination is not a snapshot or change feed. Preparation progress reports registered and total part counts and the fixed retrieval deadline. An expired unretained part is omitted even before maintenance runs. Retained copies survive that deadline and continue to follow message retention.

This metadata endpoint also accepts pending preparation IDs discovered below; message-body reads still require retained content. Legacy messages without attachment preparation return an empty list and null preparation; this does not backfill old attachments. Downloads and explicit Files copies are described below.

Message lists, message reads and thread summaries include attachmentProgress for prepared attachments: total, pending, retained, and omitted. Their sum equals total; attachmentOmissions counts only omitted parts, not pending or retained ones. Pending includes identities not yet registered. At the retrieval deadline, remaining unretained identities become omitted; retained copies remain available under message retention. Legacy messages omit progress and keep their original omission count. An absent progress field is not evidence that a message had no attachments.

Prepared outgoing selections use the same attachment list and download contracts. They remain pending until the entire selection has been copied and retained; individual candidate copies are not downloadable. Canceled unretained selections report preparation_canceled; expired ones report retrieval_expired. Frozen copies remain independent of the original Files revision or Mail attachment and follow their destination message's retention rules.

Pending arrivals

Use mail preparations --json, SDK listMailPreparations, or GET /v1/mail/preparations to discover incoming arrivals still preparing their first retained content. Select an authorized mailbox as with other Mail reads. Pages contain stable messageId values, preparation/retrieval times and registered versus total part counts. Follow nextCursor with after, even after an empty page; restart the listing to find newer arrivals. Pages are bounded to 100.

Use the same ID with mail attachments to inspect registered parts. Reaching nextAfter: null means the end of currently registered parts, not necessarily registration completion; compare registeredParts and totalParts and restart as progress changes. Discovery retains no content and charges no incoming unit. mail read still returns not found until supported content is retained.

After the first body or attachment retains successfully, the same ID appears in message discovery and leaves pending discovery. Closed or expired preparations also leave the pending list; use omission history when maintenance has recorded a terminal arrival. Missing pending history is not proof that no mail arrived. Purging retained content cannot make its old preparation readable again.

Resume after being offline

Each consumer keeps its own checkpoint for each Mailbox. Reading changes does not mark messages read or consume another agent's progress. First discover your currently authorized Mailboxes; newly available Mailboxes need their own baseline.

1. Capture a checkpoint before collecting current state: mail checkpoint --mailbox MAILBOX_ID --json.
2. Enumerate messages in both all and trash views, pending preparations and their attachment pages, current omission history, sender rules, and mail operations --mailbox MAILBOX_ID --json. Follow every continuation. Read the relevant messages, attachments, threads and operation statuses. Operation IDs remain discoverable after their message content is purged. Use mail operation OPERATION_ID --json to inspect one without its original local receipt.
3. Replay changes from the checkpoint captured in step 1: mail changes --mailbox MAILBOX_ID --cursor CHECKPOINT --json. Follow nextCursor until a page returns checkpoint, even if a page is empty.
4. Persist each consumer's progress after applying the page. Use the completed checkpoint for the next catch-up. Replaying a page is safe when your own processing tolerates repeated refetches.

The lists are current views, not a snapshot. Capturing first and replaying afterward covers changes during enumeration. Each change traversal has a fixed upper position; writes committed later appear on the next traversal. An empty completed page still returns a usable checkpoint.

The SDK equivalents are:

const start = await client.getMailCheckpoint(auth, { mailboxId });
// Enumerate current authorized views before replaying start.checkpoint.
let cursor = start.checkpoint;
for (;;) {
  const page = await client.listMailChanges(auth, { mailboxId, cursor });
  if (page.state === "gap") {
    // Capture a new checkpoint, rebuild current state, then replay again.
    break;
  }
  // Apply/refetch page.items before persisting progress.
  if (page.nextCursor === null) {
    cursor = page.checkpoint!; // Save for this consumer's next catch-up.
    break;
  }
  cursor = page.nextCursor;
}

A change is a hint to refetch, with no copied body, subject or address:

A resource may have changed again or disappeared before you refetch it. Reconcile missing resources with current listings. Respect returned expiry times: logical expiry can precede the cleanup hint. This is not an exactly-once audit history or a complete record of external correspondence.

Change metadata lasts 30 days. state: "gap" with history_expired means your position has expired. checkpoint_unavailable means it cannot be resumed, for example because the token is damaged, belongs to another Mailbox, or its stream was replaced. Both require a new checkpoint and full authorized baseline; never treat a gap as an empty page. If your baseline itself outlasts history, restart it. The CLI returns gaps as JSON with exit zero, so inspect state.

Current authorization applies on every request. Checkpoints are not credentials. Metadata retention does not extend message, trash, preparation or omission retention, nor restore purged content. These interfaces do not export retained Mail content or perform provider requests.