cloudflare-email 0.2.0 → 0.3.0

data/app/views/cloudflare/email/management/mailboxes/show.html.erb

@@ -0,0 +1,86 @@
+<nav class="breadcrumbs" aria-label="Breadcrumb"><%= link_to "Mailboxes", root_path %> <span aria-hidden="true">/</span> <span><%= @mailbox.name %></span></nav>
+<div class="page-heading">
+  <div>
+    <p class="eyebrow">Mailbox</p>
+    <h1><%= @mailbox.name %></h1>
+    <p class="muted"><%= @mailbox.state == "suspended" ? "Receiving is paused for every address in this mailbox." : "Addresses receive mail when both their address and domain are active." %></p>
+  </div>
+  <div class="actions">
+    <span class="badge"><%= @mailbox.state.capitalize %></span>
+    <% if @mailbox.state == "active" && allowed?(:suspend, @mailbox) %>
+      <%= button_to "Suspend mailbox", suspend_mailbox_path(@mailbox.id), method: :post, class: "button button-secondary" %>
+    <% elsif @mailbox.state == "suspended" && allowed?(:resume, @mailbox) %>
+      <%= button_to "Resume mailbox", resume_mailbox_path(@mailbox.id), method: :post, class: "button" %>
+    <% end %>
+  </div>
+</div>
+
+<div class="workspace-grid">
+  <section class="panel" aria-labelledby="messages-heading">
+    <div class="panel-heading"><h2 id="messages-heading">Received messages</h2><p class="muted small">Includes archived messages</p></div>
+    <% if @messages.empty? %>
+      <div class="empty-state"><h3>No messages to show</h3><p>Messages appear here after delivery to an active address.</p></div>
+    <% else %>
+      <ul class="record-list">
+        <% @messages.each do |entry| %>
+          <li class="record-row">
+            <div class="record-content">
+              <% if allowed?(:show_message, @mailbox) %>
+                <%= link_to "Message to #{entry.recipient}", message_mailbox_path(@mailbox.id, message_id: entry.id), class: "record-title" %>
+              <% else %>
+                <span class="record-title">Message to <%= entry.recipient %></span>
+              <% end %>
+              <p class="muted small"><time datetime="<%= entry.created_at.iso8601 %>"><%= entry.created_at.utc.strftime("%b %-d, %Y · %H:%M UTC") %></time></p>
+            </div>
+            <div class="status-list">
+              <span class="badge"><%= entry.read_at ? "Read" : "Unread" %></span>
+              <% if entry.archived_at %><span class="badge">Archived</span><% end %>
+            </div>
+          </li>
+        <% end %>
+      </ul>
+    <% end %>
+    <% if @next_cursor.present? %>
+      <nav class="pagination" aria-label="Message pages"><%= link_to "Next messages →", mailbox_path(@mailbox.id, after: @next_cursor), class: "button button-secondary" %></nav>
+    <% end %>
+  </section>
+
+  <div class="stack">
+    <section class="panel" aria-labelledby="addresses-heading">
+      <div class="panel-heading"><h2 id="addresses-heading">Addresses</h2></div>
+      <ul class="record-list">
+        <% @addresses.each do |address| %>
+          <% receiving = @mailbox.state == "active" && address.state == "active" && address.receiving_domain&.state == "active" %>
+          <li class="record-row address-row">
+            <span class="record-title"><%= address.address %></span>
+            <% if address.has_attribute?(:catch_all) && address[:catch_all] %>
+              <span class="badge">Domain catch-all configured</span>
+            <% end %>
+            <span class="badge"><%= receiving ? "Accepting mail" : address.state == "pending" ? "Pending setup" : "Receiving paused" %></span>
+          </li>
+        <% end %>
+      </ul>
+      <div class="panel-body"><p class="field-help">Pending addresses need routing confirmation from your administrator. Resuming a mailbox preserves each address’s existing setup state.</p></div>
+    </section>
+
+    <% if allowed?(:add_address, @mailbox) %>
+      <section class="panel" aria-labelledby="alias-heading">
+        <div class="panel-heading"><h2 id="alias-heading">Add an alias</h2></div>
+        <div class="panel-body">
+          <% if @domains.empty? %>
+            <p class="muted">No active receiving domains are available. Contact your administrator.</p>
+          <% else %>
+            <%= form_with url: aliases_mailbox_path(@mailbox.id), local: true, class: "stack" do |form| %>
+              <div class="field">
+                <%= form.label :address, "Alias email address" %>
+                <%= form.email_field :address, required: true, maxlength: 254, aria: { describedby: "alias-domains" } %>
+                <p id="alias-domains" class="field-help">Available domains: <%= @domains.join(", ") %>. Messages to this alias will appear in this mailbox.</p>
+              </div>
+              <%= form.submit "Add alias", class: "button" %>
+            <% end %>
+          <% end %>
+        </div>
+      </section>
+    <% end %>
+  </div>
+</div>

