Skip to content
SiteSwarm Platform Documentation

Company Email Setup

Corporate Email Service & Shared Routing Setup Runbook

1. Executive Summary & Purpose

This operational runbook governs the architecture, DNS configuration, Cloudflare Email Service onboarding, Authenticated SMTP setup, and email client (“Send mail as”) configuration for corporate domain email (@jptechnologysolutions.com / @jpsoftwareassociates.com).

By combining Cloudflare Email Routing, Cloudflare Email Workers (@siteswarm/service-email-router), and Workers Paid Authenticated SMTP (smtp.mx.cloudflare.net:465), SiteSwarm delivers enterprise-grade email routing without per-seat mailbox fees while preserving co-founder inbox segregation and shared thread visibility.

flowchart TD
    subgraph Inbound ["Inbound Email Flow"]
        ClientIn["External Sender"] --> MX["Cloudflare Inbound MX\n(route[1-3].mx.cloudflare.net)"]
        MX --> EdgeWorker["Cloudflare Email Worker\n(@siteswarm/service-email-router)"]
        EdgeWorker --> RouterRule{"Recipient Normalization\n& Route Classification"}
        RouterRule -->|"jacob@ / jacob+*@"| JacobPersonal["Jacob Personal Inbox\n(JACOB_PERSONAL_EMAIL)"]
        RouterRule -->|"parker@ / parker+*@"| ParkerPersonal["Parker Personal Inbox\n(PARKER_PERSONAL_EMAIL)"]
        RouterRule -->|"support@ / catch-all"| MultiFwd["Concurrent Promise.all\n(with Sender-Aware Deduplication)"]
        MultiFwd --> JacobPersonal
        MultiFwd --> ParkerPersonal
    end


    subgraph Outbound ["Outbound & Shared Thread Visibility Flow"]
        FounderClient["Personal Client / Gmail\n('Send mail as' support@)"] --> SMTP["Cloudflare Authenticated SMTP\n(smtp.mx.cloudflare.net:465)"]
        SMTP --> Recipient["Client / Customer Inbox"]
        FounderClient -.->|"Reply-All CC: support@"| EdgeWorker
        EdgeWorker -.->|"Deduplicated Partner Forward\n(In-Reply-To / References Intact)"| PartnerInbox["Partner Founder Inbox"]
    end

[!IMPORTANT] Architectural Invariant (Domain Separation): Technical runbooks govern capability IDs, DNS records, API token scopes, and client settings. Subscription pricing, per-seat retail figures, and billing terms are strictly out of scope for technical documentation per repository guidelines.

2. Inbound DNS & Email Routing Configuration

2.1 Authoritative DNS Records

To activate Cloudflare Email Routing on the corporate zone, configure the following authoritative DNS records via Cloudflare Dashboard or Terraform:

Type Name Priority Target / Content Purpose
MX @ 12 route1.mx.cloudflare.net Primary Inbound Mail Exchanger
MX @ 49 route2.mx.cloudflare.net Secondary Inbound Mail Exchanger
MX @ 54 route3.mx.cloudflare.net Tertiary Inbound Mail Exchanger
TXT @ — v=spf1 include:_spf.mx.cloudflare.net ~all Sender Policy Framework (SPF)
TXT _dmarc — v=DMARC1; p=reject; sp=reject; adkim=s; aspf=s; Enforced DMARC Policy

2.2 Verified Destination Mailboxes

Before the Email Worker can forward inbound traffic, each co-founder’s external mailbox must be attested and verified within the Cloudflare account:

  1. Navigate to Cloudflare Dashboard > Account > Email Routing > Destination addresses.
  2. Click Add destination address:
    • Add Jacob’s destination address (JACOB_PERSONAL_EMAIL).
    • Add Parker’s destination address (PARKER_PERSONAL_EMAIL).
  3. Each recipient opens the verification email dispatched by Cloudflare and clicks Verify email address.
  4. Confirm status changes to Verified in the Cloudflare console.

3. Email Worker Deployment & Routing Rules

3.1 Worker Configuration & Deployment

The routing engine lives in services/email-router (@siteswarm/service-email-router).

