REST API
Endpoints

Analytics endpoints

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.

Example usage Automatically sync analytics data to your Business Intelligence tool.

Create analytics report

POST /v1/analytics/reports

Payload examples:

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

A successful request will return a response containing the new report id:

{
  "reports": {
    "id": "8441d4a0-a0ad-4f0f-aa9c-1cc881057e42"
  }
}

This id must then be included in a Get report request.

Params

Name * required Description Example
organization* Organization ID string "0d9bab85-a74f-4ece-9142-0f9b9f36ff92"
start* Report period start 1691812800
end* Report period end 1692371867
time_zone Time zone identifier (reference) "America/Montreal"
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.

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.

We recommend fetching a report 5 seconds after its creation and retrying every 5 seconds until a successful 200 response is returned.

Contact endpoints

Contact endpoints let you manage your contacts programmatically.

Example usage 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": [
        {
          "group": {
            "kind": "group",
            "name": "VIPs"
          }
        },
        {
          "title": "CEO",
          "location": "Quebec 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 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
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/id1,id2,id3,...

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

List contact books the authenticated 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
    }
  ]
}

Params

Name * required Default Description
limit 50 Number of contact books returned. Max value: 200
offset 0 Offset used to paginate.

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

List 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 contact groups returned. Max value: 200
offset 0 Offset used to paginate.

Conversation endpoints

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.

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.

Note that a page may return more conversations than limit.

Response example:

{
  "conversations": [
    {
      "id": "6d3c9b1c-7067-4a28-8ea6-ea91340b67cc",
      "created_at": 1654544954,
      "subject": null,
      "latest_message_subject": "Question?",
      "organization": {
        "id": "96cafdc6-ec6a-4439-9b0c-f55a1133b1e7",
        "name": "Conference Badge"
      },
      "color": null,
      "assignees": [],
      "users": [
        {
          "id": "dc3c4104-eced-4206-b532-ef84b331778a",
          "name": "Chad Zemlak",
          "email": "chad@conferencebade.com",
          "unassigned": false,
          "closed": false,
          "archived": false,
          "trashed": false,
          "junked": false,
          "assigned": false,
          "flagged": true,
          "snoozed": false
        }
      ],
      "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,
      "web_url": "https://mail.missiveapp.com/#inbox/conversations/6d3c9b1c-7067-4a28-8ea6-ea91340b67cc",
      "app_url": "missive://mail.missiveapp.com/#inbox/conversations/6d3c9b1c-7067-4a28-8ea6-ea91340b67cc",
      "assignee_names": "",
      "assignee_emails": "",
      "shared_label_names": "",
      "last_activity_at": 1654544954,
      "team": {
        "id": "f36b7570-078e-408e-9cb8-2b4441ad93c0",
        "name": "Team 1",
        "organization": "96cafdc6-ec6a-4439-9b0c-f55a1133b1e7"
      },
      "shared_labels": []
    }
  ]
}

Params

Name Description
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 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 in Assigned to me.
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.
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 to the organization param when passing a shared_label or team_ param.

Get a conversation

GET /v1/conversations/id

Fetch a specific conversation using the conversation id.

Note that 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.

Response example:

{
  "conversations": [
    {
      "id": "6d3c9b1c-7067-4a28-8ea6-ea91340b67cc",
      "subject": null,
      "latest_message_subject": "Question?",
      "organization": {
        "id": "96cafdc6-ec6a-4439-9b0c-f55a1133b1e7",
        "name": "Conference Badge"
      },
      "color": null,
      "assignees": [],
      "users": [
        {
          "id": "dc3c4104-eced-4206-b532-ef84b331778a",
          "name": "Chad Zemlak",
          "email": "chad@conferencebade.com",
          "unassigned": false,
          "closed": false,
          "archived": false,
          "trashed": false,
          "junked": false,
          "assigned": false,
          "flagged": true,
          "snoozed": false
        }
      ],
      "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,
      "web_url": "https://mail.missiveapp.com/#inbox/conversations/6d3c9b1c-7067-4a28-8ea6-ea91340b67cc",
      "app_url": "missive://mail.missiveapp.com/#inbox/conversations/6d3c9b1c-7067-4a28-8ea6-ea91340b67cc",
      "assignee_names": "",
      "assignee_emails": "",
      "shared_label_names": "",
      "last_activity_at": 1654544954,
      "team": {
        "id": "f36b7570-078e-408e-9cb8-2b4441ad93c0",
        "name": "Team 1",
        "organization": "96cafdc6-ec6a-4439-9b0c-f55a1133b1e7"
      },
      "shared_labels": []
    }
  ]
}

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.

