REST API

Endpoints

Draft endpoints

The drafts endpoint lets you create email or SMS drafts that can either be sent immediately or edited and sent from the Missive app. You can create drafts in a new conversation or append them as a reply to an existing one.

Create a draft

POST /v1/drafts

Example:

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

Attributes

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.

references

The references array lets you append a draft to an existing conversation. Given a conversation already exists and includes an email with a Message-ID: <a@a.com> or References: <a@a.com> header, you may add "references": ["<a@a.com>"] to your request so the draft gets appended to that conversation.

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

Chevrons around references are optional. Both ["<some-reference-123>"] and ["some-reference-123"] would reference the same conversation. References must not contain whitespace.

conversation

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

team

team lets you link the draft’s conversation to a team. When a conversation is already linked to team, this field is ignored.

force_team

force_team lets you force a new team even if the conversation is already in another team.

organization

organization lets you scope the search for conversations to ones already associated with an organization. If a new conversation is created and organization is passed, the new conversation will be linked to that organization.

add_users

add_users 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_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_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 Sam",
    "type": "email",
    "delivered_at": 1563806347,
    "updated_at": 1563807320,
    "created_at": 1563807320,
    "email_message_id": "<0f1ab2d8-cd90-4dd1-a861-ef7e31fb3cdd@missiveapp.com>",
    "in_reply_to": [],
    "references": [],
    "body": "<div>A message from Sam</div><br><img style=\"max-width: 100%\" alt=\"inline-image.png\" data-missive-attachment-id=\"81eed561-4908-4738-9a9f-2da886b1de43\">",
    "from_field": {
      "name": "Samwise Gamgee",
      "address": "sam@fellowship.org"
    },
    "to_fields": [
      {
        "name": "Phil Smith",
        "address": "phil.smith@fakemail.com"
      }
    ],
    "cc_fields": [],
    "bcc_fields": [],
    "reply_to_fields": [],
    "attachments": [
      {
        "id": "81eed561-4908-4738-9a9f-2da886b1de43",
        "filename": "inline-image.png",
        "extension": "png",
        "url": "https://...",
        "media_type": "image",
        "sub_type": "png",
        "size": 114615,
        "width": 668,
        "height": 996
      }
    ],
    "conversation": {
      "id": "47a57b76-df42-4d8k-927x-80dbe5d87191",
      "subject": null,
      "latest_message_subject": "A Message",
      "organization": {
        "id": "93e5e5d5-11a2-4c9b-80b8-94f3c08068cf",
        "name": "Fellowship"
      },
      "color": null,
      "assignees": [
        {
          "id": "6b52b6b9-9b51-46ad-a4e3-82ef3c45512c",
          "name": "Frodo Baggins",
          "email": "frodo@fellowship.org",
          "unassigned": false,
          "closed": false,
          "archived": false,
          "trashed": false,
          "junked": false,
          "assigned": true,
          "flagged": false,
          "snoozed": true
        }
      ],
      "assignee_names": "Frodo Baggins",
      "assignee_emails": "frodo@fellowship.org",
      "users": [
        {
          "id": "6b52b6b9-9b51-46ad-a4e3-82ef3c45512c",
          "name": "Frodo Baggins",
          "email": "frodo@fellowship.org",
          "unassigned": false,
          "closed": false,
          "archived": false,
          "trashed": false,
          "junked": false,
          "assigned": true,
          "flagged": false,
          "snoozed": true
        }
      ],
      "attachments_count": 0,
      "messages_count": 1,
      "authors": [
        {
          "name": "Samwise Gamgee",
          "address": "sam@fellowship.org"
        }
      ],
      "drafts_count": 0,
      "send_later_messages_count": 0,
      "tasks_count": 0,
      "completed_tasks_count": 0,
      "shared_labels": [
        {
          "id": "146ff5c4-d5la-3b63-b994-76711fn790lq",
          "name": "Elfs"
        }
      ],
      "shared_label_names": "Elfs",
      "app_url": "missive://mail.missiveapp.com/#inbox/conversations/47a57b76-df42-4d8k-927x-80dbe5d87191",
      "web_url": "https://mail.missiveapp.com/#inbox/conversations/47a57b76-df42-4d8k-927x-80dbe5d87191"
    }
  }
}

Inline images

