Prepare and review a draft
Save an email for review, revise it and send it when it's approved.
Read as Markdown ↗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
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:
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.jsonA 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.
Retrieve, discuss and revise
Use get_draft, or:
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:
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, retrieve and revise by the same ID:
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.
With an open Python SDK client, the same edit is:
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
Use send_draft with the draft's ID, or:
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:
const { data: receipt } = await client.sendDraft({ draft_id: draftId, body: {} });
console.log(receipt.message.id, receipt.message.status);With 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 and your 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. 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 and tell us about your workflow.