# AI Agent Analytics And Compliance > Use compact outcome reports and privacy-conscious diagnostics, then change real Mailrith resources through their task permissions and normal safeguards. - Human page: https://mailrith.com/developers/agent-analytics-and-compliance - Markdown page: https://mailrith.com/developers/agent-analytics-and-compliance.md - Category: AI Agent Platform - Reading time: 12 min read - Last updated: 2026-08-24 - Related keywords: AI Agent Analytics And Compliance, AI Agent Analytics And Compliance developer docs, AI Agent Platform, AI Agent Platform developer docs, Mailrith developer docs, Mailrith public API, Build A Safe Closed Loop, Run Bounded Analytics Reports, Inspect Failures Without Scraping Mailrith, Manage Subscriber Subscriptions And Consent Evidence, AI Agent Architecture And Security, AI Agent Quickstarts, API Reference ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What This Guide Covers Build a bounded analytics, diagnostics, and Subscriber subscription loop without bypassing Mailrith safety controls. ## Build A Safe Closed Loop Mailrith lets an agent read outcomes, inspect a problem, and draft or change the actual Mailrith resource needed for the next step. Every operation requires the credential's current Permissions and passes through normal suppression, consent, preflight, and delivery rules. Analytics uses its own read permission. Diagnostics use the read permission for the Broadcast, Sequence, Automation, or Subscriber being inspected. Subscriber status and consent evidence use the Subscribers resource permissions. - Analytics reads compact rollups instead of scanning raw Subscriber events. - Diagnostics return bounded operational details and omit Subscriber email addresses and Automation input or output snapshots. - Agents can keep reasoning in their own task context and save only real Mailrith drafts or changes. ## Run Bounded Analytics Reports Create a report with `POST /v1/analytics/reports`. A range can cover at most 366 days, include at most 20 source IDs, and use at most two supported grouping fields. Reports through 31 days complete inline. Longer reports are queued. Repeating the same query within 24 hours reuses the cached report instead of creating another stored result. Supported grouping fields are `source_type`, `source`, `message`, `provider`, and `day`. `source` means the selected Broadcast, Sequence, or Automation ID. Provider grouping is available only when `source_types` contains only `broadcast` and the request names no more than 20 Broadcast source IDs. Segment, Tag, and recipient-domain grouping are not available because the current compact rollups cannot provide those dimensions accurately without adding high-cardinality data. Provider cost is also unavailable. Provider identity and readiness remain available in Broadcast diagnostics when a send run provides them. A completed report contains no more than 100 aggregate rows. A response page contains no more than 50 rows. Follow `pagination.next_cursor` with the `starting_after` query parameter. Do not construct or change the cursor. - Delivered: recipients accepted into the compact delivery rollup. - Opened and clicked: unique delivered-recipient tracking outcomes recorded in the daily rollup. - Unsubscribed: unique delivered-recipient unsubscribe outcomes recorded in the daily rollup. - Bounced and complained: Subscribers whose latest source event occurred inside the requested period. - Conversion-adjacent: `null` until the workspace has a supported conversion event source. - Delivery and engagement use send-date attribution. Bounce and complaint use event-date attribution. **Create A Seven-Day Comparison** ```json { "from": "2026-07-15", "to": "2026-07-21", "source_types": [ "broadcast" ], "source_ids": [ "broadcast_123" ], "group_by": [ "source", "day" ], "compare_previous": true } ``` ## Inspect Failures Without Scraping Mailrith Use the diagnostics endpoints to inspect recent Automation runs, Sequence failures, Broadcast delivery state, or one Subscriber's compact activity. Automation results include run status, timing, attempts, step status, and a redacted failure. Sequence results include the failed message, attempt count, and terminal state. Broadcast results include selection totals, provider readiness, up to 20 structured delivery reasons, and a current seven-day engagement comparison. Subscriber diagnostics cover a 90-day window and return no more than 50 items per category. The response omits the email address and includes only compact consent, suppression, and activity fields needed to understand eligibility. - `GET /v1/diagnostics/automations/{automation_id}/runs` - `GET /v1/diagnostics/automations/{automation_id}/runs/{run_id}` - `GET /v1/diagnostics/sequences/{sequence_id}` - `GET /v1/diagnostics/broadcasts/{broadcast_id}` - `GET /v1/diagnostics/subscribers/{subscriber_id}` ## Manage Subscriber Subscriptions And Consent Evidence A direct public API request cannot make a Subscriber Active without a nested `consent_evidence` object. When no status and no evidence are supplied for a new direct API Subscriber, Mailrith creates the Subscriber as Unconfirmed. Mailrith forms continue to use their own consent and double-opt-in flow. Send `lawful_basis`, `collected_at`, and `evidence_reference`. You may also send `consent_text_version`, an HTTP or HTTPS `source_url`, and a lowercase SHA-256 `technical_evidence_hash`. Keep the full consent text, IP address, user agent, and raw technical evidence in the system responsible for collecting consent. Mailrith rejects those raw fields. Use the Subscribers write permission when changing sending eligibility. Mailrith does not expose a generic privacy-event recorder; use Mailrith's real status operations and your own verified privacy-request workflow. > You remain responsible for deciding which lawful basis applies, keeping evidence for the required period, honoring privacy requests, and confirming that your use of Mailrith follows the laws and promises that apply to your Subscribers. **Reference-Based Consent Evidence** ```json { "email": "person@example.com", "status": "Active", "consent_evidence": { "lawful_basis": "consent", "consent_text_version": "email-v3", "collected_at": "2026-07-21T09:30:00.000Z", "source_url": "https://example.com/signup", "evidence_reference": "consent-ledger:record-42", "technical_evidence_hash": "" } } ``` ## Related Guides - [AI Agent Architecture And Security](https://mailrith.com/developers/agent-security.md): Mailrith uses one public resource model, least-privilege credentials, typed operations, existing delivery safeguards, request IDs, and current-resource verification across every supported agent client. - [AI Agent Quickstarts](https://mailrith.com/developers/agent-quickstarts.md): Start with the Mailrith plugin, the Mailrith Connector, or a scoped MCP connection. Then follow task-based paths for read-only, Broadcast, Sequence, and safe test-workspace workflows. - [API Reference](https://mailrith.com/developers/api-reference.md): The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use the API reference to find exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.