Messages and threads

Inbound mail is parsed into messages and grouped into threads using the In-Reply-To and References headers. Your agent reads conversations, not raw MIME.

Threads

List threads of one inbox, or across the whole organization with GET /v0/threads. Lists are newest first and paginated with limit (1 to 100, default 20) and page_token (from next_page_token). GET /v0/threads/{thread} returns the thread with all messages, oldest first.

Messages

Listing returns metadata without bodies, to keep responses small for agents. Getting one message returns:

• text and html: the bodies as sent.
• extracted_text: only the new text, with quoted history and mobile signatures removed. Set by the gatekeeper; prefer it when you pass a message to a model.
• authentication_results: DKIM result for the From domain, spam score and spam action.
• gatekeeper: prompt injection screening, see below.
• attachments: id, filename, content type and size. See Attachments.

The original message is available as RFC 822 from GET .../messages/{message}/raw. The {message} path parameter accepts the message UUID or the RFC Message-ID (URL encoded).

Gatekeeper verdict

Every inbound message is screened for prompt injection before it is marked complete. The verdict is clear or review, with a score and the reasons that triggered it, such as instruction_override, data_exfiltration, role_hijack, fake_tool_markup, hidden_html_text, invisible_unicode or dmarc_fail.

"gatekeeper": {
  "status": "complete",
  "verdict": "review",
  "score": 0.8,
  "reasons": ["instruction_override", "data_exfiltration"],
  "model": "gatekeeper-heuristics-v1"
}

status is pending until screening finishes, unavailable if the screener could not run and timeout if no verdict arrived within 15 minutes. Messages with verdict review also get the review label, and the message.security.review event fires.

Screen before notify

Every organization has the setting screen_before_notify, on by default (see GET /v0/auth/me). Inbound mail is held until the gatekeeper verdict exists, so an agent never reads a prompt injection before screening finishes. The message field screening shows the hold state:

Held messages are left out of message and thread lists, gets, raw downloads and attachments, and cannot be replied to or relabeled. A thread started by a held message stays hidden until one of its messages is visible. The same rules apply to the MCP tools.

# a key with message_read and message_review
curl -s "https://api.mueslimail.com/v0/inboxes/billing@agents.your-domain.eu/messages?include_review=true&label=review"   -H "Authorization: Bearer $MAI_REVIEW_KEY"

# a key with message_release: the message becomes visible and message.received fires
curl -s -X POST "https://api.mueslimail.com/v0/inboxes/billing@agents.your-domain.eu/messages/$MESSAGE_ID/release"   -H "Authorization: Bearer $MAI_REVIEW_KEY"

Labels

The platform sets system labels: received and unread on inbound mail, sent on outbound mail, spam when the spam filter flags a message, review when the gatekeeper does. Add your own labels to track workflow state, and filter any list with ?label=.

curl -s -X PATCH "https://api.mueslimail.com/v0/inboxes/billing@agents.your-domain.eu/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $MAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"add_labels": ["invoice", "approved"], "remove_labels": ["unread"]}'

Endpoints