Convert-by-Email Service

The convert-by-email service lets registered customers email a PDF to [email protected] and receive an accessible HTML version back as an email reply. No browser, no login, no software to install. PDF is the only accepted input format.

Address routing: The user-facing address is [email protected]. A Google Workspace default-routing rule rewrites the envelope recipient to [email protected], which has its MX records pointing at Cloudflare Email Routing. CF then dispatches to the convert-email Worker. Replies are sent from [email protected] via the Gmail API. The two addresses exist because theaccessible.org MX is on Google Workspace and can’t be moved to Cloudflare without breaking the rest of the org’s mail; pdf-html.com is a dedicated zone used solely as an inbound landing pad for the Worker.

How It Works

User emails PDF to [email protected]
        │
        ▼
Google Workspace (theaccessible.org)
        │  Default-routing rule: [email protected]
        │  → "Change envelope recipient" → [email protected]
        ▼
Cloudflare Email Routing (pdf-html.com)
        │  (MX records for pdf-html.com point to Cloudflare)
        │  (rule: [email protected] → convert-email Worker)
        ▼
convert-email Worker (workers/convert-email/)
        │
        ├─ 1. Parse MIME, extract attachment (postal-mime)
        ├─ 2. Look up sender in Supabase (customers table)
        ├─ 3. Validate file type, size (25MB max)
        ├─ 4. Estimate pages, pre-check credits
        ├─ 5. Send acknowledgment email via Gmail API
        ├─ 6. Store source file in R2 (temporary)
        ├─ 7. Call accessible-pdf-api via Service Binding
        ├─ 8. Calculate actual credits (flat 1 credit per page)
        ├─ 9. Deduct credits in Supabase (atomic RPC)
        ├─ 10. Send result email with accessible HTML attached
        ├─ 11. Log job in Supabase (conversion_jobs table)
        └─ 12. Clean up R2 (async)

Infrastructure

Component	Details
Worker	`convert-email` on Cloudflare Workers
Worker URL	`https://convert-email.larry-c6c.workers.dev`
Pipeline	Service Binding to `accessible-pdf-api` (no auth, no network hop)
R2 Bucket	`convert-email-files` (temporary file storage during processing)
Supabase	Project `vuvwmfxssjosfphzpzim` — `customers` and `conversion_jobs` tables
Outbound email	Gmail API via Google Workspace service account with domain-wide delegation
Inbound email	User-facing: `[email protected]` (Google Workspace alias) → `[email protected]` (Cloudflare Email Routing) → Worker

Source Files

All source is in workers/convert/src/:

File	Purpose
`index.js`	Main entry point. Handles the full email-to-reply flow. Also exposes `/health` and `/test-send` HTTP endpoints.
`gmail.js`	Gmail API module. JWT signing with Web Crypto API, token exchange, MIME building, send/reply/attachment methods.
`templates.js`	Branded HTML email templates for every reply type (unregistered, no attachment, unsupported file, insufficient credits, processing started, success, error).
`supabase.js`	REST client for customer lookups, credit deduction (via atomic RPC), and job logging.
`mime.js`	MIME parsing via `postal-mime`, file type detection, base64 utilities.
`credits.js`	Credit calculation: 1 per standard page, 2 per complex page.

Gmail API Auth Chain

The Worker sends all outbound email via the Gmail API using a Google Workspace service account:

Worker loads the service account JSON key from the GOOGLE_SERVICE_ACCOUNT_KEY secret
Creates a JWT signed with the service account’s RSA private key (Web Crypto API — no npm dependencies)
Exchanges the JWT for an access token at https://oauth2.googleapis.com/token
Calls POST gmail.googleapis.com/gmail/v1/users/me/messages/send with a base64url-encoded MIME message
Google sends the email as [email protected]

The access token is cached in memory for up to 1 hour within a single Worker invocation.

Google Cloud setup (already configured)

Project: TheAccessibleOrg-Email
API: Gmail API enabled
Service account: convert-email-sender with a JSON key stored as a Worker secret

Google Admin Console (already configured)

