---
title: "Send an email"
method: POST
path: "/v1/mailboxes/{mailbox_id}/emails"
tags: ["Emails"]
---

# Send an email

`POST /v1/mailboxes/{mailbox_id}/emails`

## Request

- Base URL: `https://api.revdoku.com`
- URL: `https://api.revdoku.com/v1/mailboxes/{mailbox_id}/emails`
- Auth: HTTP bearer

Requires mailbox write permission. Send only to account members, to other mailboxes of the account, or (on paid plans) to addresses that emailed this mailbox and passed sender authentication. The From name is the mailbox title. Set in_reply_to to reply. Delivery is asynchronous: read delivery.status later. After an unknown result, list direction=sent before you send again.

## Path parameters

- `mailbox_id` string, required

## Request body

- SendEmailRequest
  - `to` string[]: Recipient addresses, one per item. With in_reply_to, the recipient defaults to the original sender only when that sender passed SPF or DMARC; otherwise pass to. To and cc together allow at most 10 addresses.
  - `cc` string[]: Carbon-copy addresses. Bcc is not supported.
  - `subject` string: Required without in_reply_to. Defaults to "Re: " plus the original subject.
  - `text` string, required: Plain-text body, up to 1 MiB.
  - `html` string: Optional HTML body, up to 1 MiB.
  - `in_reply_to` string: Received email ID to reply to. Sets the reply headers and subject, and links the reply to the conversation.
  - `attachment_ids` string[]: Existing file IDs in this mailbox to attach.
  - `account_id` string
  - `reason` string, nullable: Optional purpose for this action. AI agents should explain intentional reads and changes when known; omit when unknown. Do not include secrets, file contents, or transcripts.

## Response `202`

Accepted

- object
  - `success` true, required
  - `data` object, required
    - `email` EmailSummary, required
      - `subject` string, nullable
      - `from_addresses` DecodedEmailAddress[]: Parsed From authors in header order, retaining multiple authors. Empty when absent/unparseable. Display names are not identity keys.
        - `address` string, required
        - `name` string, nullable, required
      - `to_addresses` DecodedEmailAddress[]: Parsed To recipients in header order, with named groups flattened. Empty when absent/unparseable; not trusted delivery routing.
        - `address` string, required
        - `name` string, nullable, required
      - `cc_addresses` DecodedEmailAddress[]: Parsed Cc recipients in header order, with named groups flattened. Empty when absent/unparseable.
        - `address` string, required
        - `name` string, nullable, required
      - `reply_to_addresses` DecodedEmailAddress[]: Parsed Reply-To addresses in header order. Empty when absent/unparseable. Does not authorize sending a reply.
        - `address` string, required
        - `name` string, nullable, required
      - `message_id` string, nullable: Sender Message-ID without angle brackets, preserving case. Null when absent/unparseable/ambiguous; never the Revdoku delivery ID.
      - `in_reply_to` string[]: Ordered parent Message-IDs without angle brackets, preserving case. Empty when absent/unparseable; multiple parents are retained.
      - `references` string[]: Ordered References IDs without angle brackets, preserving case. Empty when absent/unparseable.
      - `delivered_to` string
      - `received_at` string, date-time, required: Receipt time. For sent emails, the time Revdoku accepted the send.
      - `body_status` 'complete' | 'empty' | 'truncated' | 'unavailable' | 'withheld'
      - `omitted_attachment_count` integer
      - `id` string, required
      - `conversation_id` string, required: Email ID that identifies the conversation. Replies are linked by email headers. Filter a list with conversation_id.
      - `direction` 'received' | 'sent', required: received for incoming email; sent for email sent from this mailbox.
      - `delivery` EmailDelivery: Present on sent emails only.
        - `status` 'queued' | 'sending' | 'sent' | 'failed' | 'uncertain', required: uncertain: the provider result is unknown. Do not send again before you check the sent list.
        - `recipients` object, required: Status for each recipient address: queued, sent, delivered, bounced, bounced_temporarily, complained or rejected.
      - `labels` EmailLabel[], required: Labels on the email files. When AI labels are on for the account, they add one built-in category label, such as Junk or Receipts, a few seconds after the email arrives, usually after the email.received event.
        - `id` string, required
        - `name` string, required
        - `color` 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'gray', required
      - `withheld` boolean, required: True means Revdoku hides the email's content from API keys and MCP: the subject, display names, sender address (except its domain), body and attachments. If labels includes the Junk label, the email is junk: skip it. Downloads of the email and its files return EMAIL_WITHHELD, and a person can review it in the dashboard. Otherwise AI labels have not checked it yet: keep its ID and read it again with getEmail / get_email after a few seconds. The read returns 503 EMAIL_LABELING_PENDING with Retry-After until the label is ready (at most about one minute). Do not drop a pending email.
      - `file_id` string: Included only with include_storage=true for file-browser integration.
      - `version_id` string: Included only with include_storage=true for file-browser integration.
      - `attachment_count` integer, required
      - `read` boolean, required
      - `read_at` string, date-time, nullable, required
      - `read_by` object, nullable, required
      - `read_by_api_key` object, nullable, required
      - `files` object: Included only with include_storage=true for file-browser integration.
        - `body_id` string, nullable, required
        - `original_id` string, nullable, required
        - `attachment_ids` string[], required
        - `directory` string: Storage folder containing this email, without a trailing slash.
      - `forwarding` EmailForwarding: Server-recorded member forwarding provenance. The original author is reported by the member, not independently authenticated. Absent for ordinary or unrecognized mail.
        - `method` string, required
        - `member_id` string, required
        - `member_email` string, required
        - `intake_account_id` string, required
        - `outer_from` string
        - `outer_subject` string
        - `outer_message_id` string
        - `original_date_raw` string
        - `original_sent_at` string
        - `attribution` 'member_forwarded', required
        - `parser_version` integer, required: Parser implementation used at intake; does not change the forwarding response shape.

## Other responses

- `default`: Request failed. See error.code. Any 429 or 503 response with Retry-After (for example 503 EMAIL_LABELING_PENDING or 503 EMAIL_INDEX_BUILDING): wait that many seconds, then try the read again. 429 EMAIL_SEND_RATE_LIMITED has no Retry-After. Never retry EMAIL_LOOP_DETECTED.

---

[API](https://skmtc.dev/revdoku/apis/revdoku-api.md) · [All operations](https://skmtc.dev/revdoku/apis/revdoku-api/llms.txt) · [OpenAPI document](https://skmtc.dev/revdoku/apis/revdoku-api/revisions/3ff4e2540a8b?raw)