Guide

API Documentation

Summary

More guides…

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.

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

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

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.

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 Philippe",
    "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 Philippe</div><br><img style=\"max-width: 100%\" alt=\"inline-image.png\" data-missive-attachment-id=\"81eed561-4908-4738-9a9f-2da886b1de43\">",
    "from_field": {
      "name": "Philippe Lehoux",
      "address": "philippe@missiveapp.com"
    },
    "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
      }
    ]
  }
}
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.

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

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

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

Contact endpoints

Contact endpoints let you manage your contacts programmatically.

Example Automatically sync contacts between Missive and your CRM.

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* Organization type. Accepted values: organization, group "organization"
name* string "Missive"

Update contact(s)

PATCH /v1/contacts

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 backup or sync Missive contacts to another service.

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, pass true. Only the contact id and deleted attributes will be returned since the contact data has been deleted from Missive.

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
    }
  ]
}

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 August 22th, 2019

Need more specific answers?

Contact us via our Help Center