# AI Agent Analytics And Compliance > Use compact outcome reports and privacy-conscious diagnostics, then save evidence-backed recommendations and reference-only experiments that still pass through permissions, preview, policy, and approval. - 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-07-22 - 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, Record Consent Evidence And Privacy Events, Turn Evidence Into A Checked Action Plan, Use Recommendation-Only Experiments, 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, consent, recommendation, and experimentation loop without bypassing Mailrith safety controls. ## Build A Safe Closed Loop Mailrith lets an agent read outcomes, inspect a problem, save a recommendation, and turn that recommendation into the normal action preview. A recommendation never executes its proposed request. The same workspace permissions, policy, approval, suppression, consent, preflight, and delivery rules still apply. Use separate permissions for analytics, diagnostics, consent, recommendations, and experiments. Start with read permissions. Add recommendation or experiment drafting only when the client needs to save work, and add consent-event permission only to a trusted system that owns the matching privacy workflow. - 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. - Recommendations store evidence and a proposed request, but cannot execute it. - Experiments remain recommendation-only and do not store per-Subscriber assignments. ## 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`, `campaign`, `message`, `provider`, and `day`. 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": [ "campaign", "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, compliance, 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}` ## Record Consent Evidence And Privacy Events 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 `POST /v1/subscribers/{subscriber_id}/compliance-events` for consent withdrawal, erasure request or completion, processing restriction, objection, or privacy-request completion. This high-impact operation requires consent permission and exact approval. Its webhook contains stable IDs, the event type, time, and optional external evidence reference. It does not contain the Subscriber email address or raw evidence. > 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": "" } } ``` ## Turn Evidence Into A Checked Action Plan Create a recommendation with `POST /v1/recommendations`. Include the exact public operation ID, method, path, optional body, up to 10 compact evidence items, confidence from 0 to 1, expected effect, and risk. Requests and evidence are size-limited, visible only to the credential that created them, and expire after 30 days. The create response says `execution_available: false`. When the recommendation is still useful, call `POST /v1/recommendations/{recommendation_id}/plan`. Mailrith rechecks the credential's current permissions, matches the stored request to the current public contract, runs preview and workspace policy, and creates the normal action plan. Approval and execution remain separate steps. ## Use Recommendation-Only Experiments Experiments support subject, content, timing, and segment variations for a Broadcast, Sequence, or Automation source. Store two to five variant references and SHA-256 digests, not duplicate message bodies or per-Subscriber assignments. Every experiment requires at least 100 observations per variant and at least one hour before a winner can be recorded. A decision must include aggregate evidence for every variant. Fixed safeguards keep complaint and unsubscribe limits, consent, suppression, and frequency rules outside the optimization goal. Phase 7 experiments are always `recommendation_only`. Recording a winner adds evidence and closes the experiment; it never changes or sends a campaign automatically. ## 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, exact action approval, existing delivery safeguards, and compact redacted activity across every supported agent client. - [AI Agent Quickstarts](https://mailrith.com/developers/agent-quickstarts.md): Follow four task-based paths for a five-minute read, campaign drafting, an exact approval-based live send, and isolated sandbox testing without giving an agent broad workspace control. - [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.