Note that a page may return more messages than limit.

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": [],
      "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
        }
      ]
    }
  ]
}

Params

Name Description
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.

Draft endpoints

The drafts endpoint lets you create email, SMS, WhatsApp and Missive Live Chat 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 usage 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
Email
Object with "address" and "name" keys. {"address": "philippe@missiveapp.com", "name": "Philippe Lehoux"}
from_field
SMS & WhatsApp
Object with "phone_number" key, it must match an account number you have access to, formatted as "+" followed by digits only.
An optional "type" key with values of "signalwire", "twilio" or "twilio_whatsapp" needs to be provided when the phone number matches accounts of different types.
{"phone_number": "+18005550199", "type": "twilio_whatsapp"}
from_field
Custom channel
Object with "id", "username" and "name" keys. [{"id": "12345", "username": "@missiveapp", "name": "Missive"}]
to_fields
Email
Array of objects.

Object with "address" and "name" keys.
[{"address": "philippe@missiveapp.com", "name": "Philippe Lehoux"}]
to_fields
SMS & WhatsApp
Array of objects.

Object with "phone_number" key, only one item is allowed and it must be formatted as "+" followed by digits only.
[{"phone_number": "+18005550199"}]
to_fields
Messenger & Instagram
Array of objects.

Object with the "id" key.
[{"id": "1736313053102918"}]
to_fields
Custom channel
Array of objects.

Object with "id", "username" and "name" keys.
[{"id": "12345", "username": "@missiveapp", "name": "Missive"}]
to_fields
Missive Live Chat
Array of one object.

Object with "id", "username" and "name" keys.
[{ id: '123', username: 'phil@acme.com', name: 'Phil [Unverified]' }]
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"}]
account
Custom Channel & Missive Live Chat, Messenger & Instagram
Account ID. You can find this ID in the custom channel, Missive Live Chat settings or Settings > API > Resource IDs. "fbf74c47-d0a0-4d77-bf3c-2118025d8102"
attachments Array containing files, see below for details [{"base64_data": "iVBORw0KGgoAAAANS…", "filename": "logo.png"}]
references Array of strings for appending to an existing conversation. ["<some-reference-123>"]
from_field Object with the "phone_number", "address" or "name" keys, used to match contacts in the Missive sidebar and populate the authors line in the conversation preview {"phone_number": "+4187249887", "name": "Paul"}
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!"
conversation_color HEX color code or "good" "warning" "danger" string "#000", "danger"
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
send_at Timestamp value in Unix time 1684540565
auto_followup boolean, send_at is required when passing true false
body

The HTML/text body of your message. Regular HTML paragraphs tags in Missive will not show the desired spacing.

For instance, to get the expected spacing in between paragraphs you would change this:

<p>Paragraph 1</p>
<p>Paragraph 2</p>

to:

<p>Paragraph 1</p>
<p><br></p>
<p>Paragraph 2</p>
<p><br></p>
send

Set to true to send the draft immediately upon creating it.

send_at

Schedule draft to be sent at a later time. Cannot be combined with send: true.

auto_followup

When auto_followup is true, the scheduled draft to be sent at a later time with send_at will be discarded when there is a reply in the conversation.

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 or SignalWire accounts. For custom channels, you may pass any id, username and name with no restriction.

attachments

The attachments array lets you attach up to 25 files to the draft. The total JSON payload of your request must not exceed 10 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.

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 a message

To send a new message or reply, use Create a draft with the send: true param.

Example:

{
  "drafts": {
    "send": true,
    "subject": "Hello",
    "body": "World!",
    "to_fields": [
      {
        "address": "paul@acme.com"
      }
    ],
    "from_field": {
      "address": "philippe@missiveapp.com"
    }
  }
}

Message endpoints

Create a message

POST /v1/messages

Create an incoming message in a custom channel. Custom channels let users integrate message providers not built-in to Missive.

Example:

{
  "messages": {
    "account": "fbf74c47-d0a0-4d77-bf3c-2118025d8102",
    "from_field": {
      "id": "12345",
      "username": "@philippe",
      "name": "Philippe Lehoux"
    },
    "to_fields": [
      {
        "id": "54321",
        "username": "@missiveapp",
        "name": "Missive"
      }
    ],
    "body": "Hello <b>world</b>!"
  }
}

