# Prepare and review a draft

Save an email for review, revise it and send it when it's approved.

Source: https://cherami.to/docs/guides/drafts



A person or another agent can review a draft before it goes out. It stays in the account across sessions and connections, and you can save one before every field is filled in.

## Save the proposed email [#save-the-proposed-email]

With MCP, call `create_draft` with the `inbox_id`, a fresh `idempotency_key` and whatever you have so far.

With HTTP, set `CHERAMI_API_KEY`, `INBOX_ID` and `RECIPIENT`:

```bash
jq -n --arg key "$(uuidgen)" --arg recipient "$RECIPIENT" \
  '{idempotency_key: $key, to: [{address: $recipient}],
    subject: "Proposed next steps", text: "Here is the proposal for our next meeting."}' \
  > draft-create.json
curl --fail-with-body --silent --show-error \
  "https://cherami.to/v1/inboxes/$INBOX_ID/drafts" \
  -H "Authorization: Bearer $CHERAMI_API_KEY" \
  -H 'Content-Type: application/json' --data-binary @draft-create.json
```

A new draft returns `201` with its `id`; save it as `DRAFT_ID`. If you get no response, send the identical request again within 24 hours, `idempotency_key` included: you get the same draft back instead of a second one.

To draft a reply, add `source: {"action": "reply", "message_id": "SOURCE_ID"}` and put your response in `text`; `reply-all` works the same way. For a forward, use `"action": "forward"`, with the recipients and an optional introductory `text`. We fill in a reply's recipients and subject, and a forward's original message and attachments, when the draft is created, so the reviewer sees what will go out. [Reply and forward drafts](https://cherami.to/docs/api/drafts/create-draft).

## Retrieve, discuss and revise [#retrieve-discuss-and-revise]

Use `get_draft`, or:

```bash
curl --fail-with-body --silent --show-error \
  "https://cherami.to/v1/drafts/$DRAFT_ID" \
  -H "Authorization: Bearer $CHERAMI_API_KEY"
```

You get everything saved: recipients with their names, the bodies, the reply target and the attachment files.

Use `update_draft` to save changes. With HTTP, send only the fields that change:

```bash
curl --fail-with-body --silent --show-error \
  "https://cherami.to/v1/drafts/$DRAFT_ID" -X PATCH \
  -H "Authorization: Bearer $CHERAMI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Could we meet Thursday to agree on the next steps?"}'
```

Omitted fields stay unchanged. If the draft also has HTML, update or clear it when you revise the text. Recipient and attachment arrays replace the whole list. Sending uses the draft as currently saved.

With the [TypeScript SDK](https://cherami.to/docs/typescript), retrieve and revise by the same ID:

```ts
const { data: draft } = await client.getDraft({ draft_id: draftId });
// Discuss draft.content with the reviewer before saving a change.
await client.updateDraft({
  draft_id: draft.id,
  body: { text: "Could we meet Thursday to agree on the next steps?", html: null },
});
```

To create one, `createDraft` takes `{ inbox_id, body }` with the fields from [Save the proposed email](#save-the-proposed-email).

With an open [Python SDK client](https://cherami.to/docs/python), the same edit is:

```python
draft = client.get_draft({"draft_id": draft_id}).data
# Discuss draft["content"] with the reviewer before saving a change.
client.update_draft({
    "draft_id": draft["id"],
    "body": {"text": "Could we meet Thursday to agree on the next steps?", "html": None},
})
```

`create_draft` takes `{"inbox_id": inbox_id, "body": ...}`.

To discard a draft, use `delete_draft` or `DELETE /v1/drafts/DRAFT_ID`. This is final: a deleted draft doesn't go to Trash.

## Send when authorized [#send-when-authorized]

Use `send_draft` with the draft's ID, or:

```bash
curl --fail-with-body --silent --show-error \
  "https://cherami.to/v1/drafts/$DRAFT_ID/send" \
  -H "Authorization: Bearer $CHERAMI_API_KEY" \
  -H 'Content-Type: application/json' --data '{}'
```

With the TypeScript SDK:

```ts
const { data: receipt } = await client.sendDraft({ draft_id: draftId, body: {} });
console.log(receipt.message.id, receipt.message.status);
```

With Python:

```python
receipt = client.send_draft({"draft_id": draft_id, "body": {}}).data
print(receipt["message"]["id"], receipt["message"]["status"])
```

A draft sends like any message: the inbox's [sending rules](https://cherami.to/docs/guides/sending-rules) and your [allowance](https://cherami.to/docs/guides/sending#check-the-shared-allowance) apply, and we add the “Sent via Cherami” line. If it's refused for a missing field, a sending rule or your allowance, the draft stays editable: fix it and send again.

Once we attempt the send, the draft becomes `submitted` and can't change, whatever the outcome. Check `message.status` as for [any send](https://cherami.to/docs/guides/sending#inspect-the-outcome). If it's `rejected`, save a new draft with the fix and send that one.

Sending the same draft again never sends it twice, so if you get no response, send it again.

Need enforced approval steps before a draft can be sent? Email [hello@cherami.to](mailto:hello@cherami.to) and tell us about your workflow.

[Draft API reference](https://cherami.to/docs/api/drafts)