data/app/views/layouts/cloudflare/email/management.html.erb

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Mailbox management</title>
+    <%= csrf_meta_tags %>
+    <%= stylesheet_link_tag style_path %>
+  </head>
+  <body>
+    <a class="skip-link" href="#main">Skip to content</a>
+    <header class="site-header">
+      <div class="shell header-content">
+        <%= link_to "Mailbox management", root_path, class: "brand" %>
+        <span class="header-caption">Cloudflare Email</span>
+        <% if host_back_path %><%= link_to "Back to app", host_back_path %><% end %>
+      </div>
+    </header>
+    <main id="main" class="shell" tabindex="-1">
+      <% if flash[:notice].present? %>
+        <div class="notice" role="status"><%= flash[:notice] %></div>
+      <% end %>
+      <% if flash[:alert].present? %>
+        <div class="notice notice-error" role="alert"><%= flash[:alert] %></div>
+      <% end %>
+      <%= yield %>
+    </main>
+  </body>
+</html>

data/docs/activerecord-tenanted.md

@@ -123,6 +123,52 @@ end
 
 See the [mailbox guide](mailboxes.md) for domain activation, address provisioning, sending, and event replay. Your application still authorizes which organization, mailbox, and message each user can access.
 
+## Account emails without an organization
+
+Password resets and portal invitations can belong to the application rather
+than an organization. If you enabled separate tenant databases, give those
+outbox records an explicitly provisioned, host-reserved database too. Keep the
+business record's organization empty; a storage key is not an organization or
+an authorization grant.
+
+For example, after configuring the adapter above, provision and migrate a
+reserved database through your deployment workflow:
+
+```ruby
+# Run once through trusted provisioning, not during sending or event replay.
+TenantRecord.create_tenant("_system_outbound")
+```
+
+Your own service can select storage consistently for sending and feedback:
+
+```ruby
+module EmailStorage
+  SYSTEM_KEY = "_system_outbound".freeze
+
+  def self.with_outbound_storage(organization_key, &block)
+    # The caller must supply an already-authorized organization key.
+    key = organization_key.nil? ? SYSTEM_KEY : organization_key
+    Cloudflare::Email::Tenancy.with(key, &block)
+  end
+end
+
+EmailStorage.with_outbound_storage(nil) do
+  # Prepare/read/reconcile the system email's saved outbox operation here.
+end
+```
+
+Reserve the key against customer selection, include this database in migrations,
+backups and restoration drills, and use the same selection for receipt replay.
+If your shared business records use another database, retain their own durable
+receipt/projection boundary: a tenant commit and a shared commit are not atomic.
+Replay a committed gem operation rather than sending it again.
+
+Never modify the tenancy adapter to treat every missing context as the system
+database. Missing context must continue to fail closed. Your organization's job
+fan-out should enumerate real organizations, not every database file. Applications
+without configured multi-tenancy can keep ordinary system and organization mail
+in their existing single database; this recipe does not enable tenancy by default.
+
 ## What is verified
 
 The optional CI job boots a real Rails application with `activerecord-tenanted`, runs the gem's tenant migrations in two SQLite databases, and checks identical numeric IDs remain isolated. It also verifies context restoration, refusal to create unknown tenant databases, and GlobalID's missing/wrong-tenant rejection. Separate integration tests exercise mailbox ingress, sending, jobs, and delivery-event replay.

