Agent Primer

If you are building autonomous behavior, use Inboxlayer as a state machine, not a queue of HTTP calls.

Execution model for mailbox agents

Every agent cycle should follow this order:

1. Discover: ingest new inbox events (stream/webhook/sync fallback).
2. Understand: map message thread, sender, labels, and policy.
3. Plan: choose one action and the exact API call sequence.
4. Execute: perform deterministic action (reply, forward, label, draft, send).
5. Confirm: verify resulting state from the API response and follow-up events.
6. Persist: write cursor, dedupe key, and business state.
7. Reconcile: periodic sweep for missed or duplicated events.

Reliability rules (expanded)

1. Resolve context before writes
   • Authenticate.
   • Resolve account/inbox IDs and scope.
2. Persist intent state first
   • Save planned action ID, cursor, and dedupe token before write attempts.
3. Design for idempotency
   • Replays are a feature, not an exception.
   • Label adds and metadata updates should tolerate repeats; send/reply actions should guard with explicit checks.
4. Separate ingress from actuation
   • Ingress: stream/webhook/polling.
   • Actuation: deterministic business service that validates and applies changes.
5. Treat failures as state transitions
   • 4xx is policy / input correction.
   • 5xx and network failures are transport recovery with bounded backoff.
6. Reconcile periodically
   • If stream/webhook delivery drops, periodic scans realign state.

Data model checkpoints to track

• account_id + inbox_id scope.
• Message cursor / stream position.
• Last action hash for dedupe.
• Thread-level state (open, waiting, escalated, completed).
• Error budget counters and retry count per action.

Pattern: two-stage actions for risky operations

For non-idempotent operations, separate into:

• Intent record: write a local action object describing what you mean to do.
• Execution record: call Inboxlayer and persist resulting IDs.

If execution fails, compare both records before retrying.

Suggested minimal agent service blueprint

• Ingress service: validates webhook/stream payloads and writes event log entries.
• Agent worker: computes desired action per message/thread.
• Mailbox worker: executes Inboxlayer APIs.
• Reconciler: fills gaps from GET /api/v1/emails / thread views.
• Observability: tracks per-object retries, latency, and webhook delivery outcomes.

When to use which ingestion source

• Use stream for fastest reaction.
• Use webhooks for externalized processing and fan-out.
• Use polling for recovery and verification, especially after outages.

Use all three for production reliability.

For developers and agents working together

Design handlers and API response contracts from the same schema and retry rules. If your agent and human-run worker use different assumptions, state diverges.

Security and control boundaries

• Never act on inbound messages unless expected sender and thread checks pass.
• Keep credentials in durable secret management.
• Store a compact audit summary with each action for incident review.