Inline images markup in the message body HTML contain no src attribute, instead they contain a data-missive-attachment-id attribute with the attachment id. The attachment and its URL are available in the GET response under the attachments key.

Post endpoints

The posts endpoint lets you inject data in any Missive conversation. You can create posts in new conversations or append them to existing ones.

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@missive.com",
        "author_icon": "avatar:philippe@missive.com",
        "color": "#fff",
        "text": "Read your email for the 1st time",
        "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. References must not contain whitespace.

conversation

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

organization

organization lets you scope the search for conversations to the ones already associated with an organization. If a new conversation is created and organization is passed, the conversation will be linked to that organization.

team

team lets you link the post’s conversation to a team. When a conversation is already linked to team, this field is ignored.

force_team

force_team lets you force a new team even if the conversation is already in another team.

add_users

add_users 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_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_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

attachments.fields

Contact endpoints

Contact endpoints let you manage your contacts programmatically.

Create contact(s)

POST /v1/contacts

Payload example:

{
  "contacts": [
    {
      "contact_book": "551b8675-11e9-49c3-aac0-01fb8510d862",
      "first_name": "Philippe",
      "last_name": "Lehoux",
      "starred": true,
      "infos": [
        {
          "kind": "phone_number",
          "label": "mobile",
          "value": "+1 518 777-7777"
        },
        {
          "kind": "email",
          "label": "home",
          "value": "philippe@missiveapp.com"
        }
      ],
      "memberships": [
        {
          "title": "CEO",
          "location": "Québec city",
          "group": {
            "kind": "organization",
            "name": "Missive"
          }
        }
      ]
    }
  ]
}

A successful request will return newly created contacts.

Response example:

{
  "contacts": [
    {
      "id": "5960dcd2-3382-4430-aa70-955a2c62040a",
      "first_name": "Philippe",
      "last_name": "Lehoux",
      "starred": true,
      "contact_book": "db3767be-f506-4bd4-9e8f-b67afa332d44",
      "deleted": false,
      "modified_at": 1556201911,
      "infos": [
        {
          "kind": "email",
          "label": "home",
          "value": "philippe@missiveapp.com"
        },
        {
          "kind": "phone_number",
          "label": "mobile",
          "value": "+1 518 777-7777"
        }
      ],
      "memberships": [
        {
          "title": "CEO",
          "location": "Québec city",
          "group": {
            "id": "f8905b6f-2d13-466a-a2e6-8e3de090a6d1",
            "kind": "organization",
            "name": "Missive"
          }
        }
      ]
    }
  ]
}

Attributes

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

Get all contact books the user has access to. Remember that a contact book id is mandatory when creating a contact programmatically.

Response example:

{
  "contact_books": [
    {
      "id": "6a012cec-c2e2-4e21-91e3-a36dba6930e7",
      "user": "0db31755-adcd-4c51-8346-66bb7194449e",
      "share_with_organization": true,
      "share_with_team": null,
      "share_with_users": [],
      "organization": "2b24d4f0-d082-41c7-9075-d2a34afcfcbd",
      "name": "HR",
      "description": null
    },
    {
      "id": "171ed616-bed2-4781-91b8-bf52459dd9e6",
      "user": "0db31755-adcd-4c51-8346-66bb7194449e",
      "share_with_organization": true,
      "share_with_team": null,
      "share_with_users": [],
      "organization": "2b24d4f0-d082-41c7-9075-d2a34afcfcbd",
      "name": "Production",
      "description": null
    },
    {
      "id": "108e216d-79f9-452c-93b9-4176213d4fdb",
      "user": "0db31755-adcd-4c51-8346-66bb7194449e",
      "share_with_organization": false,
      "share_with_team": null,
      "share_with_users": [],
      "organization": null,
      "name": "My personal book",
      "description": null
    }
  ]
}

Contact group endpoints

Contacts can be grouped in both organizations and groups. Organizations are typically used to map a group of related contacts (businesses). Groups are used to group unrelated contacts, think of groups as labels.

List contact groups

GET /v1/contact_groups

Get all contact groups or organizations linked to a contact book.

Response example:

{
  "contact_groups": [
    {
      "id": "6a012cec-c2e2-4e21-91e3-a36dba6930e7",
      "name": "VIPs",
    }
  ]
}

Params

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 May 20th, 2020