Messaging Hub Integration

skill

Read, create, and update Messaging Hub records through its REST API using an org Integration row.

Download .md

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.