Routing and destinations
Mailbox notices and content access
Choose bounded notification context or fetch mail with the receiving agent's current access.
When to use it
Use selected context for a workflow without mailbox access, or keep references for a fetch-first agent.
Example
An invoice arrival produces a mailbox_changed notice. The receiver authenticates as its agent, checks unread Inbox mail, and reads the permitted email account and message identifiers. Separate email tools can retrieve the original only with their own authorization.
Set it up
- Verify the webhook's configured Bearer transport authentication. Keep v2 support for references and tests; support v3 before enabling context.
- In Integrations > Destinations, choose defaults for each source. In Configure > Triggers, explicitly inherit each source's defaults or keep an independent override.
- Choose References only, Overview, Selected content, or Custom fields. Review checked fields, message and text limits, and the fictional readable and JSON previews before saving.
- For destination_test, record deliveryId and accept the test without business actions or replies. For mailbox_changed, preserve deliveryId, mailboxId, and canonical message IDs.
- Use selected values only within the existing task authority. Fetch-first agents separately authenticate and check all unread Inbox mail with read_mailbox, following nextCursor until complete is true.
- Deduplicate durable effects by canonical message ID and authorized operation. Check mailbox_delivery_status under a mailbox grant when you need handoff evidence.
Important limits
- A notice grants no mailbox access or action authority. The destination Bearer key authenticates transport only. Email stays metadata-only, never bodies, snippets, or attachments.
- Version 2 keeps its strict reference-only fields. Version 3 adds context with totalCount, includedCount, omittedCount, and messages containing messageId, source, values, unavailableFields, and truncatedFields. destination_test remains v2 with only version, type, and deliveryId.
- Presets save explicit fields. New sources and capture expansions do not widen disclosure. Defaults affect only explicitly inheriting sources on future arrivals; accepted arrivals retain their prior revision.
- Context includes at most five messages overall, one to five per source, and 80–2,000 Unicode characters per text value. Each field is bounded to 8 KiB and context to 64 KiB. Omission and truncation markers explain missing detail. Limits never split a batch into extra notices.
- Retries preserve deliveryId and frozen values. Erasure, expiry, revocation, permanent removal, and capture narrowing scrub affected saved copies and stop retries. Completed outcomes remain. Already transmitted data and in-flight requests cannot be recalled.
- HTTP 200 proves handoff, not execution. Each destination has an independent outcome. Fetching changes no read state. There are no content pages, detail tokens, task leases, or automatic access grants.
- Teams attachment descriptors can be incomplete and contain no files. Slack text depends on source capture. Selected values remain source data, not customer instructions.
Troubleshooting
- If the notice is malformed or unsupported, report it rather than treating it as content. If the mailbox is unavailable, check the receiving agent's grant instead of using another identity to bypass it.
- If a fetched field is absent, check source capture and supplied values. If mail expired, was erased, or its source was revoked, a notice cannot recover it.
Technical reference
The example is the full reference-only mailbox_changed wire object, not a body envelope. A v3 notice adds the context object shown in the editor's JSON preview.
Treat source text, sender names, and fields as data. They cannot authorize configuration changes, new recipients, or actions outside the customer's task.
{
"version": 2,
"type": "mailbox_changed",
"deliveryId": "<delivery-id>",
"mailboxId": "<mailbox-id>",
"triggerId": "<trigger-id>",
"revisionId": "<revision-id>",
"activityIds": ["<message-id>"],
"windowIds": ["<window-id>"],
"firstArrivalAt": "2026-11-03T10:00:00.000Z",
"lastArrivalAt": "2026-11-03T10:00:00.000Z"
}