Domain-wide delegation: The service account’s Client ID is authorized for scope https://www.googleapis.com/auth/gmail.send
This allows the service account to send email as any user in the domain

Supabase Schema

customers

Column	Type	Notes
id	uuid	Primary key
email	text	Unique, indexed — the sender’s email
name	text
plan_type	text	`free` or `paid`
credits_remaining	integer	Paid tier only
lifetime_free_pages_used	integer	Default 0, max 10
created_at	timestamptz

conversion_jobs

Column	Type	Notes
id	uuid	Primary key
customer_id	uuid	FK to customers
sender_email	text
filename	text
file_type	text	`pdf`, `docx`, `html`
file_size_bytes	integer
total_pages	integer
standard_pages	integer
complex_pages	integer
credits_charged	integer
status	text	`success` or `error`
error_message	text	Nullable
created_at	timestamptz

RPC Functions

deduct_credits(p_customer_id, p_amount) — Atomic credit deduction. Raises exception if insufficient.
use_free_pages(p_customer_id, p_pages) — Atomic free page usage. Raises exception if lifetime limit (10) exceeded.

Credit System

Every page costs 1 credit, including complex pages (equations, tables, forms, multi-column) — the high-fidelity 2x multiplier was retired 2026-06-12 (HIGH_FIDELITY_CREDIT_MULTIPLIER = 1).

Free tier: 10 lifetime pages.

The Worker estimates page count from file size before processing (for pre-check), then uses the actual page classification returned by the pipeline for the final charge.

Secrets

Set via npx wrangler secret put <NAME> from the workers/convert/ directory:

Secret	Purpose
`GOOGLE_SERVICE_ACCOUNT_KEY`	Full JSON contents of the Google service account key file
`SUPABASE_SERVICE_KEY`	Supabase `service_role` key for server-side access

The PIPELINE_API_KEY secret is not needed — the pipeline is called via a Cloudflare Service Binding which bypasses auth.

Email Routing Setup

Two pieces — Google Workspace alias, then Cloudflare dispatch.

Google Workspace (theaccessible.org):

Admin console → Apps → Google Workspace → Gmail → Default routing → Add setting.
Envelope filter: “Only affect specific envelope recipients” → exact match [email protected].
Action: Change envelope recipient → [email protected].
Save. No mailbox/alias/group needed at the Google end — the rule accepts unknown recipients.

Cloudflare (pdf-html.com):

Dashboard → pdf-html.com → Email → Email Routing → Routing Rules.
Add rule: [email protected] → Send to Worker → convert-email.
MX records for pdf-html.com must point to Cloudflare (configured automatically when Email Routing is enabled).

Deployment

cd workers/convert
npm install
npx wrangler deploy

Testing

Health check

curl https://convert-email.larry-c6c.workers.dev/health

Test Gmail sending

curl -X POST https://convert-email.larry-c6c.workers.dev/test-send \
  -H "Content-Type: application/json" \
  -d '{"to":"[email protected]","subject":"Test","body":"Hello from convert-email"}'

Full flow test

Send an email with a PDF attached to [email protected] from an email address that exists in the customers table.

Error Handling

Unregistered sender: Gets a branded reply explaining how to register.
No attachment: Gets a reply asking them to attach a PDF.
Unsupported file type: Gets a reply explaining that only PDF files are accepted via email.
File too large: Gets an error reply (25MB limit).
Insufficient credits: Gets a reply with their balance and a link to purchase more.
Pipeline failure: Gets an error reply. No credits charged. Error logged to conversion_jobs.
Gmail send failure: Logged to console. The Worker catches and logs notification failures separately so they don’t mask the original error.

Reusing GmailSender in Other Workers

The GmailSender class in src/gmail.js is a standalone module. To use it in another Worker:

Copy gmail.js into the other Worker
Add the same two secrets (GOOGLE_SERVICE_ACCOUNT_KEY, GMAIL_SENDER)
Import and call new GmailSender(env).send(to, subject, text, html)

No additional Google configuration needed — the service account has domain-wide delegation.