Implementation Flows

These are reusable patterns for production mailbox automation.

Polling flow

1. Authenticate.
2. List inboxes and pick the account-scoped target.
3. Read messages with inbox_id filter and stable pagination.
4. Process each message with deterministic actions.
5. Persist final cursor/message markers.

Good for predictable startup and periodic backfills.

Streaming flow

1. Authenticate.
2. Connect to GET /api/v1/inboxes/{id}/stream.
3. Resume from checkpoint on reconnect.
4. Validate event type and payload contract before acting.
5. Persist state before moving to next event.

Good for low-latency systems and near-real-time agent loops.

Webhook flow

1. Register subscription with POST /api/v1/webhook_subscriptions.
2. Keep a verification mode endpoint for POST /api/v1/webhook_subscriptions/{id}/test.
3. Persist webhook identity and expected signature/endpoint.
4. Use queue-based processing for retries and parallelism.
5. Reconcile with polling on schedule.

Good for distributed orchestration and external event pipelines.

Message action flow

1. Fetch message with GET /api/v1/emails/{id}.
2. Derive intent (reply/forward/send/label/thread).
3. Perform action and capture resulting identifiers.
4. Persist action state and result before continuing.

Delivery reliability flow

1. Send action (for example, draft send or reply).
2. Record outbound intent and provider ID.
3. Monitor webhook/stream outcomes and map status to business state.
4. If delivery status is indeterminate, run targeted polling reconciliation.

Agentic workflow examples

Example A: Support triage

• Ingest inbound email and infer request type.
• If support intent, route to human handoff state and notify queue.
• If automated intent, apply reply/label rules and update thread state.
• Backfill reconciliation each hour to handle webhook lag.

Example B: External onboarding automation

• Poll/stream for OTP or approval email.
• Parse sender + subject pattern + link/OTP markers.
• Persist completed step in account graph before progressing.
• If code fails validation, route message to remediation path.

Example C: Contracted operational loop

• On each outbound send, persist expected delivery state.
• Listen to notification events and update object state (delivered / bounced / failed).
• Trigger retries only for bounded transport failures.

Flow selection guide

• Use polling for bootstrap and integrity checks.
• Use streams for low-latency local loops.
• Use webhooks for distributed services.
• Use hybrid mode for mission-critical automation.

Recovery notes

• Retry idempotent operations only.
• Guard non-idempotent actions with explicit preconditions.
• Reconcile every run with periodic sweeps.
• Escalate recurring business validation failures rather than blind retries.