Forward an email to other people

POST
/v1/messages/{id}/forward

Forwards one email message from the mailbox that holds it. The new email is from the same mailbox, with the subject Fwd: <original subject>, your optional note, and the original text quoted. The files of the original go along unless includeAttachments is false. It goes through the normal send path, so a mailbox with review before send holds it for approval, and each person is checked and charged like any other send. Each person gets their own copy, including cc people; nobody sees who else received it.

Requires an API key with the messages:send scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

id*string

The message id.

Header Parameters

idempotency-key?string

A unique value (a UUID works) that makes a retry safe: sending the same key again returns the first result instead of acting twice. 1–255 printable characters.

Length1 <= length <= 255

Request Body

application/json
  1. body
to*array<>

Who to forward it to: 1 to 10 email addresses.

Items1 <= items <= 10
cc?array<>

More people to send a copy to (counted in the 10). They get their own copy, not a visible cc.

Itemsitems <= 10
note?string

A line or two of your own, placed above the quoted message.

Length1 <= length <= 5000
includeAttachments?boolean

Whether the original's files go along. Default true; false sends the words only.

attachments?array<|||>

More files to attach beside the original's (same forms as on a send).

Itemsitems <= 50
files?array<|>

Email only: files the user dropped into ChatGPT, each { download_url, file_id, mime_type?, file_name? }. Fetched and checked like attachments.

Items1 <= items <= 20

Response Body

Accepted: one result per person, sent or held for approval

application/json
  1. response
summary*string
subject*string
results*array<>
Items1 <= items
Example Request
curl -X POST "https://api.vlayers.ai/v1/messages/$MESSAGE_ID/forward" \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "to": [      "[email protected]"    ],    "note": "Can you take this one?"  }'
Example Response
{  "summary": "Forwarded to 1 person.",  "subject": "Fwd: Do you have a table for two tonight?",  "results": [    {      "to": "[email protected]",      "role": "to",      "status": "sent",      "messageId": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",      "error": null    }  ]}