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.
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.
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,markdownorattachmentsis 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