Documentation

Read a shared inbox from your app

A Host app can read the mail of one shared inbox when an org admin grants it. The app reads a single email or a whole thread. It cannot send mail, change it or mark it read.

The grant

An inbox is granted by name: shared_inbox:<inbox id>. Only an org admin can add one, and the inbox must belong to the app's organisation.

waymaker host apps update <app-id> --commander-permissions "team_ids,shared_inbox:<inbox-id>"

From an agent, use the MCP tool host_app_update with commander_permissions: ["team_ids", "shared_inbox:<inbox-id>"].

The list replaces what the app had, so include the names it already holds.
* does not include inboxes. An inbox is only ever granted by name, one at a time.
Removing the grant does not need an admin.
When an inbox is archived, the app can no longer read it.

Get inbox ids with waymaker shared-inboxes list or the MCP tool commander_shared_inbox_list.

Calling it

The app calls its context API with POST https://apps.waymakerone.com/functions/v1/host-context-api. Send JSON { "action": "...", "data": { ... } } and authenticate in one of two ways:

The app acting as itself: Authorization: Bearer $WAYMAKER_CONTEXT_KEY, the app's own context key. The key names its app, so X-App-Id is not needed.
A person signed in to the app: Authorization: Bearer <their token> together with X-App-Id: <the app's id>.

The older X-API-Key with a hand-set WAYMAKER_API_KEY still works for now but is deprecated; see moving off it.

When a person's token is used, they must also be able to open that inbox in Commander. The app's grant never lets someone read mail they could not already read.

`shared_inbox_get_email`

{ "action": "shared_inbox_get_email", "data": { "email_id": "<email id>" } }

It returns one email (fields below).

`shared_inbox_get_thread`

{ "action": "shared_inbox_get_thread", "data": { "shared_inbox_id": "<inbox id>", "thread_id": "<thread id>" } }

It returns { shared_inbox_id, thread_id, status, emails, truncated }.

emails is oldest first, up to 200.
truncated is true when the thread has more than that.

The fields

Field
`id`, `thread_id`, `shared_inbox_id`, `folder_id`	ids. `folder_id` is `null` for Inbox.
`direction`	`inbound` or `outbound`
`from_email`, `from_name`, `to`, `cc`	addresses
`subject`, `body_text`, `body_html`	the message
`received_at`	ISO timestamp
`assigned_to`	the assignee's user id, or `null`
`read_status`	`unread`, `read` or `replied`
`thread_status`	`open`, `pending`, `resolved` or `archived`
`attachments`	`[{ name, size, content_type }]`: metadata only, never the file

body_html is the sender's HTML. Treat it as untrusted: sanitise it before you render it.

Inline images in body_html point at signed links that work for up to 7 days after the email arrived, and anyone holding the link can open the image. Don't store, log or forward body_html if those images shouldn't travel with it. Use body_text when you don't need the formatting.

Errors

Status	When
`404`	The email or thread does not exist, is in another inbox, or the app (or the person) has no access. These all look the same.
`400`	A required id is missing.
`401`	The app could not be authenticated.