Organize messages & drafts

Change message state explicitly#

Reading a message does not mutate it. With email:manage, use received-mail operations to mark, star, move, label or trash owned message UUIDs. Bulk operations validate the entire selection and ownership before changing messages.

curl "$MAILAT_BASE_URL/api/v1/inbox/received/mark" \
  --request POST \
  --header "Authorization: Bearer $MAILAT_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"emailUuids":["REPLACE_WITH_MESSAGE_UUID"],"isRead":true}'

Manual moves to inbox, archive, spam, trash or dmarc-reports are retained. Automatic classification is not rerun merely because you moved a report. See the exact payloads and methods in the reference.

Labels and filters#

Use /inbox/labels for label resources and /inbox/filters for rules applied by SES ingestion. Label resources have UUIDs; message label arrays and filter actions use owned label names. Renames and deletion propagate to those usages.

The filter test endpoint previews a sample without modifying messages. Supported actions include labels, folder, star, read, archive and trash. Put forwarding or automatic replies in an external workflow. Review migrationWarning on old rules: unsupported legacy rules can be disabled rather than silently failing.

Attachments#

Transactional sends support attachments with name, MIME type, base64 content, optional disposition and cid. For compose, upload multipart identityId and file to /compose/attachments, then reference the returned blobId using the compose attachment schema.

Private attachment downloads require ownership of the parent message. Received attachments use /inbox/received/{uuid}/attachments/{attachmentUuid}. Treat filenames and content as untrusted and honor content type and size limits in your workflow.

Drafts, replies and forwards#

Use /compose/drafts to store a draft and the draft's ID/version when continuing it. Keep reply and forwarding context from /compose/reply/{id} or /compose/forward/{id}; the ID is the public SES mailbox UUID.

Submit through /compose/send with an Idempotency-Key. Map the reply context's from.email to the send request's fromEmail to retain the selected alias. Preserve inReplyTo, references, the selected authorized identity and permitted attachments so the outgoing message retains its conversation context. A new subject or unrelated draft should not accidentally reuse a previous send key.

Use the instance's Sent folder and send-status/webhook APIs to track the result. Legacy /inbox/emails, thread and mailbox operations marked JMAP require Stalwart and are not substitutes for these SES operations.