Write a draft without sending it

POST
/v1/drafts

Writes an email and keeps it, unsent. Answer a conversation with conversationId, or write a new message with from (one of your mailboxes) and to. Nothing leaves until you send it with POST /v1/drafts/{id}/send. A draft is checked as it is sent, not as it is written: the text is screened, the recipient rule, opt-outs and limits apply, and the send is charged then. A new message to someone the mailbox may not write to is refused now, with the reason.

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.

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
conversationId?string

The conversation to answer. Leave out from, to and subject: the conversation decides them.

Formatuuid
from?

The mailbox to write from: { "mailboxId": "[email protected]" }.

to?string

The address to write to.

Length3 <= length <= 320
subject?string

The new message's subject. A reply keeps its conversation's subject.

Length1 <= length <= 200
text*string

The words of the message.

Length1 <= length <= 20000
attachments?array<|||>

Email only: files to attach, each { "url" } (a public https link), { "messageId", "attachmentId" } (a file already in the inbox), { "filename", "contentType", "data" } (base64) or { "uploadId" } (from POST /v1/attachments). Programs and scripts are refused; the count and the total size are the workspace's limits.

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

The draft this Idempotency-Key already made

application/json
  1. response
draft*
Example Request
curl -X POST https://api.vlayers.ai/v1/drafts \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",    "text": "Friday at 3pm works. Shall I send an invite?"  }'
Example Response
{  "draft": {    "id": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",    "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",    "mailbox": "[email protected]",    "to": "[email protected]",    "subject": "Friday",    "body": "Friday at 3pm works. Shall I send an invite?",    "attachments": [],    "heldFor": "api",    "origin": "composed",    "state": "pending",    "createdAt": "2026-10-20T15:04:05.000Z",    "expiresAt": "2026-10-27T15:04:05.000Z",    "decidedBy": null,    "decidedAt": null,    "edited": false,    "reason": null  }}