> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendrealm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent messaging and project operations

> Author messaging workflows and review consequential changes through scoped MCP tools and durable execution receipts.

Provider credential setup can be enabled separately with `MCP_PUSH_CREDENTIALS_ENABLED=true`. This exposes only FCM, APNs and Web Push configuration to keys with `push_providers.write` and the provider-management role; messaging and administration can remain disabled. Check `account_get.credential.features.push_credentials` and `project_get.capabilities.push.apps.configure_provider_credentials`. If the switch is omitted, existing messaging-enabled deployments retain provider setup; an explicit false disables it.

Phase 2 is independently controlled by `MCP_MESSAGING_ENABLED`. Tool discovery and `project_get` show the operations available to the current personal key. Existing keys receive **no new scopes automatically**. Owners select new permissions through Account → Personal API Keys; current membership, project grants and role capabilities still apply. Billing, plans, payments, credits, invoices and subscription management are excluded.

Use `account_get`, `teams_list`, `projects_list({team_id})` and `project_get({project_id})`. Every project tool requires `project_id`. The SDK uses its explicit `projectId` option; HTTP calls use `X-Sendrealm-Project-Id`. Choose UUIDs returned by discovery, including the push app's `id` rather than its public device-SDK ID for the new project operations.

## Author, preview, commit, inspect

Email, push and cross-channel campaigns remain safe drafts while editing. Inspect effective targeting, renderability, sender/provider setup and exact reachable counts before preparing delivery. Empty audience selections never mean everyone. `all_contacts` is explicit and still respects subscription and suppression policies. Cross-channel targeting changes use `cross_channel_campaigns_update` to synchronize both channels atomically; conflicting parent/channel definitions block delivery.

1. Create/edit templates or campaign drafts. Read detailed content before merging edits. `messages` replaces the complete locale list; omitted draft fields remain unchanged.
2. Preview the content and recipients. Use published, owned template versions for delivery; their content is materialized into the existing delivery pipeline.
3. Call the domain-specific `<operation>_prepare` tool. Read the exact saved input, recipient counts, readiness and consequential effects. Preparations expire after ten minutes and bind the actor, key, grant version, project and resource versions.
4. Commit that operation with **only** `project_id`, `prepared_action_id` and a stable `idempotency_key` (plus optional response mode). Changed inputs require a new review. Template/automation lifecycle tools also retain their existing resource `id` argument.
5. New project operations return a durable receipt, usually `pending`. Poll `project_operations_get({project_id,id})` using `poll_after_ms`. `completed` confirms the requested operation completed, such as entering campaign review; it does not mean every recipient received a message.

Sending uses the existing spam-review/scheduling pipeline. `campaigns_send` and its push/cross-channel equivalents request the earliest reviewed delivery, currently scheduled at least five minutes ahead. They do not bypass review. Cancellation is supported before processing; sent messages cannot be recalled. Campaign archival is limited to drafts.

Repeated commits with the same preparation/idempotency pair return the original receipt. Workers claim an intent once, serialize project dispatch, and recheck authorization, readiness and resource state. Scheduled and recipient workers recheck the originating personal key. Changed grants, lost membership, role changes or revocation can stop queued work. A stale preparation requires a new review, never automatic reapproval.

`outcome_unknown` means a worker/provider result could not be confirmed. Inspect the resource and delivery history and reconcile through support. **Do not create another preparation to repeat an uncertain effect.** No automatic external mutation replay occurs.

## Permissions and workflows