Attributes

Name * required Description Example
account* Account ID. You can find this ID in the custom channel settings. "fbf74c47-d0a0-4d77-bf3c-2118025d8102"
subject Email channel only:
string
"Hello"
body HTML or text string based on channel message type. "<b>World!</b>"
from_field Email channel:
Object with "address" and "name" keys.

Text or HTML channel:
Object with "id", "username" and "name" keys.
{ "address": "philippe@missiveapp.com", "name": "Philippe Lehoux" }


{ "id": "12345", "username": "@missiveapp", "name": "Missive" }
to_fields Email channel:
Array of objects with "address" and "name" keys.

Text or HTML channel:
Array of objects with "id", "username" and "name" keys.


[{ "address": "philippe@missiveapp.com", "name": "Philippe Lehoux" }]


[{ "id": "12345", "username": "@missiveapp", "name": "Missive" }]
cc_fields Email channel only:
Array of objects with "address" and "name" keys.
[{ "address": "philippe@missiveapp.com", "name": "Philippe Lehoux" }]
bcc_fields Email channel only:
Array of objects with "address" and "name" keys.
[{ "address": "philippe@missiveapp.com", "name": "Philippe Lehoux" }]
delivered_at Message delivery timestamp. If omitted, message is marked as delivered at request time. 1563806347
attachments Array containing files, see below for details. [{ "base64_data": "iVBORw0KGgoAAAANS...", "filename": "logo.png" }]
external_id Unique ID used to identify non-email messages (SMS, Instagram DMs, etc). "some-id-123"
references Array of strings for appending to an existing conversation. ["some-reference-123"]
conversation Conversation ID string for appending to an existing conversation "5bb24363-69e5-48ed-80a9-feee988bc953"
team Team ID string Default based on channel sharing settings: Inbox or Team Inbox
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!"
conversation_color HEX color code or "good" "warning" "danger" string "#000", "danger"
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 Default based on channel sharing settings: Inbox or Team Inbox
add_to_team_inbox boolean Default based on channel sharing settings: Inbox or Team Inbox
close boolean false
attachments

The attachments array lets you attach files to messages. The total JSON payload of your request must not exceed 10 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 message to an existing conversation. Given a conversation already exists and includes a message with external_id: "some-id-123" or references: ["some-id-123"], you may add "references": ["some-id-123"] to your request so the message gets appended to that conversation.

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

conversation

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

team

team lets you link the message’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 message’s conversation.

add_to_team_inbox

add_to_team_inbox lets you move the message’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 message’s conversation to Inbox for everyone having access to the conversation.

close

close lets you close the message’s conversation for everyone having access to the conversation.

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"
      },
      "team": {
        "id": "2f618f9e-d3d4-4a01-b7d5-57124ab366b8",
        "name": "Hobbits",
        "organization": "93e5e5d5-11a2-4c9b-80b8-94f3c08068cf"
      },
      "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.

List messages

GET /v1/messages?email_message_id=Message-ID

Fetch messages matching an email Message-ID.

Response example:

{
  "messages": [
    {
      // Latest message
    },
    {
      // Second-latest message
    }
  ]
}

Message data includes headers, body and attachments in the same format as Get a message.

Most of the time, only one message matches a given Message-ID, as required by email standards. However, non-compliant sender servers may send you multiple messages with the same Message-ID in which case this endpoint will return the latest 10.

Params

Name * required Default Description
email_message_id* The Message-ID found in an email’s header.

Organization endpoints

List organizations

GET /v1/organizations

List organizations the authenticated user is part of.

Response example:

{
  "organizations": [
    {
      "id": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92",
      "name": "Conference Badge"
    }
  ]
}

Params

Name * required Default Description
limit 50 Number of organizations returned. Max value: 200
offset 0 Offset used to paginate.

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 usage 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@missiveapp.com",
        "author_icon": "avatar:philippe@missiveapp.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 color 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. ["<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
reopen boolean true
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.

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.

reopen

reopen lets you prevent closed conversations from reopening when creating a post.

attachments
Name * required Description Example
color HEX color 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 resource "https://myapp.com/a-resource"
image_url Image URL of the attachment "https://myapp.com/a-resource.png"
text Text string "This is text!"
markdown Text string, formatted with Markdown "This is a **bold 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

Responses endpoints

List responses

GET /v1/responses

List responses for the authenticated user.

Response example:

