forward-message
Forward an existing email by ID to new recipients, optionally prepend text and add attachments, or save it as a draft for review.
Instructions
Use when: forwarding an existing message (by id) to new recipients (to is an array), with an optional body to prepend and optional extra attachments (same rules as send-email). Set send=false to save as a draft. Returns: a confirmation that the message was forwarded or saved as a draft, with the attachment count; over SMTP, also whether a Sent-folder copy was filed (sentCopy). Do not use when: replying to the sender/recipients (use reply-to-message) or composing a new message (use send-email / create-draft). Safety: with the default send=true this SENDS real email immediately and cannot be unsent — require explicit user confirmation of the recipients and any prepended body, or pass send=false to let the user review.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| to | Yes | ||
| body | No | Optional message to prepend (plain text) | |
| send | No | Send immediately (false = save as draft) | |
| account | No | For a numeric id, the account it was listed from; pair with mailbox. Omit for an imap: id. | |
| mailbox | No | For a numeric id, the exact source mailbox path; pair with account. A miss never searches elsewhere. | |
| transport | No | SMTP sends clean MIME and preserves reply threading; requires SMTP configuration. AppleScript uses Mail.app and may quote-wrap the new body on macOS 15+. Omit to prefer configured SMTP when sending; drafts use AppleScript. A selected SMTP transport never silently falls back. SMTP with send=false is rejected. | |
| attachments | No | Files to attach: absolute paths in the configured attachment read roots (e.g. '/Users/me/Documents/report.pdf') and/or inline {filename, contentBase64} objects up to 25 MiB decoded each. | |
| composition | No | Opt in to Mail's visible native editor: inserts only new prose, preserving its signature, HTML quotation and reply ancestry without the AppleScript content setter. Requires an unlocked desktop and existing Accessibility and Automation permissions. Uses Mail.app even when SMTP is configured; cannot be combined with transport=smtp or caller-built threading headers. New messages require an explicit account. Do not interact with Mail or the clipboard while it runs. Failure never falls back to another composition method or sends an unverified message. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| ok | No | ||
| sent | No | ||
| partial | No | SMTP accepted some recipients and rejected others; do not resend to accepted recipients. | |
| accepted | No | Recipients accepted by the SMTP server, not final inbox delivery. | |
| rejected | No | Recipients rejected by the SMTP server. | |
| sentCopy | No | SMTP only: whether a best-effort copy was filed to the account's Sent mailbox over IMAP (issue #220). Absent when no configured IMAP account matches the SMTP identity — not a failure, the feature simply wasn't engaged. | |
| messageId | No | ||
| transport | No | ||
| recipients | No | ||
| sentCopyError | No | Present only when sentCopy is false: why the Sent-folder copy failed. | |
| attachmentCount | No | ||
| deliveryUnknown | No | SMTP returned no definitive submission result. Verify before retrying. | |
| sentCopyAlreadyFiled | No | Present (true) only when sentCopy is true because the Sent mailbox already held this Message-ID (e.g. Gmail's SMTP files its own copy), so none was appended. |