Guide

API Documentation

Summary

Draft endpoints

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": "paul@acme.com"
      }
    ],
    "from_field": {
      "name": "Philippe Lehoux",
      "address": "philippe@missiveapp.com"
    }
  }
}

Attributes

Name * required Description Example
subject string "Hello"
body HTML or text string "<b>World!</b>"
from_field Object with "address" and "name" keys {"address": "philippe@missiveapp.com", "name": "Philippe Lehoux"}
to_fields Array of objects with "address" and "name" keys [{"address": "philippe@missiveapp.com", "name": "Philippe Lehoux"}]
cc_fields Array of objects with "address" and "name" keys [{"address": "philippe@missiveapp.com", "name": "Philippe Lehoux"}]
bcc_fields Array of objects with "address" and "name" keys [{"address": "philippe@missiveapp.com", "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
from_field

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.

attachments

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"
references

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: <a@a.com> or References: <a@a.com> header, you may add "references": ["<a@a.com>"] 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.

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

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

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.


Post endpoints

The posts endpoint lets you inject data in any Missive conversation. You can create posts in new conversations or append them to existing ones.

Example Each time someone pushes code to Github, create a post that lists the commits.
A post created from a Github webhook

Create a post

POST /v1/posts

Basic example:

{
  "posts": {
    "conversation": "00f78fe9-f11a-4b4e-a502-67e6138d3b0f",
    "notification": { "title": "A title", "body": "A body" },
    "username": "Missive",
    "username_icon": "https://s3.amazonaws.com/missive-assets/missive-avatar.png",
    "attachments": [
      {
        "author_name": "Philippe Lehoux",
        "author_link": "mailto:philippe@missive.com",
        "author_icon": "avatar:philippe@missive.com",
        "color": "#fff",
        "text": "Read your email for the 1st time",
        "timestamp": 1511540318
      }
    ]
  }
}

Attributes

Name * required Description Example
username Name of the post author, used instead of the API token owner’s name "Missive"
username_icon Image of the post author, used instead of the API token owner’s avatar "https://s3.amazonaws.com/missive-assets/missive-avatar.png"
conversation_icon Image used as the icon in the conversation list "https://s3.amazonaws.com/missive-assets/missive-avatar.png"
conversation_subject string "New user!"
conversation_color HEX code or "good" "warning" "danger" string "#000", "danger"
text Main message of a post "This is a post!"
markdown Main message of a post, formatted with Markdown "This is a **post**!"
notification* Object with the "title" and "body" keys, used to render a notification {"title":"A title", "body": "A body"}
attachments Array containing attachment objects, see below for details [{"text": "This is an attachment!"}]
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"]
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
Validations
  • Either text, markdown or attachments is required.
  • All string fields have a variable maximum length, over which the content will be truncated. Those limits are safe enough for normal use.
references

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

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

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

conversation

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

organization

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

add_users

add_users is only used when a new conversation is created. It determines users who will have access to the 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 post’s conversation.

add_to_inbox, add_to_unassigned

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

attachments
Name * required Description Example
color HEX code or "good" "warning" "danger" string "#ccc", "danger"
pretext Text string "This is a pretext!"
author_name Attachment author name "User - Phil"
author_link URL linking to the author "https://admin.myapp.com/users/phil"
author_icon Image URL of the attachment author "https://myapp.com/phil.png"
title Attachment title "This is a title!"
title_link URL linking to the attachment ressource "https://myapp.com/a-ressource"
image_url Image URL of the attachment "https://myapp.com/a-ressource.png"
text Text string "This is text!"
timestamp Integer value in Unix time 1512395766
footer Text string "This is a footer!"
footer_icon Image URL of the attachment footer "https://myapp.com/logo.png"
fields Array containing of field objects, see below for details [{"title": "Paying customer","value": "yes"}]
attachments.fields
Name * required Description Example
title Text string "Paying customer?"
value Text string "yes"
short Boolean. If true, there will be two fields per row,
otherwise one per row.
true


Last updated on Frebruary 28, 2019

Need more specific answers?

Contact us via our Help Center