API Documentation


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

Example Each time someone pushes code to Github, create a post that lists the commits.
A post created from a Github webhook

Create a post

POST /v1/posts

Basic example:

  "posts": {
    "conversation": "00f78fe9-f11a-4b4e-a502-67e6138d3b0f",
    "notification": { "title": "A title", "body": "A body" },
    "username": "Missive",
    "username_icon": "",
    "attachments": [
        "author_name": "Philippe Lehoux",
        "author_link": "",
        "author_icon": "",
        "color": "#fff",
        "text": "Read your email for the 1st time",
        "timestamp": 1511540318


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 ""
conversation_icon Image used as the icon in the conversation list ""
conversation_subject string "New user!"
conversation_color HEX code or "good" "warning" "danger" string "#000", "danger"
text Main message of a post "This is a post!"
markdown Main message of a post, formatted with Markdown "This is a **post**!"
notification* Object with the "title" and "body" keys, used to render a notification {"title":"A title", "body": "A body"}
attachments Array containing attachment objects, see below for details [{"text": "This is an attachment!"}]
references Array of references 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"
add_users Array of user ID strings ["7343bccf-cf35-4b33-99b0-b1d3c69c5f5c"]
add_shared_labels Array of shared label ID strings ["9825718b-3407-40b8-800d-a27361c86102"
remove_shared_labels Array of shared label ID strings ["e4aae78f-e932-40a2-9ece-ed764aa85790"]
add_to_inbox boolean false
add_to_unassigned boolean false
  • 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.

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: <> or References: <> header, you may add "references": ["<>"] 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.


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 lets you scope the search for conversations to the ones already associated with an organization. If a new conversation is created and organization is passed, the conversation will be linked to that organization.


add_users is only used when a new conversation is created. It determines users who will have access to the new conversation. When providing add_users, the organization field is required.

add_shared_labels, remove_shared_labels

add_shared_labels and remove_shared_labels let you manage shared labels that are applied to the post’s conversation.

add_to_inbox, add_to_unassigned

add_to_inbox and add_to_unassigned let you move the post’s conversation to Inbox or Unassigned for everyone having access to the conversation.

Name * required Description Example
color HEX code or "good" "warning" "danger" string "#ccc", "danger"
pretext Text string "This is a pretext!"
author_name Attachment author name "User - Phil"
author_link URL linking to the author ""
author_icon Image URL of the attachment author ""
title Attachment title "This is a title!"
title_link URL linking to the attachment ressource ""
image_url Image URL of the attachment ""
text Text string "This is text!"
timestamp Integer value in Unix time 1512395766
footer Text string "This is a footer!"
footer_icon Image URL of the attachment footer ""
fields Array containing of field objects, see below for details [{"title": "Paying customer","value": "yes"}]
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

Last updated on July 4, 2018

Need more specific answers?

Contact us via our Help Center