| Workflow | Explicit permission | Tools |
| - | - | - |
| Template drafts, history, restoration and assets | `templates.write` | `templates_create`, `templates_update`, `templates_restore`, `templates_assets_*` |
| Publication / archival | `templates.publish` / `templates.delete` | `templates_publish_prepare` → `templates_publish`; delete equivalents |
| Real template test email / push | `templates.test.send` / `push.test.send` | `templates_test_email_prepare` → `templates_test_email`; push equivalents |
| Campaign authoring | `campaigns.draft.write` | Existing email/push draft tools; `cross_channel_campaigns_*` and campaign assets |
| Delivery or cancellation / draft archival | `campaigns.deliver` / `campaigns.delete` | `campaigns_{schedule,send,cancel,delete}_prepare` and commits; push/cross-channel equivalents |
| Automation publication, pause/resume / deletion | `automations.publish` / `automations.delete` | Existing domain-specific prepare/execute tools |
| Live run recovery | `automation_runs.manage` | `automation_runs_cancel_prepare`, `automation_runs_retry_prepare`, then commit; audit reason belongs in preparation |
| Domains and Cloudflare / deletion | `domains.write` / `domains.delete` | Create, verify, settings, transfer, DNS setup/disconnect preparations |
| Push app deletion / channel changes / channel deletion | `push_apps.delete` / `push_channels.write` / `push_channels.delete` | Corresponding prepare/commit tools |
| Provider credentials | `push_providers.write` | `push_providers_configure_handoff` |
| Delivery, production Live Activities, event feed, device events and analytics | `diagnostics.read` | `email_messages_*`, `live_activities_*`, `automation_deliveries_*`, `events_feed_list`, `push_device_events_list`, `project_analytics_get` |

Read-only discovery uses `resources.read`; Cloudflare connection status additionally requires current domain-management capability. Export/import and deletion permissions remain separate. No new billing permissions exist.

Effect-emitting preparations default to `automation_effects: "suppress"`. Explicit `trigger` additionally requires `automations.trigger` and current automation-management capability. The policy and originating action survive campaign queues, delivery records and derived events. Suppression prevents new live runs and waiting-run resumption, including replay. Existing integration-key behavior is preserved.

The dedicated one-device push and owned Live Activity test tools retain their existing explicit test workflow and permissions. A Live Activity start returns a server-issued `test_id`; update/end never accept production activity IDs. New template delivery tests use preparations. Automation sandbox runs remain no-send tests with immutable definitions.

## Credentials and assets

`push_providers_configure_fcm`, `push_providers_configure_apns` and `push_providers_configure_web` apply provider settings directly using write-only inputs and `push_providers.write`. FCM accepts the service-account JSON file contents and Android package name; APNs accepts the `.p8` PEM, key ID, team ID, bundle ID and environment. The existing dashboard validation applies. Credentials are never returned or staged in preparations/receipts. Inspect `push_providers_list` afterward. `push_providers_configure_handoff` remains an optional browser setup path. `domains_cloudflare_authorize` returns a dashboard link for OAuth authorization; poll `project_handoffs_get` afterward. OAuth callback codes remain in the browser. Cloudflare's provider authorization is separate from MCP authentication; MCP OAuth remains deferred.

Asset tools return a Sendrealm-controlled `upload_url` and `file_key`. Upload the file bytes with PUT, then call the matching finish tool with that exact key and resource ID. Arbitrary remote fetches are not supported. Configuration handoffs select and validate the intended project before loading its app/domain.

Channel upsert follows dashboard replacement semantics: omitted nullable configuration is cleared; importance defaults to `high`, vibration to `true`, visibility to `public`, and `is_default` to `false`. Retrieve channels before preparing edits.

## SDK example

```ts theme={null}
const client = new Sendrealm({ apiKey: process.env.SENDREALM_API_KEY, projectId });
const preparation = await client.projectOperations.campaignsSchedulePrepare({
  id: campaignId,
  delivery_at: '2030-01-01T12:00:00Z',
  timezone: 'UTC',
  automation_effects: 'suppress',
});
// Review preparation.effects with the customer before this commit.
const receipt = await client.projectOperations.campaignsSchedule({
  prepared_action_id: preparation.prepared_action_id,
  idempotency_key: customerApprovedRequestId,
});
const state = await client.projectOperations.projectOperationsGet({ id: receipt.id });
```

New SDK methods disable automatic mutation retries even when a client has a global retry policy. List methods preserve pagination metadata and support `getNextPage()`. Preserve filters and opaque cursors; automation deliveries paginate the combined email/push timeline with keyset bounds. MCP lists/diagnostics default to concise output; use detailed output to inspect message content or traces. Structured errors retain safe field issues, request IDs and retry guidance.

These are ordinary MCP tools over hosted Streamable HTTP and local stdio. Optional MCP Tasks, sampling or elicitation are not required. Local fixture tests exercise protocol compatibility; vendor-specific client testing is described in [MCP compatibility](https://docs.sendrealm.com/tutorials/mcp-client-compatibility.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.