Skip to content
nofeb

Audit what an email agent did

Every mutating call through the API, MCP or the console, and every hold, denial, rule action and approval nofeb makes on its own, is written to an append-only audit log with the actor, key, action, target, outcome, status, IP address and request id. Read it with GET /v1/audit using a key that holds audit:read, filtered by actor, action (send.* for a prefix), target and outcome, or stream it out with GET /v1/audit/export as JSON Lines.

Checked against the engine on .

What do you need?

  • A key with the audit:read scope (agent keys do not get it by default)
  • Somewhere to keep exports, if you archive them: a SIEM, a bucket or a log pipeline

Steps

  1. 1. Give the reviewer a read key

    audit:read is separate from everything an agent needs, so the agent cannot read or prune its own trail. A key bound to one inbox reads only that inbox's entries, which suits a customer-facing view in a multi-tenant product.

  2. 2. Ask what happened

    Entries come newest first in pages of up to 500, over a window of up to 366 days (the last 30 by default). Filter by actor (an actor or key id), action (an operation id such as send_message, or an engine action such as send.held; a trailing * matches a prefix), target and outcome (ok, denied, failed or held).

    Everything that was denied or held for one key last week
    curl "https://api.nofeb.com/v1/audit?actor=key_…&action=send.*&from=2026-09-25T00:00:00Z&limit=100" \
      -H "Authorization: Bearer $AUDIT_KEY"
    
    { "entries": [ { "id": "aud_…", "at": "2026-09-30T14:02:11Z",
        "actor": { "kind": "key", "id": "key_…", "key_id": "key_…" },
        "action": "send.held", "target": "snd_…", "outcome": "held",
        "inbox_id": "inb_…", "via": "engine", "request_id": "req_…", … } ],
      "next_cursor": "…" }
  3. 3. Follow one send end to end

    Filter by target=snd_… to see the submission, the hold and its reason, the notification to an approver and the decision, each with who made it. Every API response carries an x-request-id header, and the matching entry records the same id, so a support ticket that quotes a request id leads straight to its entry.

  4. 4. Export for retention or a SIEM

    The export takes the same filters and streams JSON Lines, oldest first, day by day, so a nightly job can append yesterday's entries to wherever you keep records.

    Yesterday as JSON Lines
    curl "https://api.nofeb.com/v1/audit/export?from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z" \
      -H "Authorization: Bearer $AUDIT_KEY" > audit-2026-10-01.jsonl

Who counts as an actor?

Each entry's actor has a kind: key for an API key, oauth for an app a person connected (naming that person), human for the webmail, console for the console (naming the console user), slack and email_link for external approvers, rule for a rule's own actions, and system for the server. via says whether the call came over REST, MCP, the console's control API or from the engine itself.

Reads are not recorded; the log is about changes and decisions. Events carry an actor too, so a webhook consumer can tell an agent's metadata write from a person's without querying the log.

Frequently asked questions

Can an AI agent delete its own audit trail?

No. The log is append-only, there is no call that edits or deletes an entry, and agent keys do not hold audit:read unless you grant it.

Does the audit log include what the server decided on its own?

Yes. Holds, denials, list and rule rejections, rule-generated sends, approver notifications and external approvals are written as engine actions beside the API calls.

How do I prove who approved an email?

Query the audit log for the send id. The decision entry names the approver: an API key, a console user, a Slack user or an email link.

Status of everything on this page

Every capability named above, with its status as reconciled against the engine.

CapabilityWhat it doesStatus
Append-only audit log Every change made through the API, MCP or the console, and every hold, denial, rejection and approval the server makes on its own, recorded with the actor, key, operation, target, outcome and request id. Query it with filters and cursors, or export it as JSON Lines. Shipped
Human approval of held sends A held send waits with status awaiting_approval until a human approves or rejects it; both steps emit events. The approval queue lists every held send with its recipients (each marked if new to the conversation), the reasons it was held and who submitted it. Approving needs the separate send:approve scope, which keys from agent self-signup never hold, so an agent cannot approve its own send. Shipped
Approvals in Slack and by email link Approve or reject a held send from a Slack message with Approve and Reject buttons, or from a signed, single-use, expiring link in an email. Slack requests are verified with your app's signing secret and can be limited to named people; the email link decides only on an explicit click, so link scanners cannot approve. Shipped
Scoped API keys Keys bound to the organization, one pod or one inbox, holding only the scopes they are given. A key cannot mint a key wider than itself. Shipped
MCP sign-in with OAuth MCP clients connect by signing in instead of pasting a key: OAuth 2.1 with discovery, dynamic client registration, client ID metadata documents, PKCE, tokens bound to the MCP server, refresh-token rotation and immediate revocation. A person approves the scopes, and optionally one inbox, in the console, and can disconnect the app at any time. API keys keep working beside it. Shipped