Endpoints
Complete reference for Missive API endpoints: analytics, conversations, drafts, posts, contacts, labels, and more.
Analytics
Analytics endpoints let you fetch a report based on a selected period and optional filters such as team inbox, users, labels, etc. Two endpoints are involved due to the asynchronous nature of generating reports: one request to create the report and another to get the data shortly after.
Analytics API endpoints require a Productive or Business plan. Filtering capabilities (teams, users, labels, accounts) require a Business plan.
Example usage Automatically sync analytics data to your Business Intelligence tool.
Create analytics report
POST /v1/analytics/reports
{
"reports": {
"organization": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92",
"start": 1691812800,
"end": 1692371867,
"time_zone": "America/Montreal"
}
}{
"reports": {
"organization": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92",
"start": 1691812800,
"end": 1692371867,
"time_zone": "America/Montreal",
"teams": [
"0e24f298-965d-4475-9220-b32636a1e2c3"
],
"users": [
"1ce8117e-ae42-4304-b953-c81656da4bd1",
"74f91030-39b8-4627-9835-9cfbce9d67c1"
],
"accounts": [
"716be7a6-fd40-45a2-bfcb-43b9ed38d1f0",
"a5d2aa1c-3828-4f90-bbd8-3dffaadda97e"
],
"account_types": [
"email",
"sms"
],
"shared_labels": [
"bca0bb8f-8b2f-45f8-a59a-333de84f0184"
]
}
}{
"reports": {
"id": "8441d4a0-a0ad-4f0f-aa9c-1cc881057e42"
}
}This id must then be included in a Get report request.
Params
organization*
Organization ID string
"0d9bab85-a74f-4ece-9142-0f9b9f36ff92"
start*
Report period start
1691812800
end*
Report period end
1692371867
teams
Array of team ID strings
["0e24f298-965d-4475-9220-b32636a1e2c3"]
users
Array of user ID strings
["1ce8117e-ae42-4304-b953-c81656da4bd1"]
shared_labels
Array of organization label ID strings
["bca0bb8f-8b2f-45f8-a59a-333de84f0184"]
accounts
Array of account ID strings
["716be7a6-fd40-45a2-bfcb-43b9ed38d1f0"]
account_types
Array of type strings
["email", "sms"]
teams, users, shared_labels, accounts
Refer to Resource IDs.
account_types
"custom", "email", "instagram", "live_chat", "messenger", "sms", "whatsapp"
Get analytics report
GET /v1/analytics/reports/:id
Fetch a report using its id returned by a Create report request. Report data is returned as JSON.
Most reports complete within 2 or 3 seconds after creation, but some may take 30 seconds or more. They expire 60 seconds after completion. An empty 404 response is returned for incomplete, expired or inexistent reports.
Fetch a report 5 seconds after its creation and retry every 5 seconds until a successful 200 response is returned.
Contacts
Contact endpoints let you manage your contacts programmatically.
Example usage Automatically sync contacts between Missive and your CRM.
Create contact(s)
POST /v1/contacts
A successful request will return newly created contacts.
Attributes
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
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
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
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
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
kind*
string
"physical_address"
street
string
123 Fake 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
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
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.
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
kind*
Group type. Accepted values: organization, group
"organization"
name*
string
"Missive"
Contact properties
The same shape is returned by Create contact(s), Update contact(s), List contacts, and Get a contact.
id*
Contact UUID
deleted*
Whether the contact is deleted
modified_at*
Unix timestamp when the contact was last modified
contact_book*
Contact book UUID
first_name
last_name
middle_name
phonetic_first_name
phonetic_last_name
phonetic_middle_name
prefix
suffix
nickname
file_as
notes
starred
Boolean
gender
pronouns
job_title
infos
Array of contact infos (see contact info kinds in the request docs)
memberships
Array of contact memberships (see request docs)
A deleted contact returned via modified_since + include_deleted=true will contain only id, deleted: true, and modified_at.
Update contact(s)
PATCH /v1/contacts/:id1,:id2,:id3,...
A successful request will return the updated contacts with embedded memberships and infos.
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.
The infos and memberships arrays are exceptions: when passed, you must include all items. Missing items will be deleted from the contact. To delete items, omit them from the array.
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.
Params
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 books
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
List contact books the authenticated user has access to. Remember that a contact book id is mandatory when creating a contact programmatically.
Params
limit
50
Number of contact books returned. Max value: 200
offset
0
Offset used to paginate.
Contact book properties
id*
Contact book UUID
name*
Contact book name
user*
UUID of the owning user
organization
Organization UUID for shared books
share_with_organization*
Whether the book is shared with everyone in the organization
share_with_team
Team UUID if shared with a specific team
share_with_users*
Array of user UUIDs the book is explicitly shared with
description
Description
importing*
Whether an import is currently in progress
import_error_text
Error message from the last failed import
import_rows_count
Total rows in the current/last import
import_processed_rows_count
Rows processed so far in the current/last import
Contact groups
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
List contact groups or organizations linked to a contact book.
Params
contact_book*
Contact book ID
kind*
Either group or organization.
limit
50
Number of contact groups returned. Max value: 200
offset
0
Offset used to paginate.
Contact group properties
id*
Contact group UUID
name*
Contact group name
Conversations
Managing conversation state (close, move, assign, etc.)
Use Update conversations to change conversation state without adding a post. Use Posts, Messages, or Drafts when you also want to create visible content in the conversation.
Posts are useful for automations and integrations that should leave a visible trace showing what triggered the action.
List conversations
GET /v1/conversations
List conversations visible to the user who owns the API token. Must be filtered by mailbox, shared label or team.
At least one mailbox filter is required. Omitting all of them returns a "You need to paginate at least one mailbox" error. Pass one of: inbox, all, assigned, closed, snoozed, flagged, trashed, junked, drafts, shared_label, team_inbox, team_closed, or team_all.
Returns conversations ordered from newest to oldest activity. To paginate, pass an until param equal to the last_activity_at of the oldest conversation returned in the previous page. The last page is reached when fewer conversations than limit are returned or if all conversations in a page have the same last_activity_at.
A page may return more conversations than limit. Conversations where the API token user is a guest will be returned with limited data, containing only the id and last_activity_at fields.
Params
limit
Number of conversations returned. Default: 25. Max: 50.
until
Timestamp value in Unix time used to paginate. Use the last_activity_at of the oldest conversation from the previous page.
inbox
Pass true to list conversations in the Inbox.
all
Pass true to list conversations in the All mailbox.
assigned
Pass true to list conversations assigned to the user.
closed
Pass true to list conversations in Closed.
snoozed
Pass true to list conversations in Snoozed.
flagged
Pass true to list conversations in Starred.
trashed
Pass true to list conversations in Trash.
junked
Pass true to list conversations in Spam. Note: Missive uses "Spam" in the UI, though some email providers call this "Junk".
drafts
Pass true to list conversations in Drafts.
shared_label
Shared label ID. List conversations in the shared label.
team_inbox
Team ID. List conversations in the team's Inbox.
team_closed
Team ID. List conversations in the team's Closed mailbox.
team_all
Team ID. List conversations in the team's All mailbox.
organization
Organization ID. Filter conversations to only those shared with the organization. There is no use for the organization param when passing a shared_label or team_ param.
email
Email address string. Filter conversations by a specific contact email address (e.g., user@example.com). Matches the address in the From, To, Cc, Bcc and Reply-To headers. Mutually exclusive with domain and contact_organization.
domain
Domain string. Filter conversations by contacts from a specific email domain (e.g., example.com not @example.com). Matches the domain in the From, To, Cc, Bcc and Reply-To headers. Mutually exclusive with email and contact_organization.
contact_organization
Contact organization or group UUID. Filter conversations by contacts belonging to a specific contact organization or contact group. Mutually exclusive with email and domain.
The email, domain, and contact_organization parameters are mutually exclusive. You can only use one of these contact filters at a time. Passing multiple will return a 400 error.
Get a conversation
GET /v1/conversations/:id
Fetch a specific conversation using the conversation id.
The returned conversation may have a different id. This happens when conversations get merged; passing an old conversation id will keep working, but the new conversation id will be returned.
Conversation properties
The same shape is returned by List conversations, Get a conversation, Update conversations, and Merge conversations.
id*
Conversation UUID
created_at*
Unix timestamp when the conversation was created
subject
Conversation subject
latest_message_subject
Subject of the latest message in the conversation
organization
Organization object (id, name)
color
HEX color or color name (good, warning, danger)
authors*
Array of message authors (name, address)
external_authors*
Subset of authors excluding coworkers
users*
Array of users with access (see User access properties below)
assignees*
Subset of users who are assigned to the conversation
assignee_names*
Comma-separated assignee display names
assignee_emails*
Comma-separated assignee emails
shared_labels*
Array of shared label objects on the conversation
shared_label_names*
Comma-separated shared label names
team
Compact team object (see Compact team properties below)
messages_count*
Number of messages in the conversation
drafts_count*
Number of drafts in the conversation
send_later_messages_count*
Number of scheduled (send-later) messages
attachments_count*
Number of attachments across all messages
tasks_count*
Number of tasks in the conversation
completed_tasks_count*
Number of completed tasks
last_activity_at*
Unix timestamp of the conversation's most recent activity
closed_at
Unix timestamp when the task/tasked conversation was closed
web_url*
URL to open the conversation in the web app
app_url*
URL to open the conversation in the desktop app
When the API token user is a guest in the conversation, only id and last_activity_at are returned.
Compact team properties
The team object embedded in conversation responses is a compact team object. For the full team shape, use List teams, Create team(s), or Update team(s).
id*
Team UUID
name*
Team name
organization*
Organization UUID
active_members*
Array of user UUIDs for active team members
observers*
Array of user UUIDs for team observers
User access properties
Items inside users and assignees on a conversation.
id*
User UUID
name*
User display name
email*
User email
assigned*
Whether the user is assigned to the conversation
unassigned*
Whether the conversation is in the user's Unassigned mailbox
closed*
Whether the conversation is in the user's Closed mailbox
archived*
Whether the conversation is archived for the user (not in Inbox)
flagged*
Whether the conversation is starred (flagged) for the user
snoozed*
Whether the conversation is snoozed for the user
trashed*
Whether the conversation is in the user's Trash
junked*
Whether the conversation is in the user's Spam mailbox
Update conversations
PATCH /v1/conversations/:id
Update one or more conversations without creating a post. Use this endpoint to close, reopen, move, assign, label, recolor, or rename conversations silently. System events can still appear in Missive. When the update changes shared labels, label change rules still run.
To update multiple conversations in one request, pass comma-separated IDs:
PATCH /v1/conversations/:id,:id2,:id3
The request body must include a conversations array with exactly one object for each ID in the URL. Each object must include the matching id.
If a conversation was merged, you can pass the old conversation id. The response returns the current conversation id. In bulk requests, do not pass two IDs that resolve to the same merged conversation.
The response uses the same conversation object shape documented in Conversation properties.
Attributes
id*
Conversation ID string. Must match an ID passed in the URL.
"6d3c9b1c-7067-4a28-8ea6-ea91340b67cc"
subject
New conversation subject
"Refund approved"
color
HEX color code or "good" "warning" "danger" string
"#000", "danger"
conversation_color
Same as color
"#000", "danger"
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"]
remove_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
true
add_to_team_inbox
boolean
true
close
boolean
true
reopen
boolean
true
organization
organization is required when using add_users, add_assignees, remove_assignees, or add_shared_labels.
team
team changes the conversation team when the conversation is not already linked to another team.
force_team
force_team forces a new team even if the conversation is already in another team.
add_assignees, remove_assignees
add_assignees assigns users to the conversation. remove_assignees removes users from the conversation's assignees. Both require organization, and user IDs must belong to members of that organization.
add_shared_labels, remove_shared_labels
add_shared_labels and remove_shared_labels manage shared labels on the conversation. When adding labels, they must belong to organization and be visible to the API token user.
add_to_team_inbox
add_to_team_inbox moves the conversation to a team inbox. When providing add_to_team_inbox, the team field is required.
add_to_inbox
add_to_inbox moves the conversation to Inbox for everyone having access to the conversation.
close
close closes the conversation for everyone having access to the conversation.
reopen
reopen reopens the conversation for everyone having access to the conversation.
List conversation messages
GET /v1/conversations/:id/messages
List messages in the conversation passed as id. Draft messages are excluded.
Returns messages ordered from newest to oldest. To paginate, pass an until param equal to the delivered_at of the oldest message returned in the previous page. The last page is reached when fewer messages than limit are returned or if all messages in a page have the same delivered_at.
A page may return more messages than limit.
Params
limit
Number of messages returned. Default: 10. Max: 10
until
Timestamp value in Unix time used to paginate. Use the delivered_at of the oldest message from previous page.
Message properties
The same shape is returned by List conversation messages, List conversation drafts, List messages, and Get a Message. The body field is only included by Get a Message. Some keys are channel-specific (see notes below).
id*
Entry UUID
type*
Message type: email, custom_email, custom_text, custom_html, twilio_message, messenger_message, instagram_message, etc.
preview*
Short text preview of the message body
delivered_at*
Unix timestamp when the message was delivered
updated_at*
Unix timestamp when the message was last updated
created_at*
Unix timestamp when the message record was created in Missive
from_field*
Sender. Email channel: object with name, address. Other channels: object with id, name, username. For WhatsApp, see the breaking change note below.
to_fields*
Array of recipients in the same shape as from_field
attachments*
Array of attachment objects (see Attachment properties)
references*
Array of Message-ID strings this message references
subject
Email subject. Email channel only
cc_fields
Array of CC recipients. Email channel only
bcc_fields
Array of BCC recipients. Email channel only
reply_to_fields
Array of Reply-To recipients. Email channel only
email_message_id
Email Message-ID header (wrapped in <>). Email channel only
in_reply_to
Array of Message-ID strings this message replies to. Email channel only
external_id
Provider message ID. Non-email channels only (SMS, Messenger, etc.)
author
User who authored the message (for outgoing)
body
HTML body of the message. Only returned by Get a Message
account_author
Legacy alias for from_field. Only returned for SMS, Messenger, and Twitter messages
account_recipients
Legacy alias for to_fields. Only returned for SMS, Messenger, and Twitter messages