data/docs/architecture.md

@@ -14,7 +14,7 @@ durable infrastructure without copying the reference inbox's models and services
 | Shared event intake, tenant correlation and tenant-aware jobs | Durable queue workers, scheduled recovery and schema rollout to every tenant |
 | Structured/raw sending and ActionMailer transport | Compose UI, recipients and send authorization |
 | `Response#accepted?`, plus individual recipient outcomes | Handle partial acceptance without resending accepted recipients |
-| Authenticated v2 ingress and recipient-scoped deduplication | Map trusted recipient to an authorized mailbox |
+| Authenticated ingress (default v2; opt-in v3 [metadata](custom-ingress.md)) and context-scoped deduplication | Map trusted recipient to an authorized mailbox; apply sender and document policy |
 | `MessageId.normalize` and returned provider IDs | Store conversation membership and scope reply lookups |
 | Queue decoding, validation and ACK | Queue/subscription setup and recurring execution |
 | Optional ActiveRecord event receipts, deduplication and indexed replay | Configure queue polling and receipt retention |
@@ -75,7 +75,15 @@ does not automatically provision domains or deploy infrastructure.
 
 Current limitations are deliberate and visible: no provider exactly-once API,
 no automatic resend of uncertain or rejected operations, no multi-provider-ID
-operation (conflicting IDs require review), and no durable inbound Worker buffer.
+operation (conflicting IDs require review). Direct inbound forwarding can reject
+mail during a Rails outage. The default [durable Worker path](../templates/worker/README.md#durable-inbound-delivery)
+commits raw mail and stable envelope context to R2 before returning successfully.
+Queue handoffs and a scheduled recovery pass retry pending mail; a Rails 2xx
+allows removal from the pending store. Queue expiration does not remove R2 mail.
+This boundary requires durable Rails persistence before 2xx, idempotent replay,
+private R2 storage without expiration of pending objects, and operational
+monitoring. It cannot guarantee acceptance when Cloudflare itself cannot store
+the incoming message.
 A prepared operation can be dispatched using its existing identity after a job
 enqueue failure; sending/unknown operations require evidence-based reconciliation.
 Notifications indicate method execution and may run inside an outer transaction;
@@ -92,4 +100,6 @@ silently impose a marketing subscription model on transactional mail.
 The optional [mailbox module](mailboxes.md) now packages mailbox persistence and
 address management over the existing transport/receipt APIs. It includes a
 [tenant adapter](activerecord-tenanted.md), without adding a tenant library to
-the plain Ruby client. A future inbox UI or starter should consume these APIs.
+the plain Ruby client. The optional [management engine](management-engine.md)
+consumes these same APIs with host-supplied authentication and authorization.
+Full inbox products can continue using them through their own frontends.

data/docs/custom-ingress.md

@@ -0,0 +1,207 @@
+# Use your existing inbound email pipeline
+
+This integration API is available in gem version 0.3.0.
+
+You can adopt mailbox registration without replacing your Worker, document processing, sender review, or archive. Use the gem to authenticate the request and resolve an accepted address, then keep your application's policy and processing.
+
+A useful starting point is one mailbox per site: an organization owns a receiving domain, a site owns a mailbox, and that mailbox can have several accepted addresses. This is an application convention, not a requirement of the gem. Database tenancy is optional; a single SQLite database works too.
+
+## Register addresses before accepting mail
+
+Follow [mailbox setup](mailboxes.md) to register and activate the receiving domain and accepted addresses. With existing catch-all Worker routing, address creation can be a database operation once an administrator has confirmed that routing covers the exact domain. Registering a domain does not create DNS records or extend wildcard coverage.
+
+Use the same provisioning service from organization/site onboarding and from the management UI. Keep a stable site reference in the mailbox's `owner_ref`; keep site permissions, slug changes, document workflows, and sender allowlists in your app. Treat a rename as an explicit alias/lifecycle decision so old addresses are not accidentally lost.
+
+For separate organization databases, configure [the SQLite tenant adapter](activerecord-tenanted.md) before loading mailbox models. The shared directory resolves the signed recipient to a tenant. Action Mailbox, Active Storage, and the gem's mailbox records must all use that tenant's connection.
+
+## Verify a custom endpoint before writing anything
+
+`Cloudflare::Email::Ingress.verify` is usable outside the bundled controller. It accepts a String or IO body, bounds the raw body size, and returns an immutable result. Successful verification exposes the exact binary body and authenticated envelope; rejected requests expose no verified message.
+
+The following controller is a starting point for a host with registered mailboxes:
+
+```ruby
+require "cloudflare/email/ingress"
+
+class InboundEmailsController < ActionController::API
+  def create
+    result = Cloudflare::Email::Ingress.verify(
+      secret: Rails.application.credentials.dig(:cloudflare, :ingress_secret),
+      headers: request.headers,
+      body: request.body,
+      content_length: request.content_length,
+      max_email_bytes: 25 * 1024 * 1024
+    )
+
+    case result.status
+    when :too_large
+      return head :payload_too_large
+    when :bad_signature, :stale
+      return head :unauthorized
+    end
+
+    verified = result.message
+
+    Cloudflare::Email::Mailboxes.receive(
+      recipient: verified.envelope.fetch("to")
+    ) do |destination|
+      # This block runs in the recipient's tenant. Apply your sender/review
+      # policy here, before persistence schedules Action Mailbox routing.
+      # Your policy may raise a host error or return nil instead of persisting.
+      # destination.owner_ref identifies your site/team; validate it using
+      # your application's policy in this tenant context.
+      verified.persist_action_mailbox!
+    end
+
+    head :ok
+  rescue Cloudflare::Email::Mailboxes::Unavailable
+    head :unprocessable_entity
+  end
+end
+```
+
+Mount this controller at your own route and point your existing Worker there. The host owns response codes and retry policy. If your policy returns nil and you acknowledge the request, you are accepting responsibility for that email: persist a durable review record or deliberately discard it according to your application's policy. A successful verification alone does not queue processing or create a mailbox.
+
+Do not use the MIME `To` header or an unauthenticated URL subdomain to select storage. `verified.envelope.fetch("to")` is the signed SMTP recipient. `Mailboxes.receive` checks that its domain, mailbox, and accepted address are active before entering the persistence block.
+
+`persist_action_mailbox!` stores the verified raw bytes and metadata in Action Mailbox. The receiving block adds mailbox membership in the same tenant transaction. Rails schedules normal routing after the transaction commits. Apply policies that must stop processing before calling persistence; a check performed after receiving returns can be too late.
+
+For an application that owns a different raw-email store, use `verified.body`, `verified.envelope`, `verified.provider_metadata`, `verified.message_checksum`, and `verified.storage_metadata` with your own persistence/transaction system. `Mailboxes.receive` specifically expects an Action Mailbox inbound email record (or nil) from its block; do not pass an unrelated processing record. The gem does not choose your archive retention, held-message model, or document queue.
+
+## Persist the email and link your business record
+
+Email persistence remains part of the gem's supported path. Action Mailbox stores
+the raw MIME using Active Storage, the verifier saves authenticated metadata, and
+`Mailboxes.receive` adds the inbox membership. Your processing/review record can
+refer to that email rather than storing a second copy of its raw content:
+
+```ruby
+Cloudflare::Email::Mailboxes.receive(
+  recipient: verified.envelope.fetch("to")
+) do |destination|
+  # Validate owner_ref and sender policy here, before any routing is scheduled.
+  inbound = verified.persist_action_mailbox!
+  if inbound
+    # Example host model, on the SAME tenant connection as the gem records.
+    EmailIntake.create!(
+      inbound_email_id: inbound.id,
+      mailbox_id: destination.mailbox_id,
+      owner_ref: destination.owner_ref
+    )
+  end
+  inbound # Return the ActionMailbox record; duplicate deliveries return nil.
+end
+```
+
+The database writes commit together. A host failure rolls back the new email,
+membership and host link and prevents the routing job from being enqueued. This
+does not make an R2 archive, another database, or external API calls transactional.
+Host exceptions propagate; only unavailable registry destinations are translated
+to `Mailboxes::Unavailable`. Existing blocks without a destination argument still
+work.
+
+Persisting through ActionMailbox schedules its normal routing after commit. Put
+your processing in that route or a deliberately coordinated job pipeline. If an
+email must be held, implement a routing policy that cannot process it before
+approval; storing it is not itself a review gate. A routing job failure also needs
+normal job retry/recovery. Receipt deduplication does not make every downstream
+business side effect idempotent.
+
+Managed mailbox membership protects raw email from ActionMailbox's normal
+automatic incineration. Archiving a mailbox message keeps its content; deliberate
+purging can remove it once no other membership references the email. Raw email
+saved without membership follows the normal ActionMailbox lifecycle. Keep host
+references, backup and R2 retention consistent with your chosen deletion policy.
+Multi-tenancy remains opt-in.
+
+## Resolve an address with your own persistence
+
+If your application already owns its raw-email store, use the standalone API:
+
+```ruby
+Cloudflare::Email::Mailboxes.with_recipient(
+  recipient: verified.envelope.fetch("to")
+) do |destination|
+  # Example host-owned persistence service; it must commit durably before ACK.
+  ExistingEmailStore.save!(
+    tenant_key: destination.tenant_key,
+    mailbox_id: destination.mailbox_id,
+    recipient: destination.recipient,
+    raw: verified.body,
+    metadata: verified.storage_metadata
+  )
+end
+```
+
+This checks the active domain, address and mailbox, enters the configured tenant,
+and yields an immutable `Destination` with `tenant_key`, `mailbox_id`, `address_id`,
+`receiving_domain_id`, `recipient` and `owner_ref`. It returns the block's result,
+creates no email or membership, starts no storage transaction, and requires no
+ActionMailbox. Configure the optional mailbox registry and tenant adapter as usual.
+
+Both APIs must be called after complete request verification. Destination values
+are routing snapshots, not authorization tokens: an owner reference does not
+prove a site still exists or that a sender may submit to it. Use records inside
+their tenant context and recheck lifecycle/permissions when later work requires
+it. Both APIs restore the previous tenant context when the block returns or raises.
+
+## Carry Worker metadata with authenticated provenance
+
+The default Worker protocol remains v2: it authenticates the raw message and SMTP envelope. Optional v3 also authenticates a bounded metadata object:
+
+```json
+{
+  "source": "cloudflare",
+  "data": {
+    "archive_key": "inbound/example.eml"
+  }
+}
+```
+
+The `archive_key` above is an illustrative application-defined value. The gem does not fetch that object or verify an archive exists. Your trusted Worker constructs the data from sources whose provenance you understand.
+
+V3 binds the encoded metadata to the timestamp, envelope, and exact raw bytes. The `X-CF-Email-Metadata` header is unpadded base64url UTF-8 JSON. Metadata attached to a v2 request is rejected rather than treated as authenticated. Existing v2 requests without metadata continue to work.
+
+The Worker template exports `signedEmailHeaders` for an existing transport and `forwardEmail` for the bundled forwarding behavior. Keep your current archive and retry handling, and use the header builder to authenticate the original raw bytes:
+
+```js
+import { signedEmailHeaders } from "./cloudflare-ingress.js";
+
+const headers = await signedEmailHeaders({
+  secret: env.INGRESS_SECRET,
+  raw, // Uint8Array from your bounded reader
+  from: message.from,
+  to: message.to,
+  metadata: { source: "cloudflare", data: { archive_key: archiveKey } },
+});
+// Send exactly raw with these headers using your existing transport.
+```
+
+Here `cloudflare-ingress.js` is your local copy of the template's `src/index.js`. `raw` and `archiveKey` come from your existing bounded reader and archive operation. See the [Worker integration instructions](../templates/worker/README.md) for supported metadata values and forwarding behavior. Upgrade the Rails receiver before enabling v3 in the Worker.
+
+In your Action Mailbox handler, read persisted metadata through the gem:
+
+```ruby
+require "cloudflare/email/provider_metadata"
+
+metadata = Cloudflare::Email::ProviderMetadata.for(inbound_email)
+archive_key = metadata&.dig("data", "archive_key")
+```
+
+This reads verified Active Storage metadata, not similarly named MIME headers. Authenticate your Worker first and preserve the verified object unchanged. Avoid adding secrets or unnecessary personal information to provider metadata.
+
+**A valid Worker signature proves that your trusted Worker submitted the request. It does not prove the original email sender is authentic.** Even metadata labelled `source: "cloudflare"` is an assertion made by the holder of the ingress secret. Do not copy sender-controlled MIME headers into a “trusted authentication” field. If your existing Worker has reliable authentication evidence, preserve its documented provenance and let your application decide how that evidence affects acceptance. The gem intentionally does not infer SPF/DMARC results or implement a sender allowlist.
+
+Retries with the same recipient, raw bytes, and metadata context reuse the inbound record. Aliases receive distinct membership context. Changing signed metadata produces a distinct checksum: stable values are preferable to per-attempt timestamps or random IDs. Keep downstream document extraction and external side effects idempotent too.
+
+## Adopt incrementally
+
+1. Inventory existing accepted addresses, organization/subdomain mappings, fallback destinations, and disabled sites. Backfill records explicitly; do not silently create a mailbox for every incoming address.
+2. Confirm existing Worker routing for one organization's exact domain and activate only verified addresses. Exercise an alias, unknown address, suspended mailbox, and cross-tenant destination with synthetic mail.
+3. Add request verification and preserve your current sender review, archive behavior, error responses, and size limits. Test that rejected or held mail cannot reach the processing queue.
+4. Connect site provisioning to the same mailbox API used by the [management engine](management-engine.md). Scope the engine through existing host authentication and authorization.
+5. Retire duplicate infrastructure only after comparing delivery and recovery behavior. Inbound adoption does not require switching your outbound provider.
+
+Keep the shared operational communications history separate from tenant-local raw emails and mailbox membership when those serve different purposes. Define who owns deletion, archive retention, deduplication, and processing status; two competing delivery ledgers make recovery harder.
+
+The gem's custom-ingress integration test exercises a custom controller against two real SQLite tenant databases, preserving binary MIME bytes and signed metadata before routing jobs run. It also verifies rejected metadata, host review, accepted-address enforcement, and retry behavior. It does not verify a deployed customer's Cloudflare DNS, Worker authentication evidence, R2 archive, or document-processing pipeline; those require that host's end-to-end tests.

data/docs/delivery-events.md

@@ -2,6 +2,15 @@
 
 Cloudflare Email Sending can publish outbound lifecycle events to Queues. This is separate from inbound Email Routing and the ActionMailbox ingress.
 
+Mail to a verified Email Routing destination can travel through Routing without
+producing an Email Sending callback. Keep using the recipient's normal address;
+do not interpret a missing callback as failure or resend the message. The optional
+[Routing delivery confirmation](routing-deliveries.md) integration checks
+authenticated analytics for qualifying single-recipient deliveries. It requires
+a separate **Analytics Read + Zone Read** credential and leaves unsupported or
+ambiguous evidence unresolved. Acceptance, receiving-server delivery and a human
+reading the message are different facts.
+
 ## Provision once
 
 1. Create a dedicated Cloudflare Queue for your application's sending events.

data/docs/features.md

@@ -5,7 +5,7 @@ services. You can use just the sending client, add incoming mail, or build a
 mailbox on top of the optional database-backed delivery tools.
 
 Start with [Getting started](getting-started.md) for working examples. These
-features are available in **0.2.0**. Database multi-tenancy is **off by default**:
+features are available in **0.3.0**. Database multi-tenancy is **off by default**:
 the optional mailbox module works in one database unless you explicitly configure
 a tenant connection adapter. A mailbox tenant key alone does not switch databases.
 
@@ -29,6 +29,34 @@ a tenant connection adapter. A mailbox tenant key alone does not switch database
 | Observe email processing | ActiveSupport notifications + `doctor` | Send/ingress/event/outbox instrumentation and configuration diagnostics |
 | Deploy receiving infrastructure | Ruby deployer and routing tasks | Environment-specific Workers, ingress secrets, address routes and DNS preflight checks |
 
+## Integration tools
+
+[Durable inbound delivery](../templates/worker/README.md#durable-inbound-delivery)
+saves raw email and its envelope in R2 before the Worker returns successfully.
+Queues attempt the Rails handoff, and a scheduled pass recovers retained mail
+after enqueue failures or retry exhaustion. Provision the storage, queue and
+schedule before deploying; direct forwarding requires an explicit fallback setting.
+
+[Routing delivery confirmation](routing-deliveries.md) adds a read-only provider
+client and optional durable receipts for qualifying single-recipient deliveries
+that appear in Routing analytics. It does not infer outcomes from missing events
+or change whether an accepted email may be sent again.
+
+Existing ingestion pipelines can use [custom ingress](custom-ingress.md) to
+verify bounded raw messages before tenant lookup, keep their own storage, or
+persist through ActionMailbox. Optional v3 signatures authenticate custom Worker
+metadata; your application still decides whether its provenance and sender policy
+are acceptable. The bundled Worker continues to use v2 by default.
+
+`Mailboxes.receive` yields the resolved destination while retaining email and
+membership persistence, so your own processing record can link to the saved mail.
+`Mailboxes.with_recipient` offers the same destination context for applications
+that own their storage. Neither replaces your sender policy or business workflow.
+
+[Read-only routing diagnostics](routing-diagnostics.md) inspect exact-domain DNS
+and the selected Worker route. They distinguish missing configuration from an
+incomplete inspection; a passing snapshot does not prove live email delivery.
+
 ## SQLite works
 
 The optional receipt and outbox tables work with **SQLite**. Keep your existing
@@ -58,7 +86,7 @@ subscriptions. The [getting-started guide](getting-started.md) walks through eac
 
 ## Protections included
 
-Incoming requests use v2 HMAC signatures covering the timestamp, SMTP sender,
+By default, incoming requests use v2 HMAC signatures covering the timestamp, SMTP sender,
 SMTP recipient and raw message. Rails checks a five-minute timestamp window.
 Identical MIME retried for the same recipient is deduplicated; delivery to a
 different recipient is stored separately.
@@ -83,7 +111,9 @@ See [managed mailbox setup](mailboxes.md) for the application-facing API and
 The gem supplies email infrastructure and optional managed mailbox records.
 Your app supplies users, mailbox permissions, conversation records, custom folders, search, compose screens,
 drafts and any AI review or approval workflow. It also decides unsubscribe and
-recipient eligibility policy. The gem does not supply an inbox UI or AI agent.
+recipient eligibility policy. The optional [management engine](management-engine.md)
+adds server-rendered mailbox administration and plain-text message previews.
+It does not supply a compose/conversation product or AI agent.
 
 An authenticated SMTP envelope tells your app which address Cloudflare received
 the message for. It does not prove the human sender's identity. Reply correlation
@@ -91,8 +121,9 @@ also does not authorize access to a conversation. Apply your app's permissions
 before displaying mail or sending a reply.
 
 You configure Cloudflare domains/DNS, queue subscriptions, durable jobs,
-monitoring, storage protection and retention. Inbound mail is not durably
-buffered by the Worker during a Rails outage. See [architecture](architecture.md)
+monitoring, storage protection and retention. Direct forwarding does not buffer
+Rails outages; the optional durable inbound setup retains pending mail in R2.
+See [architecture](architecture.md)
 for the full boundary and [security guidance](../SECURITY.md) for deployment.
 
 ## Where to go next

data/docs/getting-started.md

@@ -18,11 +18,11 @@ not need to be the same domain as your Rails application's web address.
 
 ### Install the current code
 
-Add version 0.2 to your app's `Gemfile`. If upgrading from 0.1, read the
-[upgrade guide](upgrading-0.2.md) before changing an existing Worker deployment:
+Add version 0.3 to your app's `Gemfile`. If upgrading an existing installation, read the
+[upgrade guide](upgrading-0.3.md) before changing an existing Worker deployment:
 
 ```ruby
-gem "cloudflare-email", "~> 0.2.0"
+gem "cloudflare-email", "~> 0.3.0"
 ```
 
 ```sh
@@ -123,8 +123,18 @@ In Cloudflare **Email Routing → your apex domain → Settings → Subdomains**
 your receiving subdomain, such as `in.example.com`, and finish its DNS setup.
 This is separate from verifying the sending domain.
 
-Deploy Rails with ActionMailbox storage and workers configured. Then run these
-commands in an environment with production configuration and deployment credentials:
+Deploy Rails with ActionMailbox storage and workers configured. For guided
+Worker setup, use the [Deploy to Cloudflare template](../templates/deploy-to-cloudflare/README.md).
+It provisions R2 and Queues and prompts for your Rails URL and shared secret.
+Then select that Worker in your Email Routing rule as described in its guide.
+
+For the CLI setup instead, run these commands in an environment with production
+configuration and deployment credentials:
+
+First create the private R2 bucket and Queue, then deploy the generated Wrangler
+configuration using the [durable setup guide](../templates/worker/docs/durable-inbound.md).
+The Ruby task below updates that provisioned Worker while preserving its bindings.
+It refuses a missing bucket/queue binding or recovery schedule before changing code.
 
 ```sh
 RAILS_ENV=production bin/rails cloudflare:email:deploy_worker URL=https://app.example.com/rails/action_mailbox/cloudflare/inbound_emails
@@ -166,11 +176,11 @@ Install `cloudflared`, configure development credentials and a separate developm
 receiving route, then start Rails. In another terminal:
 
 ```sh
-bin/rails cloudflare:email:deploy_worker
+INBOUND_DELIVERY_MODE=direct bin/rails cloudflare:email:deploy_worker
 bin/rails cloudflare:email:dev
 ```
 
-The first command creates the development Worker; the second points it at a
+The first command creates the development Worker with the explicit direct fallback; the second points it at a
 temporary tunnel to your local Rails server on port 3000. Keep the tunnel running
 while testing and stop it with Ctrl-C. Set `PORT=...` if Rails uses another port.
 The task checks that Rails has the ingress-only guard; restart Rails if asked.
@@ -295,4 +305,4 @@ override it. Cloudflare has separate [outgoing size and recipient limits](https:
 
 Use [troubleshooting](troubleshooting.md) when something does not arrive,
 [the feature overview](features.md) to explore more, and
-[the upgrade guide](upgrading-0.2.md) for an existing 0.1 installation.
+[the upgrade guide](upgrading-0.3.md) for an existing 0.1 installation.