Work with Mail attachments

Download a retained attachment

Use an attachment ID from mail attachments:

agent-workplace mail download MESSAGE_ID ATTACHMENT_ID --output ./attachment.bin --json

The parent directory must exist. The CLI downloads and verifies the exact length and SHA-256 before publishing a private file at your explicit destination. It never uses an email-supplied filename as a path and never overwrites an existing file. Failure leaves existing destinations unchanged. Retry an interrupted transfer using the same IDs and a new or absent destination; Mail parts are bounded to 10,000,000 bytes, and retries download the part again.

SDK downloadMailAttachment(authorization, { messageId, attachmentId, mailboxId }) returns verified bytes and metadata. Its output allocation is bounded by the 10,000,000-byte part limit; it rejects shortened, oversized or hash-mismatched responses. Downloads send neither product authorization headers nor cookies to storage and refuse redirects. Repeated reads do not charge another incoming unit.

For a custom transfer, getMailAttachmentDownloadGrant calls POST /v1/mail/messages/{messageId}/attachments/{attachmentId}/download and returns a 60-second bearer URL plus immutable length and digest. Keep that URL out of logs and shared output. Issuance and renewal check current mailbox authority and require a verified retained copy; pending or omitted parts cannot be downloaded. Revocation and purge block new grants; an already-issued URL is not recalled by account revocation and keeps its expiry. Purge can remove the underlying bytes before that URL expires. Retained copies can be read from unexpired trash and survive the preparation deadline. Downloaded copies cannot be recalled. The human Mail dashboard has no attachment download controls.

In the human dashboard, Preparing lists arrivals that do not yet have retained content. Select an arrival to inspect registered parts; refresh to discover changes. Once any content is retained, find that same message in Messages. Message details show attachment counts and paginated pending, retained, or omitted status. Filenames are displayed as text only. Status refreshes do not download bytes, and the end of a page does not prove retrieval is complete. Refresh Mail to update message-level counts; attachment refresh updates the selected part listing.

Copy an attachment into workplace Files

A copy becomes a separate workplace file, readable and editable by active workplace accounts under Files permissions. It consumes its own storage allowance; purging the message does not delete the file, and deleting the file does not delete the retained attachment. Choose the destination deliberately:

agent-workplace mail copy --message MESSAGE_ID --attachment ATTACHMENT_ID \
  --name chosen-name.pdf --operation ./private/copy.json --json

The operation directory must be private and owned by you. Use --parent FOLDER_ID for a new file in a folder. To create a revision of an existing file, replace --name with --file FILE_ID --expected-version VERSION_ID. The command never uses the email filename as a local path or destination name. --mailbox selects an explicitly authorized mailbox when needed.

Retry using the same private receipt, even after an interrupted or lost response:

agent-workplace mail copy --operation ./private/copy.json --json

Inspect the returned Files state: pending is unfinished, published identifies the new revision, and conflict/expiry/cancellation require an explicit decision. A retry preserves the original operation, target and one-hour admission deadline. Do not delete the receipt or choose a new operation merely because a response was lost. The receipt contains no credential, attachment bytes or temporary grants.

Recovery checks the destination before requesting more source bytes. A completed or fully uploaded copy can finish after the message is purged. An incomplete copy that still needs unavailable source bytes fails; it cannot reconstruct deleted content. A fresh source grant requires current Mail authority. Already downloaded bytes and valid grants retain their existing semantics; Files publication checks current Files authority. Transfer runs in your client, with at most one decimal 10 MB attachment per invocation; this is not a server-side background copy service.

SDK callers use copyMailAttachmentToFile(auth, { workplaceId, operationId, expiresAt, target, source: { messageId, attachmentId, mailboxId } }, saveIntent). The async callback must durably save the supplied immutable intent, bound to the API origin and account, before returning. If it fails, no Files admission occurs. Resume with resumeMailAttachmentFileCopy(auth, savedIntent) against the original origin/account; parseMailAttachmentFileCopyIntent validates a loaded record. Keep the same operation ID/deadline and inspect the returned Files status.

Direct HTTP clients compose the existing attachment download-grant endpoint with the Files upload workflow: verify Mail length/hash, persist an immutable Files upload request before admission, then upload and finalize using API-issued grants. Recover the destination first. There is no dedicated Mail-copy endpoint and no requirement to give clients provider credentials.