REST API

Endpoints

Contact endpoints

Contact endpoints let you manage your contacts programmatically.

Create contact(s)

POST /v1/contacts

Payload example:

{
  "contacts": [
    {
      "contact_book": "551b8675-11e9-49c3-aac0-01fb8510d862",
      "first_name": "Philippe",
      "last_name": "Lehoux",
      "starred": true,
      "infos": [
        {
          "kind": "phone_number",
          "label": "mobile",
          "value": "+1 518 777-7777"
        },
        {
          "kind": "email",
          "label": "home",
          "value": "philippe@missiveapp.com"
        }
      ],
      "memberships": [
        {
          "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

infos

The infos array lets you attach data of different kinds to contact: email, twitter, phone_number, facebook, physical_address, url, 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.

memberships.group

Update contact(s)

PATCH /v1/contacts/:id

A successful request will return the updated contacts with embedded memberships and infos.

Payload example:

{
  "contacts": [
    {
      "id": "ee31f156-db95-4158-923f-b26450e0dbf7",
      "last_name": "Lehoux"
    }
  ]
}

Attributes

Contact id is required. See the Create contact(s) section for other attributes. When updating a contact, you may pass only attributes you want to update. In the example above, only the last name will be updated.

There are two exceptions: the infos and memberships arrays. When these are passed, you must pass all of their items, otherwise the missing items will be deleted from the contact. Consequently, to delete items from infos or memberships, simply omit them in the array passed in the request.

List contacts

GET /v1/contacts

This endpoint is useful to sync Missive contacts to another service or to find contacts based on some search term.

Response example:

{
  "contacts": [
    {
      "id": "183382b8-fb70-4a35-bf22-4ebae1450553",
      "first_name": "Arthur",
      "last_name": "Sto",
      "starred": false,
      "contact_book": "487bc080-6631-4edc-830e-1d114eef4ab0",
      "deleted": false,
      "modified_at": 1556200645
    },
    {
      "id": "862aceb8-3553-4644-9300-0312a432315f",
      "first_name": "Zeb",
      "last_name": "Craft",
      "starred": false,
      "contact_book": "487bc080-6631-4edc-830e-1d114eef4ab0",
      "deleted": false,
      "modified_at": 1556200644
    },
    {
      "id": "b40713e2-e790-4c67-9eb3-22e83bd1bdf9",
      "first_name": "Alex",
      "last_name": "Alstorm",
      "starred": false,
      "contact_book": "487bc080-6631-4edc-830e-1d114eef4ab0",
      "deleted": false,
      "modified_at": 1556200643,
      "infos": [
        {
          "kind": "phone_number",
          "label": "work",
          "value": "+1 (418) 717-1066"
        },
        {
          "kind": "custom",
          "custom_label": "Favorite food",
          "value": "Pizza"
        }
      ],
      "memberships": [
        {
          "title": "Project manager",
          "group": {
            "id": "522f8e19-0261-4f8b-b8b1-8d8bb4055569",
            "kind": "organization",
            "name": "Pagac Inc"
          }
        }
      ]
    }
  ]
}

Params

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

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

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.

Note that a page may return more conversations than limit.

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

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.

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

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.

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

send

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

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 5 files to the draft. Each file must be under 5 MB and the total JSON payload of your request must not exceed 10 MB.

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 a reply, add send: true to the create a draft params (POST).

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

attachments

The attachments array lets you attach files to messages. Each file must be under 5 MB and the total JSON payload of your request must not exceed 10 MB.

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.

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

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.

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

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.

attachments

attachments.fields

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

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

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

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

Last updated on June 6th, 2022