Configure production environment variables in wrangler.jsonc or via Cloudflare secrets:

Terminal window
# Set production destination addresses
pnpm --filter=@siteswarm/service-email-router exec wrangler secret put JACOB_PERSONAL_EMAIL
pnpm --filter=@siteswarm/service-email-router exec wrangler secret put PARKER_PERSONAL_EMAIL


# Deploy to Cloudflare edge
pnpm --filter=@siteswarm/service-email-router run build
pnpm --filter=@siteswarm/service-email-router exec wrangler deploy

3.2 Binding the Email Worker to Inbound Routes

  1. Navigate to Cloudflare Dashboard > Select Zone (jptechnologysolutions.com) > Email Routing > Routing Rules.
  2. Under Catch-all rule:
    • Action: Send to a Worker
    • Destination Worker: siteswarm-service-email-router
    • Status: Active
  3. Optional: Explicit custom rules can also route individual prefixes (jacob@, parker@, support@) to the same worker; the worker normalizes all incoming recipients automatically.

3.3 Recipient Normalization Contract

The Worker applies RFC 5233 local-part normalization and subaddress stripping:

// Local-part normalization and RFC 5233 subaddress parsing
const { normalizedLocalPart, tag } = normalizeRecipient(message.to);


if (normalizedLocalPart === "jacob") {
  // Routes exclusively to Jacob
  await message.forward(env.JACOB_PERSONAL_EMAIL, headers);
} else if (normalizedLocalPart === "parker") {
  // Routes exclusively to Parker
  await message.forward(env.PARKER_PERSONAL_EMAIL, headers);
} else {
  // Shared & Catch-All: Concurrent multi-destination forward
  await Promise.allSettled([
    message.forward(env.JACOB_PERSONAL_EMAIL, headers),
    message.forward(env.PARKER_PERSONAL_EMAIL, headers),
  ]);
}

4. Cloudflare Authenticated SMTP (smtp.mx.cloudflare.net:465)

Workers Paid accounts include Cloudflare Email Service Authenticated SMTP, allowing personal email clients (such as Gmail, Apple Mail, or Thunderbird) to send signed outbound emails directly from custom-domain addresses.

4.1 SMTP Connection Parameters

Parameter Configuration Value Notes
SMTP Server smtp.mx.cloudflare.net Cloudflare Global Anycast SMTP Relay
Port 465 Implicit TLS / SSL (Mandatory)
Authentication Required (Plain / Login) API Token authentication
Username <company-email-address> or <CF-API-Token> e.g. jacob@jptechnologysolutions.com
Password <Email-Sending-API-Token> Cloudflare Scoped API Token
Encryption Protocol SSL / TLS 1.3 Enforced encryption

4.2 Scoped API Token Generation

Generate dedicated, least-privilege API tokens for each co-founder:

  1. Navigate to Cloudflare Dashboard > My Profile > API Tokens > Create Token.
  2. Select Create Custom Token:
    • Token Name: smtp-email-sending-jacob (or smtp-email-sending-parker)
    • Permissions:
      • Account > Email Sending > Edit (or Zone > Email Sending > Edit)
    • Account Resources: Include Jpsoftwareassociates@gmail.com's Account
    • Zone Resources: Include All zones or jptechnologysolutions.com
    • Client IP Address Filtering: Optional (leave empty for mobile roaming)
  3. Click Continue to summary and Create Token.
  4. Securely store the generated token secret in 1Password / password manager.

5. Gmail “Send Mail As” Client Configuration

Both co-founders configure their personal Gmail accounts to send and receive corporate email with complete threading synchronization.

5.1 Personal Address Setup (jacob@ / parker@)

  1. In Gmail, click Settings (Gear icon) > See all settings > Accounts and Import.
  2. In the Send mail as section, click Add another email address:
    • Name: Co-Founder Full Name (e.g., Jacob Miller or Parker Henderson)
    • Email address: jacob@jptechnologysolutions.com (or parker@...)
    • Treat as an alias: Checked (for personal individual address)
  3. Click Next Step:
    • SMTP Server: smtp.mx.cloudflare.net
    • Port: 465
    • Username: jacob@jptechnologysolutions.com
    • Password: <Cloudflare Email Sending API Token>
    • Secured connection using: SSL (recommended)
  4. Click Add Account. Enter the confirmation verification code sent to your inbox.

