# Write a draft without sending it

Source: https://docs.vlayers.ai/reference/messages/create-draft

`POST /v1/drafts` · scope `messages:send`

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.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `idempotency-key` | header | string | no | 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. Example: `"7f3c9a2e-5b1d-4c8e-9f0a-2d6b8e4c1a37"` |
| `conversationId` | body | string | no | The conversation to answer. Leave out `from`, `to` and `subject`: the conversation decides them. |
| `from` | body | object | no | The mailbox to write from: `{ "mailboxId": "support@acme.vlayersmail.com" }`. |
| `to` | body | string | no | The address to write to. |
| `subject` | body | string | no | The new message's subject. A reply keeps its conversation's subject. |
| `text` | body | string | yes | The words of the message. |
| `attachments` | body | object[] | no | 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. |
| `files` | body | object \| string[] | no | Email only: files the user dropped into ChatGPT, each `{ download_url, file_id, mime_type?, file_name? }`. Fetched and checked like `attachments`. |

## Request

cURL:

```bash
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?"
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { draft } = await voicelayer.messages.createDraft({
  conversationId: '0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21',
  text: 'Friday at 3pm works. Shall I send an invite?'
});
console.log(draft.id);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.messages.create_draft(
    conversation_id="0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
    text="Friday at 3pm works. Shall I send an invite?",
)
print(result.draft.id)
```

## Response `200`

```json
{
  "draft": {
    "id": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",
    "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
    "mailbox": "support@acme.vlayersmail.com",
    "to": "ada@example.org",
    "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
  }
}
```
