Missive

Missive

Missive is a collaborative shared inbox spanning email, SMS, WhatsApp, Instagram, Messenger, custom channels, and live chat. The data model is built around conversations; everything else (messages, drafts, posts, comments, tasks) lives inside a conversation.

Entity Hierarchy

• Organization — top-level workspace. Most write paths require an organization id.
• Team — a sub-grouping inside an organization, with active_members (notified) and observers (not notified). Teams own team inboxes and can own conversations.
• User — a Missive seat. The API token owner is marked me: true.
• Account — a connected channel (email mailbox, SMS line, WhatsApp number, Messenger page, custom-channel adapter, …). Account ids appear in messages and drafts; the catalog of accounts lives in Missive's Settings, not in a list endpoint.
• Contact book → contact group / contact organization → contact. Contact books are the entry point — contact_book id is required for both contact_groups and contacts list calls.
• Conversation — the unit of triage. Holds messages, comments, drafts, posts, and an array of tasks.
  • Message — actual incoming/outgoing communication.
  • Comment — internal team-only discussion (with @mentions and optional task shape).
  • Draft — outbound message in progress; send immediately via the draft create path with send=true.
  • Post — integration / automation entry. Also the documented way to mutate conversation state.
• Shared label — cross-conversation tag, optionally nested via parent.
• Canned response — reusable email template scoped to organization or user.
• Task — standalone, conversation subtask, or tasked-conversation.
• Hook (webhook) — event subscription; backed by a Missive Rule under the hood.

Workflows

• Read a mailbox: list conversations with at least one of mailbox / shared_label / team_inbox / team_closed / team_all (Missive returns HTTP 400 'You need to paginate at least one mailbox' when all are absent). For each conversation of interest, fetch messages, comments, drafts, and posts via the per-conversation sub-listings. Pull the full body of a specific message via the by-id message fetch.
• Triage: use the post tool with action flags (close, reopen, add_to_inbox, add_to_team_inbox, add_assignees, add_shared_labels, remove_shared_labels, conversation_color, team + force_team) to mutate state — there is no PATCH endpoint on conversations, and the API does not expose an 'archive' parameter at all.
• Reply or send: create a draft. To send immediately, set send=true. To schedule, set send_at to a Unix epoch (mutually exclusive with send=true). To reply to an existing conversation, pass conversation (preferred when you have the id) or references (when matching by email Message-ID). For correct paragraph spacing in HTML bodies, use <div>...</div><div><br></div> instead of <p>...</p>.
• Sync contacts: list contact_books, then for each book paginate contacts (optionally with modified_since for incremental sync and include_deleted for tombstones).
• Manage canned responses: list responses for the user, optionally filtered by organization; create/update via upsert; delete one or many via the batch delete tool.
• Webhooks for automations: subscribe with the create-webhook tool, store the returned id, delete with the delete-webhook tool. There is no list / get for webhooks via the API — visibility lives in Missive's Rules settings UI.
• Analytics: kick off an analytics report (organization + start + end required), then poll for it 5 seconds later and re-poll every 5 seconds until 200. Reports expire 60 seconds after completion. Plan gating applies (Productive plan for any report; Business plan for team / user / label / account filters).

Gotchas

• Conversation listing requires a mailbox filter. mailbox, shared_label, team_inbox, team_closed, or team_all — at least one is mandatory. The API's 'junked' mailbox is what the Missive UI calls 'Spam'.
• Contact groups need both contact_book AND kind. Either alone gives HTTP 400 'Required parameter missing'.
• Contact updates with infos / memberships REPLACE the entire array. Missing items are deleted by Missive. Always read the contact first if you only intend to add one info entry.
• Conversation state mutations go through posts, not through any dedicated PATCH endpoint. There is no 'archive' parameter.
• Sent messages cannot be deleted via the REST API. Only drafts have a delete endpoint. Posts also have a delete endpoint (admin-gated for shared conversations).
• HTML bodies need <div>+<br>, not <p>, for visible paragraph spacing in Missive's renderer.
• Analytics reports are async and short-lived — 60-second expiry after completion; expect 404 until the report is ready.
• Custom-channel message creation is for INCOMING messages. To send outbound mail or chat, use the draft tool with send=true; the custom-channel message endpoint simulates a message arriving from an external system, not one going out.
• Webhook events sometimes look like rules in the Missive UI — the create-webhook tool creates a Missive Rule with a webhook action; deleting via the delete-webhook tool removes that rule.