5.2 Shared Address Setup (support@jptechnologysolutions.com)

[!WARNING] CRITICAL OPERATIONAL REQUIREMENT: When configuring support@jptechnologysolutions.com, the “Treat as an alias” checkbox must be UNCHECKED.

Why “Treat as an alias” Must Be Unchecked:

  1. Gmail De-Aliasing: When “Treat as an alias” is checked, Gmail considers support@ as identical to the user’s primary mailbox. Gmail suppresses incoming copies of sent messages and prevents the message from being treated as a distinct inbound conversation.
  2. Shared Thread Visibility:
    • When Unchecked, Gmail preserves From: support@jptechnologysolutions.com and includes support@ on replies when choosing Reply to all.
    • The email client dispatches the outbound message through smtp.mx.cloudflare.net:465.
    • The CC’d support@ address routes back into the Cloudflare Email Worker.
    • The Email Worker detects the founder sender (from: jacob.personal@example.com or from: jacob@...) and invokes Sender-Aware Deduplication, delivering the message exclusively to Parker’s inbox.
    • Because standard RFC 5322 In-Reply-To and References headers are preserved intact, the customer and both co-founders see the exact same unified conversation thread in their respective inboxes.
sequenceDiagram
    autonumber
    actor Customer as Customer
    actor Jacob as Jacob (Personal Gmail)
    actor Parker as Parker (Personal Gmail)
    participant Worker as Cloudflare Email Worker
    participant SMTP as Cloudflare Authenticated SMTP


    Customer->>Worker: Inbound to support@jptechnologysolutions.com
    Worker->>Jacob: Forward (Route: shared)
    Worker->>Parker: Forward (Route: shared)
    Note over Jacob,Parker: Both co-founders see inbound inquiry


    Jacob->>SMTP: Reply via 'Send mail as' support@ (CC: support@)
    SMTP->>Customer: Outbound message delivered to customer
    SMTP->>Worker: CC delivered to support@jptechnologysolutions.com
    Worker->>Worker: Sender-Aware Check: From Jacob -> Deliver to Parker only
    Worker->>Parker: Forward with preserved In-Reply-To & References
    Note over Parker: Parker sees Jacob's outbound reply threaded in inbox

6. Verification Checklist & Troubleshooting

Verification Step Command / Action Expected Result Pass/Fail
1. DNS Records Active dig MX jptechnologysolutions.com +short route[1-3].mx.cloudflare.net returned [ ]
2. SPF Policy Valid dig TXT jptechnologysolutions.com +short Includes _spf.mx.cloudflare.net [ ]
3. Inbound Individual Route Send email to jacob@jptechnologysolutions.com Received only in Jacob’s inbox [ ]
4. Subaddressing Route Send email to parker+test@jptechnologysolutions.com Received in Parker’s inbox [ ]
5. Shared Inbound Route Send email to support@jptechnologysolutions.com Received in BOTH inboxes [ ]
6. Authenticated SMTP Send email from Gmail via support@ Successfully delivered via port 465 [ ]
7. Shared Thread Sync Jacob replies from support@ with CC support@ Appears in Parker’s thread; no Jacob duplicate [ ]

Troubleshooting Guide

  • Error: “Authentication failed. Please check your username/password” in Gmail:
    • Verify port is 465 with SSL (not port 587 with STARTTLS).
    • Verify the API token has Account > Email Sending > Edit permissions.
    • Check that the token has not expired and the Cloudflare Account ID matches.
  • Inbound mail bouncing with SMTP 550:
    • Verify MX records point to route[1-3].mx.cloudflare.net.
    • Confirm the destination addresses are verified in Cloudflare Dashboard.
    • Check Worker logs via pnpm exec wrangler tail siteswarm-service-email-router for setReject exceptions.
  • Loop detected / Dropped email:
    • Check worker logs for Dropped email to prevent loop.
    • Verify that custom email client rules do not forward incoming messages back to support@.