{
  "responses": [
    {
      "id": "75ad834a-9bd6-4008-b9e6-fc9fa2e7770b",
      "title": "A test response",
      "body": "<div>Inline image: <img alt=\"\" title=\"\" width=\"288\" data-missive-attachment-id=\"66d17982-4c83-4e13-a9c5-83cf6065b3da\" data-missive-resizable-image=\"true\" data-missive-image-resolution=\"144\" style=\"max-width: 100%\"></div>",
      "subject": null,
      "organization": "84f876cc-ef7c-41cd-9711-7ab9cf9f26a5",
      "user": null,
      "share_with_team": null,
      "modified_at": 1700150379,
      "to_fields": [],
      "cc_fields": [],
      "bcc_fields": [],
      "shared_labels": ["93f876cc-ef7c-42cd-9711-7ab9cf9f26a4"],
      "attachments": [
        {
          "id": "66d17982-4c83-4e13-a9c5-83cf6065b3da",
          "filename": "image.png",
          "extension": "png",
          "url": "...",
          "media_type": "image",
          "sub_type": "png",
          "size": 99,
          "width": 100,
          "height": 100
        }
      ]
    }
  ]
}

Params

Name * required Default Description
organization null Organization ID
limit 50 Number of responses returned. Max value: 200
offset 0 Offset used to paginate.
Inline images

Inline images markup in the response 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.

Get a response

GET /v1/responses/id

Fetch a specific response using the response id.

Shared label endpoints

List shared labels

GET /v1/shared_labels

List shared labels in organizations the authenticated user is part of.

Response example:

{
  "shared_labels": [
    {
      "id": "b45a00fd-353s-89l2-a487-2465c35c3r91",
      "color": null,
      "name": "Invoices",
      "name_with_parent_names": "Invoices",
      "organization": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92"
    }
  ]
}

Params

Name * required Default Description
organization null Organization ID
limit 50 Number of shared labels returned. Max value: 200
offset 0 Offset used to paginate.

Create shared labels(s)

POST /v1/shared_labels

Payload example:

{
  "shared_labels": [
    {
      "name": "Heroku",
      "color": "#430098",
      "parent": "b45a00fd-353s-89l2-a487-2465c35c3r91",
      "organization": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92"
    }
  ]
}

A successful request will return newly created shared labels.

Response example:

{
  "shared_labels": [
    {
      "id": "6960dfv2-4382-4230-aa70-933a1c62040b",
      "name": "Heroku",
      "name_with_parent_names": "Invoices/Heroku",
      "color": "#430098",
      "parent": "b45a00fd-353s-89l2-a487-2465c35c3r91",
      "organization": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92"
    }
  ]
}

Attributes

Name * required Description Example
name* Label name string "Heroku"
organization* Organization ID string "0d9bab85-a74f-4ece-9142-0f9b9f36ff92"
color HEX color code "#430098"
parent Parent shared label ID string "9b45a00fd-353s-89l2-a487-2465c35c3r91"
share_with_organization Boolean true
share_with_team Team ID string nil
share_with_users Array of user ID strings []
visibility Either 'organization' or 'delegates' string 'organization'
share_with_organization
share_with_team
share_with_users

Users affected by either of those params will have access to all the conversations in the label.

visibility

The visibility param controls whom the label is visible to. If the value is organization, everyone in the organization can use the label. If the value is delegates, only admins and auto-shared users (users affected by share_with_users, share_with_organization, share_with_team) can use the label.

Team endpoints

List teams

GET /v1/teams

List teams in organizations the authenticated user is part of.

Response example:

{
  "teams": [
    {
      "id": "d75aecb6-96a2-4b5f-afa6-19d1916052ea",
      "name": "Sales",
      "organization": "0d9bab85-a74f-4ece-9142-0f9b9f36ff92"
    }
  ]
}

Params

Name * required Default Description
organization null Organization ID
limit 50 Number of teams returned. Max value: 200
offset 0 Offset used to paginate.

User endpoints

List users

GET /v1/users

List users in organizations the authenticated user is part of.

Response example:

{
  "users": [
    {
      "id": "a41a00fd-453d-49d7-a487-9765c35a3b70",
      "me": true,
      "email": "philippe@missiveapp.com",
      "name": "Philippe Lehoux",
      "avatar_url": "https://...",
    }
  ]
}

Params

Name * required Default Description
organization null Organization ID
limit 50 Number of users returned. Max value: 200
offset 0 Offset used to paginate.


Last updated on Feb 13th, 2024

Need more specific answers?

Contact us via our Help Center