cloudflare-email 0.3.0 → 0.4.1

data/lib/cloudflare/email/tenant_job_context.rb

@@ -1,90 +1,7 @@
 require "cloudflare/email/tenancy"
-
+require "mailbox_kit/tenant_job_context"
 module Cloudflare
   module Email
-    # Opt in with `prepend Cloudflare::Email::TenantJobContext` on jobs whose
-    # arguments or work reference tenant records. Queue payloads must be trusted.
-    module TenantJobContext
-      PAYLOAD_KEY = "cloudflare_email_tenant_key".freeze
-
-      def serialize
-        key = cloudflare_email_job_tenant_key
-        return super unless key
-        Tenancy.with(key) do
-          payload = super
-          verify_cloudflare_email_host_tenant!(key, payload["tenant"])
-          payload.merge(PAYLOAD_KEY => key)
-        end
-      end
-
-      def deserialize(job_data)
-        # Bind before super: host job integrations may deserialize model arguments
-        # eagerly. Never infer a missing tenant from the worker's ambient context.
-        if !job_data.key?(PAYLOAD_KEY) && cloudflare_email_optional_job_context?
-          @cloudflare_email_job_tenant_key = nil
-          return super
-        end
-        @cloudflare_email_job_tenant_key = Tenancy.normalize_key(job_data[PAYLOAD_KEY])
-        verify_cloudflare_email_host_tenant!(@cloudflare_email_job_tenant_key, job_data["tenant"])
-        Tenancy.with(@cloudflare_email_job_tenant_key) { super }
-      end
-
-      def perform_now
-        # Active Job resolves GlobalIDs before around_perform, so that callback
-        # cannot safely implement database tenant selection.
-        key = cloudflare_email_job_tenant_key
-        return super unless key
-        if defined?(::ActiveRecord::Tenanted::Job) && respond_to?(:tenant)
-          verify_cloudflare_email_host_tenant!(key, tenant)
-        end
-        Tenancy.with(key) { super }
-      end
-
-      def self.install_framework_jobs!
-        if defined?(::ActionMailbox)
-          %i[RoutingJob IncinerationJob].each do |name|
-            next unless ::ActionMailbox.const_defined?(name)
-            klass = ::ActionMailbox.const_get(name)
-            klass.define_singleton_method(:cloudflare_email_optional_job_context?) { !Tenancy.enabled? }
-            klass.prepend(self) unless klass.ancestors.include?(self)
-          end
-        end
-        if defined?(::ActiveStorage)
-          %i[BaseJob AnalyzeJob PurgeJob MirrorJob TransformJob PreviewImageJob].each do |name|
-            next unless ::ActiveStorage.const_defined?(name)
-            klass = ::ActiveStorage.const_get(name)
-            klass.define_singleton_method(:cloudflare_email_optional_job_context?) { !Tenancy.enabled? }
-            klass.prepend(self) unless klass.ancestors.include?(self)
-          end
-        end
-      end
-
-      private
-
-      def cloudflare_email_job_tenant_key
-        # Once serialized/deserialized, retries retain their original tenant even
-        # if re-enqueued from a different tenant or outside a tenant context.
-        return @cloudflare_email_job_tenant_key if instance_variable_defined?(:@cloudflare_email_job_tenant_key)
-        return nil if cloudflare_email_optional_job_context? && !Tenancy.current_key
-        # Native uploads/mailbox work may originate in the host's own with_tenant
-        # block. Framework jobs can capture that trusted context on first use.
-        # deserialize never takes this path for missing persisted metadata.
-        if !Tenancy.current_key && self.class.respond_to?(:cloudflare_email_optional_job_context?)
-          key = Tenancy.host_current_key
-          return @cloudflare_email_job_tenant_key = key if key
-        end
-        @cloudflare_email_job_tenant_key = Tenancy.require_context!
-      end
-
-      def cloudflare_email_optional_job_context?
-        self.class.respond_to?(:cloudflare_email_optional_job_context?) && self.class.cloudflare_email_optional_job_context?
-      end
-
-      def verify_cloudflare_email_host_tenant!(key, host_key)
-        if host_key && host_key != key
-          raise ConfigurationError, "job host tenant conflicts with Cloudflare Email tenant context"
-        end
-      end
-    end
+    TenantJobContext = MailboxKit::TenantJobContext
   end
 end

