# Messaging Hub Integration

## When to use

Use this skill whenever a task requires sending outbound messages (email, SMS, WhatsApp, or other supported channels) on behalf of a tenant, checking the delivery status of a previously sent message, cancelling a message that has not yet gone out, or managing a recipient's consent (unsubscribe/opt-out) state. Do not use it for building or editing message templates, or for any channel configuration that is not exposed by the endpoints below.

## Tools

- `http-get` — read channels, message status, and suppression lists
- `http-post` — create messages (single or batch) and add suppressions
- `http-request` — cancel messages (DELETE) and remove suppressions (DELETE)
- `write-file` — stage large result sets (batch responses, suppression exports) instead of inlining them
- `send-message` — escalate to a human when auth fails or an Integration is missing

All requests go to the Messaging Hub REST API under `/api/v1` on the base URL configured in the org's Integration row for this app. Authentication is injected automatically — never ask for, echo, or hardcode an API key.

## Playbook

1. Discover available channels before sending. Call `http-get` on `/api/v1/channels` to list the channels (own and shared) the authenticated client app can send through. If you need details on one channel (type, provider, status, priority), call `http-get` on `/api/v1/channels/:id`.
2. Send a single message with `http-post` on `/api/v1/messages`, specifying the target channel and recipient. Always pass an `idempotency_key` so retries after a timeout or network error do not create duplicate sends.
3. For multiple recipients in one operation, use `http-post` on `/api/v1/messages/batch` (up to 100 messages per call). After the call, inspect the per-item status in the response — each item is `created`, `replayed`, `conflict`, `suppressed`, or `error`. If the batch response is large, use `write-file` to stage it rather than inlining the full payload in your output.
4. Before manually adding a suppression check whether the recipient is already suppressed by calling `http-get` on `/api/v1/suppressions`, so you do not report a false negative.
5. To honor an unsubscribe or manual opt-out, call `http-post` on `/api/v1/suppressions` with the recipient's contact details and reason.
6. To reverse a suppression (recipient re-consented), call `http-request` with DELETE on `/api/v1/suppressions/:id`.
7. To check a message's delivery outcome, call `http-get` on `/api/v1/messages/:id` (the message's `public_id`), which returns delivery and bounce event history.
8. To cancel a message that has not yet been sent, call `http-request` with DELETE on `/api/v1/messages/:id`. If the response is 409, the message has already been sent or is processing — do not retry the cancellation; instead report the current state.
9. If any call returns 401 or 403, or the org has no Integration configured for Messaging Hub, stop immediately and use `send-message` to notify a human, naming "Messaging Hub" and the scopes needed (channel read, message send, suppression management).

## Failure modes

- 401/403 or missing Integration: stop and escalate via `send-message`; never retry with guessed credentials.
- 404 on a message or suppression: the record does not exist for this tenant (cross-tenant access always returns 404, not 403) — treat as "not found," not as a permissions issue to work around.
- 409 on message cancellation: the message already sent or is processing; report status instead of retrying the delete.
- Batch item status `suppressed`: the recipient is on the consent suppression list — do not attempt to resend that item; surface it to the requester.
- Network/timeout on send: retry `http-post` to `/api/v1/messages` with the same `idempotency_key` rather than omitting it, to avoid duplicate sends.

## Done when

The requested message(s) have been sent, cancelled, or their delivery status retrieved, and any suppression changes are confirmed via a follow-up `http-get`, or the task has been escalated to a human because of an authentication or Integration failure.