API Documentation



The drafts endpoint lets you create email drafts that can then be edited and sent from the Missive app. You can create drafts in a new conversation or append them as a reply to an existing one.

Example Create a new draft in a shared label named “Follow up” with a specific body every time someone fills out a form on your website.

Create a draft

POST /v1/drafts

Basic example:

  "drafts": {
    "subject": "Hello",
    "body": "World!",
    "to_fields": [
        "address": ""
    "from_field": {
      "name": "Philippe Lehoux",
      "address": ""


Name * required Description Example
subject string "Hello"
body HTML or text string "<b>World!</b>"
from_field Object with "address" and "name" keys {"address": "", "name": "Philippe Lehoux"}
to_fields Array of objects with "address" and "name" keys [{"address": "", "name": "Philippe Lehoux"}]
cc_fields Array of objects with "address" and "name" keys [{"address": "", "name": "Philippe Lehoux"}]
bcc_fields Array of objects with "address" and "name" keys [{"address": "", "name": "Philippe Lehoux"}]
attachments Array containing files, see below for details [{"base64_data": "iVBORw0KGgoAAAANS…", "filename": "logo.png"}]
references Array of references for appending to an existing conversation ["<some-reference-123>"]
conversation Conversation ID string for appending to an existing conversation "5bb24363-69e5-48ed-80a9-feee988bc953"
organization Organization ID string "90beb742-27a3-44cf-95bc-7e5097167c9d"
add_users Array of user ID strings ["7343bccf-cf35-4b33-99b0-b1d3c69c5f5c"]
conversation_subject string "New user!"
add_shared_labels Array of shared label ID strings ["9825718b-3407-40b8-800d-a27361c86102"
remove_shared_labels Array of shared label ID strings ["e4aae78f-e932-40a2-9ece-ed764aa85790"]
add_to_inbox boolean false
add_to_unassigned boolean false

The from_field address be must equal to one of your email aliases on Missive. If it is not, the draft will still be created but with no alias selected in the From field.


The attachments array lets you attach up to 5 files to draft. Each file must be under 5 Mb.

Name * required Description Example
base64_data* The base64-encoded contents of the file "iVBORw0KGgoAAAANS…"
filename* Filename of the attachment "logo.png"

The references array lets you append a draft to an existing conversation. Given a conversation already exists and includes an email with a Message-ID: <> or References: <> header, you may add "references": ["<>"] to your request so the draft gets appended to that conversation.

If references passed in the request are related to more than one conversation, the draft will be appended to the first conversation found. If no reference is provided, the draft will be created in a new conversation. If one or more references are provided but none of them match an existing conversation, the draft will be created in a new conversation.

Chevrons around references are optional. Both ["<some-reference-123>"] and ["some-reference-123"] would reference the same conversation.


If you know the ID of an existing Missive conversation you want to create your draft into, you can pass it as conversation instead of using references.


organization lets you scope the search for conversations to ones already associated with an organization. If a new conversation is created and organization is passed, the new conversation will be linked to that organization.


add_users is only used when a new conversation is created. It determines users who will get access to this new conversation. When providing add_users, the organization field is required.

add_shared_labels, remove_shared_labels

add_shared_labels and remove_shared_labels let you manage shared labels that are applied to the draft’s conversation.

add_to_inbox, add_to_unassigned

add_to_inbox and add_to_unassigned let you move the draft’s conversation to Inbox or Unassigned for everyone having access to the conversation.

Last updated on July 4, 2018

Need more specific answers?

Contact us via our Help Center