data/lib/cloudflare/email/version.rb

@@ -1,5 +1,5 @@
 module Cloudflare
   module Email
-    VERSION = "0.3.0"
+    VERSION = "0.4.1"
   end
 end

data/lib/cloudflare-email.rb

@@ -1,3 +1,9 @@
+require "mailbox-kit"
+module Cloudflare
+  module Email
+    Mailboxes = MailboxKit::Mailboxes
+  end
+end
 require "cloudflare/email/version"
 require "cloudflare/email/error"
 require "cloudflare/email/response"

data/lib/generators/cloudflare/email/mailboxes/templates/create_cloudflare_email_mailboxes.rb

@@ -40,6 +40,7 @@ class CreateCloudflareEmailMailboxes < ActiveRecord::Migration[7.1]
       t.timestamps
     end
     add_index :cloudflare_email_mailbox_messages, [:mailbox_id, :inbound_email_id], unique: true, name: "idx_cf_email_mailbox_inbound"
+    add_index :cloudflare_email_mailbox_messages, :inbound_email_id, name: "idx_cf_email_message_inbound"
     add_index :cloudflare_email_mailbox_messages, [:tenant_key, :mailbox_id, :archived_at, :id], name: "idx_cf_email_mailbox_inbox"
 
     create_table :cloudflare_email_mailbox_outbound_messages do |t|

data/lib/generators/cloudflare/email/mailboxes/templates/create_cloudflare_email_receiving_domains.rb

@@ -3,7 +3,7 @@ class CreateCloudflareEmailReceivingDomains < ActiveRecord::Migration[7.1]
     create_table :cloudflare_email_receiving_domains do |t|
       t.string :domain, null: false
       t.string :tenant_key, null: false
-      t.string :account_id, null: false
+      t.string :account_id # Required by the sending adapter only.
       t.string :state, null: false, default: "pending"
       t.boolean :sending_enabled, null: false, default: false
       t.text :provisioning_evidence

data/templates/deploy-to-cloudflare/README.md

