# email_send

Send Email

## Beschreibung

Sends an email from one of the caller's connected Gmail
accounts in this account. Covers five modes via
parameters — they're mutually exclusive:

- **New** (default): omit `reply_to_message_id`,
  `forward_of`, and `redirect_of`.
- **Reply**: set `reply_to_message_id` to an `emsg_…`. The
  subject is auto-prefixed with `Re:` if absent, threading
  headers (`In-Reply-To`, `References`) are populated, and
  the message stays in the original Gmail conversation.
  The original is auto-quoted below your body — write only
  your own reply, not the citation.
- **Reply-all**: same as reply, plus set `reply_all: true`
  to copy the original `To` + `Cc` (minus your own
  addresses) into the outgoing `Cc`.
- **Forward**: set `forward_of` to an `emsg_…`. Subject
  gets `Fwd:` prefix, the original is quoted below your
  body, original attachments are NOT auto-carried (re-
  attach explicitly via `attachment_ids` if needed).
- **Redirect**: set `redirect_of` to an `emsg_…`. Body is
  NOT taken from `body_markdown`; the original message is
  forwarded verbatim with optional `comment` rendered in
  an attribution box. `Reply-To` is set to the original
  sender so the recipient can reply directly to them.
  `subject` / `body_markdown` are ignored in this mode.

`as_draft: true` saves to the sender's Drafts instead of
sending. Works with new/reply/forward; not with redirect.

Body is Markdown — server renders to HTML (and a plain-
text fallback) so the recipient sees formatting and
clickable links. Use standard GFM (headings, lists, bold,
italic, links, code).

Attachments: pass `attachment_ids` — handles from
`attachment_upload` (att_… ids or file_urls).
Combined size <= 25 MB (Gmail's limit).

On success returns `{ message_id, thread_id }` (live send)
or `{ draft_id }` (when `as_draft: true`).

Gating: if the mailbox owner enabled "Require confirmation
for agent send", a live send is held as a draft and returns
`{ confirmation_required: true, draft_id }` instead of
sending — a human approves it later. Otherwise, direct live
sends are rate-limited (50/hour per user); over the cap
returns `{ rate_limited: true, retry_after }`. `as_draft`
and confirmation-held sends do not count against the cap
(held sends are governed by human approval instead).

## Zugriff

Zugriffsprofil: `gated`. Module: `email`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja | Account prefix ID (acct_…). |
| `from_account_id` | string | Ja | Sender mail account prefix ID (mail_…). Discover via email_account_list. |
| `to` | array | Ja | Primary recipients. Plain addresses only — no "Name <email>". |
| `cc` | array | Nein | Cc recipients. Plain addresses only. |
| `bcc` | array | Nein | Bcc recipients. Plain addresses only. |
| `subject` | string | Nein | Subject line. Auto-prefixed with Re:/Fwd: in reply/forward modes if absent. Ignored in redirect mode. |
| `body_markdown` | string | Nein | GFM Markdown body. Server renders to HTML; plain text is auto-derived. Ignored in redirect mode. |
| `reply_to_message_id` | string | Nein | Message prefix ID (emsg_…) to reply to. Exclusive with forward_of/redirect_of. |
| `reply_all` | boolean | Nein | Reply-mode only: include original To+Cc (minus self) in outgoing Cc. |
| `forward_of` | string | Nein | Message prefix ID (emsg_…) to forward. Exclusive with reply_to_message_id/redirect_of. |
| `redirect_of` | string | Nein | Message prefix ID (emsg_…) to redirect. Exclusive with reply_to_message_id/forward_of. |
| `comment` | string | Nein | Redirect mode only: short note rendered in an attribution box above the forwarded body. |
| `attachment_ids` | array | Nein | Attachment handles from attachment_upload — att_… ids or file_urls. |
| `as_draft` | boolean | Nein | Save to Drafts instead of sending. Default false. Not compatible with redirect. |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account prefix ID (acct_…)."
    },
    "from_account_id": {
      "type": "string",
      "description": "Sender mail account prefix ID (mail_…). Discover via email_account_list."
    },
    "to": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Primary recipients. Plain addresses only — no \"Name <email>\"."
    },
    "cc": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Cc recipients. Plain addresses only."
    },
    "bcc": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Bcc recipients. Plain addresses only."
    },
    "subject": {
      "type": "string",
      "description": "Subject line. Auto-prefixed with Re:/Fwd: in reply/forward modes if absent. Ignored in redirect mode."
    },
    "body_markdown": {
      "type": "string",
      "description": "GFM Markdown body. Server renders to HTML; plain text is auto-derived. Ignored in redirect mode."
    },
    "reply_to_message_id": {
      "type": "string",
      "description": "Message prefix ID (emsg_…) to reply to. Exclusive with forward_of/redirect_of."
    },
    "reply_all": {
      "type": "boolean",
      "description": "Reply-mode only: include original To+Cc (minus self) in outgoing Cc."
    },
    "forward_of": {
      "type": "string",
      "description": "Message prefix ID (emsg_…) to forward. Exclusive with reply_to_message_id/redirect_of."
    },
    "redirect_of": {
      "type": "string",
      "description": "Message prefix ID (emsg_…) to redirect. Exclusive with reply_to_message_id/forward_of."
    },
    "comment": {
      "type": "string",
      "description": "Redirect mode only: short note rendered in an attribution box above the forwarded body."
    },
    "attachment_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Attachment handles from attachment_upload — att_… ids or file_urls."
    },
    "as_draft": {
      "type": "boolean",
      "description": "Save to Drafts instead of sending. Default false. Not compatible with redirect."
    }
  },
  "required": [
    "account_id",
    "from_account_id",
    "to"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "message_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Set when the message was sent."
    },
    "thread_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Set when the message was sent."
    },
    "draft_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Set when as_draft was true, or when a live send was held for confirmation."
    },
    "mode": {
      "type": "string",
      "enum": [
        "new",
        "reply",
        "reply_all",
        "forward",
        "redirect"
      ]
    },
    "confirmation_required": {
      "type": "boolean",
      "description": "ENG-1218: true when the send was held as a draft for human approval instead of sent."
    },
    "rate_limited": {
      "type": "boolean",
      "description": "ENG-1218: true when the hourly send rate limit was hit; nothing was sent."
    },
    "retry_after": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Seconds to wait before retrying, when rate_limited."
    }
  },
  "type": "object"
}
```