Draft endpoints
The drafts endpoint lets you create email or SMS drafts that can either be sent immediately or 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
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 either "address" and "name", or "phone_number" keys. When "phone_number" is used, it must match a Twilio account number you have access to, formatted as "+" followed by digits only. |
{"address": "philippe@missiveapp.com", "name": "Philippe Lehoux"}
{"phone_number": "+18005550199"}
|
to_fields |
Array of objects with either "address" and "name", or "phone_number" keys. When "phone_number" is used, only one item is allowed and it must be formatted as "+" followed by digits only. |
[{"address": "philippe@missiveapp.com", "name": "Philippe Lehoux"}]
[{"phone_number": "+18005550199"}]
|
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 strings for appending to an existing conversation. Strings containing whitespace are silently ignored. | ["<some-reference-123>"] |
conversation |
Conversation ID string for appending to an existing conversation | "5bb24363-69e5-48ed-80a9-feee988bc953" |
team |
Team ID string | "646bb7f1-2066-40be-b8f6-bacb8b3b7419" |
force_team |
boolean | false |
organization |
Organization ID string | "90beb742-27a3-44cf-95bc-7e5097167c9d" |
add_users |
Array of user ID strings | ["7343bccf-cf35-4b33-99b0-b1d3c69c5f5c"] |
add_assignees |
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_team_inbox |
boolean | false |
close |
boolean | false |
send |
boolean | false |
from_field
from_field
must either have an address
that matches one of your email aliases on Missive, or a
phone_number
that matches one of your Twilio accounts.
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. References must not contain whitespace.
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
.
team
team
lets you link the draft’s conversation to a team. When a conversation is already linked to team, this field is ignored.
force_team
force_team
lets you force a new team even if the conversation is already in another team.
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
determines users who will get access to the conversation. When providing add_users
, the organization
field is required.
add_assignees
add_assignees
lets you assign users to the conversation. Existing assignees will remain assigned. When providing add_assignees
, 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_team_inbox
add_to_team_inbox
lets you move the draft’s conversation to a team inbox. When providing add_to_team_inbox
, the team
field is required.
add_to_inbox
add_to_inbox
lets you move the draft’s conversation to Inbox for everyone having access to the conversation.
close
close
lets you close the draft’s conversation for everyone having access to the conversation.
send
Set to true
to send the draft immediately upon creating it.
Message endpoints
Get a Message
GET /v1/messages/:id
Fetch a specific message headers, body and attachments using the message id
.
Response example:
{
"messages": {
"id": "3fa4bcf5-e57e-47a4-9422-de2cce5f802e",
"subject": "A Message",
"preview": "A message from Sam",
"type": "email",
"delivered_at": 1563806347,
"updated_at": 1563807320,
"created_at": 1563807320,
"email_message_id": "<0f1ab2d8-cd90-4dd1-a861-ef7e31fb3cdd@missiveapp.com>",
"in_reply_to": [],
"references": [],
"body": "<div>A message from Sam</div><br><img style=\"max-width: 100%\" alt=\"inline-image.png\" data-missive-attachment-id=\"81eed561-4908-4738-9a9f-2da886b1de43\">",
"from_field": {
"name": "Samwise Gamgee",
"address": "sam@fellowship.org"
},
"to_fields": [
{
"name": "Phil Smith",
"address": "phil.smith@fakemail.com"
}
],
"cc_fields": [],
"bcc_fields": [],
"reply_to_fields": [],
"attachments": [
{
"id": "81eed561-4908-4738-9a9f-2da886b1de43",
"filename": "inline-image.png",
"extension": "png",
"url": "https://...",
"media_type": "image",
"sub_type": "png",
"size": 114615,
"width": 668,
"height": 996
}
],
"conversation": {
"id": "47a57b76-df42-4d8k-927x-80dbe5d87191",
"subject": null,
"latest_message_subject": "A Message",
"organization": {
"id": "93e5e5d5-11a2-4c9b-80b8-94f3c08068cf",
"name": "Fellowship"
},
"color": null,
"assignees": [
{
"id": "6b52b6b9-9b51-46ad-a4e3-82ef3c45512c",
"name": "Frodo Baggins",
"email": "frodo@fellowship.org",
"unassigned": false,
"closed": false,
"archived": false,
"trashed": false,
"junked": false,
"assigned": true,
"flagged": false,
"snoozed": true
}
],
"assignee_names": "Frodo Baggins",
"assignee_emails": "frodo@fellowship.org",
"users": [
{
"id": "6b52b6b9-9b51-46ad-a4e3-82ef3c45512c",
"name": "Frodo Baggins",
"email": "frodo@fellowship.org",
"unassigned": false,
"closed": false,
"archived": false,
"trashed": false,
"junked": false,
"assigned": true,
"flagged": false,
"snoozed": true
}
],
"attachments_count": 0,
"messages_count": 1,
"authors": [
{
"name": "Samwise Gamgee",
"address": "sam@fellowship.org"
}
],
"drafts_count": 0,
"send_later_messages_count": 0,
"tasks_count": 0,
"completed_tasks_count": 0,
"shared_labels": [
{
"id": "146ff5c4-d5la-3b63-b994-76711fn790lq",
"name": "Elfs"
}
],
"shared_label_names": "Elfs",
"app_url": "missive://mail.missiveapp.com/#inbox/conversations/47a57b76-df42-4d8k-927x-80dbe5d87191",
"web_url": "https://mail.missiveapp.com/#inbox/conversations/47a57b76-df42-4d8k-927x-80dbe5d87191"
}
}
}
Inline images
Inline images markup in the message body
HTML contain no src
attribute, instead they contain a data-missive-attachment-id
attribute with the attachment id
. The attachment and its URL are available in the GET response under the attachments
key.
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
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": "#2266ED",
"text": "New customer signed up!",
"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 strings for appending to an existing conversation. Strings containing whitespace are silently ignored. | ["<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" |
team |
Team ID string | "646bb7f1-2066-40be-b8f6-bacb8b3b7419" |
force_team |
boolean | false |
add_users |
Array of user ID strings | ["7343bccf-cf35-4b33-99b0-b1d3c69c5f5c"] |
add_assignees |
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_team_inbox |
boolean | false |
close |
boolean | false |
Validations
- Either
text
,markdown
orattachments
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. References must not contain whitespace.
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.
team
team
lets you link the post’s conversation to a team. When a conversation is already linked to team, this field is ignored.
force_team
force_team
lets you force a new team even if the conversation is already in another team.
add_users
add_users
determines users who will get access to the conversation. When providing add_users
, the organization
field is required.
add_assignees
add_assignees
lets you assign users to the conversation. Existing assignees will remain assigned. When providing add_assignees
, 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_team_inbox
add_to_team_inbox
lets you move the post’s conversation to a team inbox. When providing add_to_team_inbox
, the team
field is required.
add_to_inbox
add_to_inbox
lets you move the post’s conversation to Inbox for everyone having access to the conversation.
close
close
lets you close the post’s conversation 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 |
Contact endpoints
Contact endpoints let you manage your contacts programmatically.
Create contact(s)
POST /v1/contacts
Payload example:
{
"contacts": [
{
"contact_book": "551b8675-11e9-49c3-aac0-01fb8510d862",
"first_name": "Philippe",
"last_name": "Lehoux",
"starred": true,
"infos": [
{
"kind": "phone_number",
"label": "mobile",
"value": "+1 518 777-7777"
},
{
"kind": "email",
"label": "home",
"value": "philippe@missiveapp.com"
}
],
"memberships": [
{
"title": "CEO",
"location": "Québec city",
"group": {
"kind": "organization",
"name": "Missive"
}
}
]
}
]
}
A successful request will return newly created contacts.
Response example:
{
"contacts": [
{
"id": "5960dcd2-3382-4430-aa70-955a2c62040a",
"first_name": "Philippe",
"last_name": "Lehoux",
"starred": true,
"contact_book": "db3767be-f506-4bd4-9e8f-b67afa332d44",
"deleted": false,
"modified_at": 1556201911,
"infos": [
{
"kind": "email",
"label": "home",
"value": "philippe@missiveapp.com"
},
{
"kind": "phone_number",
"label": "mobile",
"value": "+1 518 777-7777"
}
],
"memberships": [
{
"title": "CEO",
"location": "Québec city",
"group": {
"id": "f8905b6f-2d13-466a-a2e6-8e3de090a6d1",
"kind": "organization",
"name": "Missive"
}
}
]
}
]
}
Attributes
Name * required | Description | Example |
contact_book * |
Contact book ID string | "551b8675-11e9-49c3-aac0-01fb8510d862" |
first_name |
string | "Philippe" |
last_name |
string | "Lehoux" |
middle_name |
string | "Antoine" |
phonetic_first_name |
string | "f ih l - IH - p ai" |
phonetic_last_name |
string | "l ay h oo" |
phonetic_middle_name |
string | "ah n t - w ah n" |
prefix |
string | "Mr." |
suffix |
string | "Jr." |
nickname |
string | "Phil" |
file_as |
string | "Missive" |
notes |
string | "Cool prospect!" |
starred |
boolean | true |
gender |
string | "Male" |
infos |
Array containing contact info objects, see below for details |
[{"kind": "email", "label": "work", "value": "phil@missiveapp.com"}]
|
memberships |
Array containing contact membership objects, see below for details | [{ "title": "CEO", "group": { "kind": "organization", "name": "Missive" }}] |
infos
The infos
array lets you attach data of different kinds to contact: email
, twitter
, phone_number
, facebook
, physical_address
, url
, custom
:
Infos with kind email
Name * required | Description | Example |
kind * |
string | "email" |
value * |
Email address | "philippe@missiveapp.com" |
label * |
Email address type. Accepted values: home , work , personal , other |
"work" |
custom_label |
Custom label value, use only if label is other |
"old" |
Infos with kind phone_number
Name * required | Description | Example |
kind * |
string | "phone_number" |
value * |
Phone number | "+1 518 777-7777" |
label * |
Phone number type. Accepted values: main , mobile , home , work , home_fax , work_fax , other_fax , pager , other |
"mobile" |
custom_label |
Custom label value, use only if label is other |
"old" |
Infos with kind twitter
Name * required | Description | Example |
kind * |
string | "twitter" |
value * |
Twitter username | "@plehoux" |
label * |
Twitter account type. Accepted values: work , personal , other |
"personal" |
custom_label |
Custom label value, use only if label is other |
"old" |
Infos with kind facebook
Name * required | Description | Example |
kind * |
string | "facebook" |
name * |
Facebook user name | "Philippe-Antoine Lehoux" |
label * |
Facebook account type. Accepted values: work , personal , other |
"personal" |
custom_label |
Custom label value, use only if label is other |
"old" |
Infos with kind physical_address
Name * required | Description | Example |
kind * |
string | "physical_address" |
street |
string | 274 Christophe-Colomb Est Street |
extended_address |
string | Office 222 |
city |
string | Quebec |
region |
string | QC |
postal_code |
string | G1K 3T4 |
po_box |
string | PO#12345 |
country |
string | Canada |
label * |
Address type. Accepted values: work , home , other |
"work" |
custom_label |
Custom label value, use only if label is other |
"old" |
Infos with kind url
Name * required | Description | Example |
kind * |
string | "url" |
value * |
URL | "https://missiveapp.com/" |
label * |
URL type. Accepted values: homepage , profile , blog , work , personal , other |
"homepage" |
custom_label |
Custom label value, use only if label is other |
"admin" |
Infos with kind custom
Name * required | Description | Example |
kind * |
string | "custom" |
value * |
string | "A custom value" |
label * |
Custom info type. Accepted values: other |
"other" |
custom_label |
Custom label value | "custom" |
memberships
The memberships
array lets you link a contact to organizations or groups. A membership always embeds a related group
, which has a kind
equal to either group
or organization
.
- Organizations are most often used to link contacts to their work location.
- Groups are used to group contacts together. Think of groups as labels.
Name * required | Description | Example |
department |
can be set if group is of kind organization |
"Finance" |
title |
can be set if group is of kind organization |
"CFO" |
location |
can be set if group is of kind organization |
"Montreal" |
description |
can be set if group is of kind organization |
"Handle reporting" |
group * |
Object, see below for details | {"kind": "organization", "name": "Missive"} |
memberships.group
Name * required | Description | Example |
kind * |
Group type. Accepted values: organization , group |
"organization" |
name * |
string | "Missive" |
Update contact(s)
PATCH /v1/contacts/:id
A successful request will return the updated contacts with embedded memberships
and infos
.
Payload example:
{
"contacts": [
{
"id": "ee31f156-db95-4158-923f-b26450e0dbf7",
"last_name": "Lehoux"
}
]
}
Attributes
Contact id
is required. See the Create contact(s) section for other attributes. When updating a contact, you may pass only attributes you want to update. In the example above, only the last name will be updated.
There are two exceptions: the infos
and memberships
arrays. When these are passed, you must pass all of their items, otherwise the missing items will be deleted from the contact. Consequently, to delete items from infos
or memberships
, simply omit them in the array passed in the request.
List contacts
GET /v1/contacts
This endpoint is useful to sync Missive contacts to another service or to find contacts based on some search term.
Response example:
{
"contacts": [
{
"id": "183382b8-fb70-4a35-bf22-4ebae1450553",
"first_name": "Arthur",
"last_name": "Sto",
"starred": false,
"contact_book": "487bc080-6631-4edc-830e-1d114eef4ab0",
"deleted": false,
"modified_at": 1556200645
},
{
"id": "862aceb8-3553-4644-9300-0312a432315f",
"first_name": "Zeb",
"last_name": "Craft",
"starred": false,
"contact_book": "487bc080-6631-4edc-830e-1d114eef4ab0",
"deleted": false,
"modified_at": 1556200644
},
{
"id": "b40713e2-e790-4c67-9eb3-22e83bd1bdf9",
"first_name": "Alex",
"last_name": "Alstorm",
"starred": false,
"contact_book": "487bc080-6631-4edc-830e-1d114eef4ab0",
"deleted": false,
"modified_at": 1556200643,
"infos": [
{
"kind": "phone_number",
"label": "work",
"value": "+1 (418) 717-1066"
},
{
"kind": "custom",
"custom_label": "Favorite food",
"value": "Pizza"
}
],
"memberships": [
{
"title": "Project manager",
"group": {
"id": "522f8e19-0261-4f8b-b8b1-8d8bb4055569",
"kind": "organization",
"name": "Pagac Inc"
}
}
]
}
]
}
Params
Name * required | Default | Description |
contact_book * |
Contact book ID | |
order |
last_name |
Default ordering is by contact last name. To get the most recently updated contacts, pass last_modified |
limit |
50 |
Number of contacts returned. Max value: 200 |
offset |
0 |
Offset used to paginate. |
modified_since |
null |
To return only contacts that have been modified or created since a point in time, pass a Unix Epoch time like 1556137749 . |
include_deleted |
false |
To include deleted contacts in the results of modified_since requests, pass true . Only the contact id and deleted attributes will be returned since the contact data has been deleted from Missive. |
search |
null |
Text string to filter contacts. search term(s) are matched against all contact infos: name, email, phone, organization, custom fields, notes, etc. |
Get a contact
GET /v1/contacts/:id
Fetch a specific contact using the contact id
. Trying to get a deleted contact will produce a 404 response.
Contact book endpoints
In Missive, contacts are stored in contact books. Contact books can be private or shared with various members of an organization.
List contact books
GET /v1/contact_books
Get all contact books the user has access to. Remember that a contact book id
is mandatory when creating a contact programmatically.
Response example:
{
"contact_books": [
{
"id": "6a012cec-c2e2-4e21-91e3-a36dba6930e7",
"user": "0db31755-adcd-4c51-8346-66bb7194449e",
"share_with_organization": true,
"share_with_team": null,
"share_with_users": [],
"organization": "2b24d4f0-d082-41c7-9075-d2a34afcfcbd",
"name": "HR",
"description": null
},
{
"id": "171ed616-bed2-4781-91b8-bf52459dd9e6",
"user": "0db31755-adcd-4c51-8346-66bb7194449e",
"share_with_organization": true,
"share_with_team": null,
"share_with_users": [],
"organization": "2b24d4f0-d082-41c7-9075-d2a34afcfcbd",
"name": "Production",
"description": null
},
{
"id": "108e216d-79f9-452c-93b9-4176213d4fdb",
"user": "0db31755-adcd-4c51-8346-66bb7194449e",
"share_with_organization": false,
"share_with_team": null,
"share_with_users": [],
"organization": null,
"name": "My personal book",
"description": null
}
]
}
Contact group endpoints
Contacts can be grouped in both organizations and groups. Organizations are typically used to map a group of related contacts (businesses). Groups are used to group unrelated contacts, think of groups as labels.
List contact groups
GET /v1/contact_groups
Get all contact groups or organizations linked to a contact book.
Response example:
{
"contact_groups": [
{
"id": "6a012cec-c2e2-4e21-91e3-a36dba6930e7",
"name": "VIPs",
}
]
}
Params
Name * required | Default | Description |
contact_book * |
Contact book ID | |
kind * |
Either group or organization . |
|
limit |
50 |
Number of contacts returned. Max value: 200 |
offset |
0 |
Offset used to paginate. |
User endpoints
List users
GET /v1/users
Get all users known by the authenticated user.
Response example:
{
"users": [
{
"id": "a41a00fd-453d-49d7-a487-9765c35a3b70",
"me": true,
"email": "philippe@missiveapp.com",
"name": "Philippe Lehoux",
"avatar_url": "https://...",
}
]
}
Organization endpoints
List organizations
GET /v1/organizations
Get all organizations the authenticated user is part of.
Response example:
{
"organizations": [
{
"id": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92",
"name": "Conference Badge"
}
]
}
Last updated on Feb 15th, 2021