@@ -3,13 +3,13 @@
 Receive email in Rails with the [cloudflare-email gem](https://github.com/cole-robertson/cloudflare-email).
 This template stores inbound mail in private R2, delivers it through a Queue,
 and retries from storage when Rails is unavailable. It includes scheduled
-recovery and Worker logs. No React app or extra server is needed.
+recovery and Worker logs.
 
 [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
 
 ## 1. Prepare Rails
 
-Install `gem "cloudflare-email", "~> 0.3.0"` and follow the
+Install `gem "cloudflare-email", "~> 0.4.0"` and follow the
 [Rails setup guide](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/getting-started.md).
 Deploy Rails with Action Mailbox storage and routing configured before connecting
 real email. Generate a secret with `openssl rand -hex 32` and configure it as
@@ -38,20 +38,39 @@ cron are present. Keep the bucket private with no lifecycle rule expiring
 
 ## 3. Connect an email address
 
+**Choose your address shape:** `acme@in.example.com` on one receiving domain,
+or `invoices@acme.in.example.com` with dynamic organization subdomains.
+Use the [shared domain setup guide](docs/domain-setup.md) for DNS,
+Worker routing, and verification commands.
+The same Worker serves both; there is no per-organization Worker allowlist.
+
 In Cloudflare, enable Email Routing for the intended receiving domain/subdomain
 and complete its required DNS setup. Add an Email Routing rule for your receiving
-address with **Send to a Worker**, selecting the Worker you just deployed.
+address with **Send to a Worker**, selecting the Worker you just deployed. For
+many local parts, configure the intended domain's catch-all to this Worker once.
 The button does not change your MX records, provision addresses in Rails, or
 replace your existing mailbox provider. Use a receiving subdomain when your apex
 domain's email belongs to Google Workspace or Microsoft 365.
 
 If using the gem's managed mailboxes, register the receiving mailbox/address in
 Rails too. Tenant support and domain catch-all receiving remain explicit choices.
+After verifying a dynamic namespace as described in the guide, register new
+organization domains in Rails without routinely adding provider rules per org.
+Verify wildcard receiving on your account before relying on unlisted subdomains.
 Outbound Email Sending credentials and delivery-event subscriptions are separate
 from this inbound Worker setup.
 
 ## 4. Verify and operate
 
+For dynamic organization subdomains, start with the read-only DNS check:
+
+```sh
+npm run check:subdomains -- --base in.example.com --labels acme,globex
+```
+
+It checks named and fresh labels without API credentials or configuration changes.
+It reports DNS observations only; finish with the real-email checks below.
+
 Send to the configured address and verify that Rails retains and routes it.
 In staging, stop Rails, send another message, confirm it remains in R2, restore
 Rails, and confirm one inbox record and removal of the pending object. Verify a
@@ -67,10 +86,9 @@ also tolerate retries. Configure operational alerts in your monitoring service.
 
 ## Updates and local development
 
-Your copied repository belongs to you; gem updates do not update its Worker
-automatically. Review upstream release notes, deploy Rails first, then port Worker
-changes into your copy while preserving your resource names, secrets, and pending
-storage. Keep production resources separate from test resources.
+Your copied repository contains your Worker deployment. Deploy changes from that
+repository; updating the gem does not deploy the Worker. Preserve resource names,
+secrets, and pending storage.
 
 Use Node 22.12+ (or a supported newer version): `npm ci`, `npm test`, and
 `npm run check`. For local development, copy `.dev.vars.example` to `.dev.vars`,

data/templates/deploy-to-cloudflare/docs/domain-setup.md

@@ -0,0 +1,118 @@
+# Set up addresses and customer subdomains
+
+Choose the address pattern for your app:
+
+| Pattern | Example | Rails setup |
+| --- | --- | --- |
+| One receiving domain | `acme@in.example.com` | Register the domain once; create a mailbox for each customer |
+| Customer subdomains | `invoices@acme.in.example.com` | Register each exact customer domain and its mailboxes |
+
+One Worker can serve all your accepted addresses. Rails looks up the mailbox;
+you do not need to maintain an address list in the Worker.
+Database multi-tenancy is optional.
+
+## 1. Deploy the Worker
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
+
+Deploy Rails first, then enter its HTTPS ingress URL and shared secret in the
+Worker deployment form. Cloudflare provisions private R2 storage and a Queue.
+Use separate deployments for development and production.
+
+The [setup guide](https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
+covers the form and required resources.
+
+## 2. Connect your receiving domain
+
+Use a subdomain such as `in.example.com` if your main domain already receives
+mail through Google Workspace or Microsoft 365.
+
+In Cloudflare Email Routing:
+
+1. [Add the receiving domain or subdomain](https://developers.cloudflare.com/email-service/configuration/subdomains/).
+2. Add the DNS records Cloudflare provides, preserving your main domain's mail records.
+3. Create a route with **Send to a Worker** and select your deployed Worker.
+4. To accept many local parts, configure the receiving domain's
+   [catch-all rule](https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/#catch-all-rule)
+   to use that Worker.
+
+A Cloudflare catch-all gets email to your Worker. Rails still decides which
+addresses are accepted. To put unknown local parts into an inbox, also enable
+the gem's [mailbox catch-all](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/mailboxes.md#receive-unregistered-local-parts-with-an-optional-catch-all).
+
+## 3. Customer subdomains
+
+Cloudflare documents explicit subdomain onboarding. If you want new customer
+subdomains to work without adding each one in Cloudflare, verify wildcard
+receiving on your account before relying on it.
+
+For a receiving namespace under `in.example.com`, the DNS pattern is:
+
+| Type | Name in zone `example.com` | Value |
+| --- | --- | --- |
+| MX | `*.in` | Each receiving MX target and priority assigned by Cloudflare |
+
+Wildcard DNS alone does not guarantee Email Routing accepts an unlisted
+subdomain. Test with a fresh customer subdomain and confirm email reaches the
+Worker and the correct Rails inbox. If your account requires explicit onboarding,
+add those subdomains in Cloudflare or use the single-domain pattern.
+
+[Explicit DNS records override wildcard inheritance](https://developers.cloudflare.com/dns/manage-dns-records/reference/wildcard-dns-records/),
+including names with A or TXT records. Check existing customer names as well as
+new ones. The receiving base `in.example.com` needs its own records.
+
+### Check DNS
+
+From either Worker template:
+
+```sh
+npm run check:subdomains -- --base in.example.com --labels acme,globex
+```
+
+This checks your chosen labels and two fresh labels without changing DNS.
+It needs Node and DNS access, with no API key. A passing result confirms MX
+answers; send a real email to verify delivery.
+
+For configured Worker rules, use the
+[Rails routing diagnostic](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/routing-diagnostics.md).
+That check inspects exact DNS records, so inherited wildcard MX may appear missing.
+
+## 4. Create the mailbox in Rails
+
+After verifying the receiving route, run this from trusted application setup code:
+
+```ruby
+registry = Cloudflare::Email::Mailboxes
+domain = registry.register_domain(
+  domain: "acme.in.example.com",
+  tenant_key: "organization-123"
+)
+registry.activate_domain!(domain.id, evidence: "Receiving route verified")
+
+registry.for_tenant("organization-123") do |inboxes|
+  mailbox = inboxes.create(
+    name: "Invoices",
+    address: "invoices@acme.in.example.com",
+    owner_ref: "Organization:123"
+  )
+  inboxes.activate_address!(mailbox.addresses.first.id,
+    evidence: "Receiving route verified")
+end
+```
+
+Use your application's stable organization identity and validate customer slugs.
+Activation records the verification you performed; it does not configure DNS.
+Registration takes exact domains, not `*` patterns.
+
+Once wildcard receiving is verified, create new customer domains and mailboxes
+through these same APIs. Send a test message and confirm it appears only in the
+intended inbox. Monitor pending mail so unregistered or suspended destinations
+can be resolved.
+
+## Sending from customer addresses
+
+Receiving and sending are separate. Cloudflare requires
+[verification of each sending domain](https://developers.cloudflare.com/email-service/configuration/subdomains/#add-a-subdomain-to-email-sending).
+A simple setup uses a shared verified From address and a customer-specific
+Reply-To address. To send through a managed mailbox, follow the
+[mailbox sending setup](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/mailboxes.md#send-from-the-mailbox).

data/templates/deploy-to-cloudflare/package.json

@@ -11,6 +11,7 @@
     "deploy": "wrangler deploy",
     "dev": "wrangler dev",
     "check": "wrangler deploy --dry-run",
+    "check:subdomains": "node scripts/check-subdomains.mjs",
     "test": "vitest run"
   },
   "devDependencies": {

data/templates/deploy-to-cloudflare/scripts/check-subdomains.mjs

@@ -0,0 +1,54 @@
+// Read-only public DNS check. No Cloudflare credentials or configuration writes.
+import { Resolver } from "node:dns/promises";
+import { randomBytes } from "node:crypto";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const labelPattern = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export async function checkSubdomains({ base, labels = [] }, lookup, randomLabel = () => `cf-probe-${randomBytes(8).toString("hex")}`) {
+  base = String(base || "").trim().toLowerCase();
+  if (base.length > 220 || base.split(".").length < 2 || !base.split(".").every(label => labelPattern.test(label))) {
+    throw new Error("Provide a DNS base such as in.example.com, without @, a scheme, or *.");
+  }
+  if (labels.length > 10 || !labels.every(label => labelPattern.test(label) && `${label}.${base}`.length <= 253)) {
+    throw new Error("Provide at most 10 comma-separated single-label subdomains, such as acme,globex.");
+  }
+  const probes = [randomLabel(), randomLabel()];
+  const names = [...new Set([...labels, ...probes])];
+  const checks = await Promise.all(names.map(async label => {
+    const domain = `${label}.${base}`;
+    try {
+      const mx = (await lookup(domain)).map(record => ({ priority: record.priority, exchange: record.exchange.toLowerCase().replace(/\.$/, "") }));
+      const cloudflare = mx.length > 0 && mx.every(record => record.exchange.endsWith(".mx.cloudflare.net"));
+      return { domain, fresh_probe: probes.includes(label), status: cloudflare ? "cloudflare_mx_observed" : "other_or_missing_mx", mx };
+    } catch (error) {
+      return { domain, fresh_probe: probes.includes(label), status: "unknown", reason: error.code || "DNS_LOOKUP_FAILED" };
+    }
+  }));
+  return {
+    checked_at: new Date().toISOString(),
+    base, dns_observation: checks.every(check => check.status === "cloudflare_mx_observed") ? "cloudflare_mx_observed_for_all_names" : "needs_attention",
+    delivery_verified: false, checks,
+    next_step: "Inspect the catch-all Worker rule, register two exact domains/mailboxes in Rails, and send real test emails. MX answers do not verify account ownership, Email Routing acceptance, Worker delivery, or Rails persistence."
+  };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const { values } = parseArgs({ options: { base: { type: "string" }, labels: { type: "string" }, help: { type: "boolean" } } });
+    if (values.help) {
+      console.log("npm run check:subdomains -- --base in.example.com [--labels acme,globex]\nRead-only DNS observations, including two fresh labels. This does not verify email delivery.");
+    } else {
+      const resolver = new Resolver({ timeout: 2000, tries: 1 });
+      const labels = values.labels ? values.labels.split(",").map(label => label.trim().toLowerCase()) : [];
+      const report = await checkSubdomains({ base: values.base, labels }, domain => resolver.resolveMx(domain));
+      console.log(JSON.stringify(report, null, 2));
+      if (report.dns_observation === "needs_attention") process.exitCode = 1;
+    }
+  } catch (error) {
+    console.error(error.message);
+    console.error("Usage: npm run check:subdomains -- --base in.example.com [--labels acme,globex]");
+    process.exitCode = 1;
+  }
+}

data/templates/deploy-to-cloudflare/test/subdomains.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, vi } from "vitest";
+import { checkSubdomains } from "../scripts/check-subdomains.mjs";
+
+function probes() {
+  let id = 0;
+  return () => `fresh-${++id}`;
+}
+const cloudflare = [{ priority: 10, exchange: "route1.mx.cloudflare.net" }];
+
+describe("subdomain setup DNS observations", () => {
+  it("checks chosen exact names plus fresh labels without claiming delivery", async () => {
+    const lookup = vi.fn(async () => cloudflare);
+    const report = await checkSubdomains({ base: "in.example.com", labels: ["acme"] }, lookup, probes());
+    expect(lookup.mock.calls.map(call => call[0])).toEqual(["acme.in.example.com", "fresh-1.in.example.com", "fresh-2.in.example.com"]);
+    expect(report.dns_observation).toBe("cloudflare_mx_observed_for_all_names");
+    expect(report.delivery_verified).toBe(false);
+  });
+
+  it("reports an exact-name exception even when fresh probes resolve", async () => {
+    const report = await checkSubdomains({ base: "in.example.com", labels: ["acme"] }, async domain => {
+      if (domain.startsWith("acme.")) throw Object.assign(new Error("no answer"), { code: "ENODATA" });
+      return cloudflare;
+    }, probes());
+    expect(report.dns_observation).toBe("needs_attention");
+    expect(report.checks[0].status).toBe("unknown");
+  });
+
+  it.each([
+    { mx: [] }, { mx: [{ priority: 0, exchange: "." }] },
+    { mx: [{ priority: 10, exchange: "mx.example.com" }] },
+    { mx: [...cloudflare, { priority: 5, exchange: "mx.other.test" }] }
+  ])("does not accept absent, null, foreign or mixed MX: $mx", async ({ mx }) => {
+    const report = await checkSubdomains({ base: "in.example.com" }, async () => mx, probes());
+    expect(report.dns_observation).toBe("needs_attention");
+  });
+
+  it("preserves DNS timeout uncertainty", async () => {
+    const report = await checkSubdomains({ base: "in.example.com" }, async () => { throw Object.assign(new Error("timeout"), { code: "ETIMEOUT" }); }, probes());
+    expect(report.checks.every(check => check.status === "unknown")).toBe(true);
+    expect(report.delivery_verified).toBe(false);
+  });
+
+  it("rejects malformed domains and nested labels before DNS", async () => {
+    const lookup = vi.fn();
+    for (const base of ["*.example.com", "https://example.com", "a@b.com", "localhost", "a..com"]) {
+      await expect(checkSubdomains({ base }, lookup)).rejects.toThrow();
+    }
+    await expect(checkSubdomains({ base: "example.com", labels: ["nested.acme"] }, lookup)).rejects.toThrow();
+    expect(lookup).not.toHaveBeenCalled();
+  });
+});

data/templates/worker/README.md

@@ -6,6 +6,12 @@ gem.
 
 ## Deploy
 
+Choose a single receiving domain or dynamic organization subdomains using the
+[domain setup guide](docs/domain-setup.md). Once your
+receiving namespace is verified, new mailboxes can be created in Rails without
+editing a Worker recipient list. `npm run check:subdomains -- --base in.example.com`
+checks public MX for fresh names; it does not claim live delivery verification.
+
 For a guided dashboard deployment that provisions resources and prompts for
 secrets, use the [Deploy to Cloudflare template](../deploy-to-cloudflare/README.md).
 It uses this same Worker with a standalone configuration. The CLI setup below
@@ -60,7 +66,7 @@ For each inbound message, the Worker:
    pass. Even exhausted queue retries leave the original message recoverable.
 
 The signed request uses HMAC-SHA256 and authenticates the original SMTP envelope
-alongside the MIME bytes. See [durable delivery setup and recovery](./docs/durable-inbound.md).
+alongside the MIME bytes. See [durable delivery setup and recovery](docs/durable-inbound.md).
 `INBOUND_DELIVERY_MODE=direct` selects an explicit single-attempt fallback that
 calls `message.setReject` on non-2xx, timeout or network failure. Existing pending
 mail keeps draining through Queue and cron while this fallback is selected.
@@ -70,8 +76,7 @@ timestamps outside its 5-minute acceptance window. A signature authenticates the
 Worker request, not the original email sender. Captured requests remain valid
 inside that window; Rails deduplicates messages through Action Mailbox.
 
-Deploy the Rails gem and this Worker together with ingress paused during the
-transition. Rails accepts v2 and v3 signatures and rejects v1/missing versions. It stores authenticated
+Rails accepts v2 and v3 signatures and rejects v1/missing versions. It stores authenticated
 SMTP metadata separately from MIME; applications read it using
 `Cloudflare::Email::Envelope.for(inbound_email)`. Duplicate detection includes the
 exact SMTP recipient, preserving separate To/Cc/Bcc deliveries. The format accepts
@@ -138,8 +143,7 @@ encoded as unpadded base64url, limited to 16,384 encoded characters, and sent as
 HMAC-SHA256(secret, "v3.{timestamp}.{encoded_envelope}.{encoded_metadata}.{raw_body}")
 ```
 
-Neither the MIME nor its headers are rewritten. Upgrade Rails to a version that
-supports v3 before enabling metadata in a custom Worker. Keep sensitive provider
+Neither the MIME nor its headers are rewritten. Keep sensitive provider
 data out of metadata unless your application's retention and access policies
 permit storing it with email records.
 
@@ -234,10 +238,10 @@ after delivery and does not replace this optional outage archive.
 
 ## Durable inbound delivery
 
-[Durable inbound delivery](./docs/durable-inbound.md) is the default. Provision the
+[Durable inbound delivery](docs/durable-inbound.md) is the default. Provision the
 configured private R2 bucket, Queue producer/consumer and cron before deploying.
 There is no rollout enable flag or automatic downgrade when bindings are missing.
-The guide covers upgrades, monitoring, recovery tests and explicit direct fallback.
+The guide covers monitoring, recovery tests, and direct fallback.
 
 ## Validate changes
 

data/templates/worker/docs/domain-setup.md

@@ -0,0 +1,118 @@
+# Set up addresses and customer subdomains
+
+Choose the address pattern for your app:
+
+| Pattern | Example | Rails setup |
+| --- | --- | --- |
+| One receiving domain | `acme@in.example.com` | Register the domain once; create a mailbox for each customer |
+| Customer subdomains | `invoices@acme.in.example.com` | Register each exact customer domain and its mailboxes |
+
+One Worker can serve all your accepted addresses. Rails looks up the mailbox;
+you do not need to maintain an address list in the Worker.
+Database multi-tenancy is optional.
+
+## 1. Deploy the Worker
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
+
+Deploy Rails first, then enter its HTTPS ingress URL and shared secret in the
+Worker deployment form. Cloudflare provisions private R2 storage and a Queue.
+Use separate deployments for development and production.
+
+The [setup guide](https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
+covers the form and required resources.
+
+## 2. Connect your receiving domain
+
+Use a subdomain such as `in.example.com` if your main domain already receives
+mail through Google Workspace or Microsoft 365.
+
+In Cloudflare Email Routing:
+
+1. [Add the receiving domain or subdomain](https://developers.cloudflare.com/email-service/configuration/subdomains/).
+2. Add the DNS records Cloudflare provides, preserving your main domain's mail records.
+3. Create a route with **Send to a Worker** and select your deployed Worker.
+4. To accept many local parts, configure the receiving domain's
+   [catch-all rule](https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/#catch-all-rule)
+   to use that Worker.
+
+A Cloudflare catch-all gets email to your Worker. Rails still decides which
+addresses are accepted. To put unknown local parts into an inbox, also enable
+the gem's [mailbox catch-all](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/mailboxes.md#receive-unregistered-local-parts-with-an-optional-catch-all).
+
+## 3. Customer subdomains
+
+Cloudflare documents explicit subdomain onboarding. If you want new customer
+subdomains to work without adding each one in Cloudflare, verify wildcard
+receiving on your account before relying on it.
+
+For a receiving namespace under `in.example.com`, the DNS pattern is:
+
+| Type | Name in zone `example.com` | Value |
+| --- | --- | --- |
+| MX | `*.in` | Each receiving MX target and priority assigned by Cloudflare |
+
+Wildcard DNS alone does not guarantee Email Routing accepts an unlisted
+subdomain. Test with a fresh customer subdomain and confirm email reaches the
+Worker and the correct Rails inbox. If your account requires explicit onboarding,
+add those subdomains in Cloudflare or use the single-domain pattern.
+
+[Explicit DNS records override wildcard inheritance](https://developers.cloudflare.com/dns/manage-dns-records/reference/wildcard-dns-records/),
+including names with A or TXT records. Check existing customer names as well as
+new ones. The receiving base `in.example.com` needs its own records.
+
+### Check DNS
+
+From either Worker template:
+
+```sh
+npm run check:subdomains -- --base in.example.com --labels acme,globex
+```
+
+This checks your chosen labels and two fresh labels without changing DNS.
+It needs Node and DNS access, with no API key. A passing result confirms MX
+answers; send a real email to verify delivery.
+
+For configured Worker rules, use the
+[Rails routing diagnostic](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/routing-diagnostics.md).
+That check inspects exact DNS records, so inherited wildcard MX may appear missing.
+
+## 4. Create the mailbox in Rails
+
+After verifying the receiving route, run this from trusted application setup code:
+
+```ruby
+registry = Cloudflare::Email::Mailboxes
+domain = registry.register_domain(
+  domain: "acme.in.example.com",
+  tenant_key: "organization-123"
+)
+registry.activate_domain!(domain.id, evidence: "Receiving route verified")
+
+registry.for_tenant("organization-123") do |inboxes|
+  mailbox = inboxes.create(
+    name: "Invoices",
+    address: "invoices@acme.in.example.com",
+    owner_ref: "Organization:123"
+  )
+  inboxes.activate_address!(mailbox.addresses.first.id,
+    evidence: "Receiving route verified")
+end
+```
+
+Use your application's stable organization identity and validate customer slugs.
+Activation records the verification you performed; it does not configure DNS.
+Registration takes exact domains, not `*` patterns.
+
+Once wildcard receiving is verified, create new customer domains and mailboxes
+through these same APIs. Send a test message and confirm it appears only in the
+intended inbox. Monitor pending mail so unregistered or suspended destinations
+can be resolved.
+
+## Sending from customer addresses
+
+Receiving and sending are separate. Cloudflare requires
+[verification of each sending domain](https://developers.cloudflare.com/email-service/configuration/subdomains/#add-a-subdomain-to-email-sending).
+A simple setup uses a shared verified From address and a customer-specific
+Reply-To address. To send through a managed mailbox, follow the
+[mailbox sending setup](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/mailboxes.md#send-from-the-mailbox).