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.

12 min read

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

{
  "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.

Reference-Based Consent Evidence

{
  "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": "<lowercase-sha256>"
  }
}

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.