DocumentationView as .md

ReplyLayer documentation

ReplyLayer is an email platform for AI agents. It gives an agent a real, scoped mailbox it can send from and receive on over a REST API, the rly CLI, an MCP server, and TypeScript / Python SDKs — with security scanning on every message in both directions. It is built for transactional, operational, and reply-driven email, not bulk or marketing sending.

This is the human-facing documentation tree. If you are wiring an agent to the contract directly — message lifecycle, scan verdicts, send gates, typed errors — the agent documentation is the companion tree.

Getting started

  • Quickstart — Install the rly CLI, get an API key, create a mailbox, and land your first scanned send to the email success simulator in about a minute.
  • Authentication — How ReplyLayer API keys work — the rly_live key format, admin vs agent roles, Bearer-vs-session auth, session-only surfaces, and safe create-verify-revoke rotation.

Guides

  • Email simulator — Test outbound delivery, bounce and complaint webhooks, plus inbound scanning and quarantine, without sending to a real recipient.
  • Do-not-contact list (suppressions) — How the suppression list gates every send, when to add addresses yourself, and the add / list / remove contract across API, CLI, SDKs, and MCP.
  • Webhooks — Receive signed callbacks for inbound mail and outbound state changes — setup, signature verification, the retry and auto-disable model, PII redaction, and rotation.
  • Recipient allowlist (mailbox containment) — How per-mailbox allowlist mode contains outbound sends — opt-in restriction, admin-only mutations, wildcard domains, thread-reply bypass, and agent-send containment.
  • Inbound firewall (sender allowlist + blocklist) — Gate incoming email by sender with per-mailbox allowlist mode, an account-wide blocklist, the releasable firewall_blocked state, and verified-reply bypass.
  • Scheduled send (send later) — Schedule an email for a future time. ReplyLayer holds the draft and re-runs the full send-time gate stack at dispatch, so policy changes are always honored.
  • Sub-addressing and secure replies — Route replies back to the exact agent instance that opened a thread using plus-addressing, and how ReplyLayer's tamper-evident secure-reply headers protect those threads.
  • Attachments (receiving and sending) — How inbound attachment exposure tiers work — metadata, text previews, and raw downloads — and how to send files with the upload, scan, then attach flow.
  • Content scanning — How ReplyLayer scans inbound and outbound email, when a message is quarantined versus delivered with a finding, and what releasing held mail actually does.
  • Custom domains (bring your own domain) — Send and receive from your own subdomain by adding ReplyLayer's DNS records at your provider — the create flow, the records table, verification states, and health.

Clients

  • CLI (rly) — Install and run the rly command-line client — npm/pipx setup, credential storage, a tour of the everyday commands, config, and verifying signed release artifacts.
  • SDKs (TypeScript & Python) — Install and use the official TypeScript and Python SDKs — client setup, your first send, safe idempotent retries, webhook signature verification, and typed errors.
  • MCP server — Connect an MCP client to ReplyLayer two ways — the hosted /v1/mcp streamable-HTTP endpoint or the local stdio server — with copy-paste client config.

Platform

  • Tiers, quotas, and sandbox limits — Per-tier daily send caps, the sandbox trial restrictions, the GET /v1/accounts/quota preflight, and the RATE_LIMITED 429 contract when you hit your cap.

API reference

  • Messages API — Per-operation reference for the Messages resource — send, reply, read, list, long-poll, search, lifecycle (release/block/report/delete), human review, and read/star markers.
  • Drafts API — Draft CRUD, the scan-then-review-then-send flow, scheduled and asynchronous dispatch, and release-and-send for drafts held by a send-time scan.
  • Mailboxes API reference — CRUD and per-mailbox policy operations — scanner policy, PII delivery mode, attachment exposure, sender/firewall mode, agent-send containment, and instruction-trust tightening.
  • Attachments API — REST reference for reading inbound attachments (text previews, raw byte download) and staging outbound attachments through single-use upload handles.
  • Webhooks API reference — HTTP reference for managing webhook endpoints — create, list, update, delete, rotate the signing secret, send a test event, and list or retry deliveries.
  • Suppressions API reference — Per-operation contract for the do-not-contact list — list, add, bulk-add, and remove, with actor metadata, domain patterns, idempotency, and complaint-lock (409) semantics.
  • Recipient allowlist API — Recipient allowlist CRUD, blocked-send-attempt logs, and sandbox verified-recipient endpoints — methods, auth, request and response shapes, and a per-operation classification.
  • Threads API — List and read email threads, and continue a conversation with a thread-scoped send — request fields, response shapes, error codes, and per-operation classification.
  • Account API reference — Per-operation reference for the account resource — programmatic signup, send-budget quota, usage & trust, malicious-link-scanning opt-in, data export, and account deletion.
  • Inbound sender policy (firewall) API — Per-resource reference for the inbound firewall — sender-policy mode, per-mailbox allowlist, account-wide blocklist, blocked-attempt log, and message release.

Machine-readable index

  • llms.txt — a plain-text map of this documentation for agents and automated clients, with absolute links.
  • OpenAPI specification — the generated OpenAPI 3.0 document for the customer REST API.