Privacy and erasure

Binding for implementation. This page lists every store of personal data, how long it is kept and how it is deleted; how the jurisdiction applies; the retention and erasure jobs step by step; legal holds; subject-access export; and what remains after deletion (backups, logs, processors). The user-facing explanation is in Privacy, retention and erasure.

1. Principles

1. Minimise. Store the least that delivers the feature: vectors hold no text; queues hold pointers; logs hold pseudonyms; suppressions and tombstones hold keyed hashes.
2. Delete together. A message’s rows, index entries, references, vectors and objects are deleted by the same job, and the receipt counts each store (FR-PRV-3, FR-SRCH-11).
3. Prove deletion. Every erasure ends with probe queries whose results are in the receipt (F6).
4. Say what remains. Backups, processor-side logs and suppressions survive by design and are listed here (section 11).

2. Data inventory

Webhook receivers, AI processing and the email providers are covered in section 11.

3. Jurisdiction and residency

PM_JURISDICTION (eu or default) is chosen at pmail setup and applied at creation (FR-PRV-1):

With default, the same resources are created without a jurisdiction and objects use unique_id(). Changing jurisdiction means a new deployment and a migration, which v1.0 does not provide.

What the jurisdiction does not cover. It controls where D1, R2 and Durable Objects store data and where the database and objects run. It does not control:

• Where the Worker runs. Requests and queue consumers run in the data centre that receives them and read jurisdiction-bound data from there (Cloudflare D1 data-location docs, read 2026-10-09).
• Queues, which carry pointers only. Inbound pointers carry the envelope sender and recipient (Inbound).
• Vectorize, which has no documented data-location option. It stores vectors, vector IDs and the eight filter fields only: never text, subjects or addresses. Embeddings are derived from content and are treated as personal data: they are erased with their message.
• Workers AI (embeddings, reranking, triage, the agentic planner, toMarkdown), which processes mail content in transit. When PM_AI_GATEWAY is set, content-bearing calls disable gateway log collection and caching (Security › STRIDE, TB5).
• Email Routing and Email Sending, which process mail on Cloudflare’s network. Email Sending keeps an activity log for 30 days and, when Email preview is on, a copy of each sent message for about seven days. New sending domains have preview turned on automatically (Cloudflare Email Service docs, read 2026-10-09). Domain onboarding therefore sets preview_enabled: false on every sending domain through PATCH /zones/{zone_id}/email/sending/subdomains/{subdomain_id}, and pmail doctor fails if any sending domain has preview enabled.
• Workers Logs and Analytics Engine, which hold no personal data (section 2).
• DNS-over-HTTPS lookups, which send sender and tenant domain names to the configured resolvers (by default Cloudflare and Google).
• Amazon Web Services, only for domains with inbound = ses or transport = ses (the dns_records, send_only and smtp_relay with inbound: ses methods, and SES failover). SES processes message content in PM_SES_REGION; raw inbound mail rests in the S3 bucket until it is ingested (normally seconds, never longer than the 14-day lifecycle rule), with SSE-S3 and no public access; SNS and SQS carry receipt notifications. With PM_JURISDICTION=eu, pmail setup ses refuses an SES region outside the EU and the UK unless --allow-non-eu is given, and /health reports ses_region (Domains on any DNS host §11). For the SES region, eu means “EU or UK”: the UK has an EU adequacy decision under the GDPR (European Commission adequacy decisions, renewed 19 December 2025, read 2026-10-09), so London (eu-west-2, this deployment’s SES region, decided 2026-10-09) is an acceptable data location. This is not Cloudflare’s eu jurisdiction above, which means the European Union only (R2 data location, read 2026-10-09).
• The customer’s own mail provider, for an smtp_relay domain: outbound content goes to the relay the customer chose and configured.
• Google and GitHub, when console sign-in with them is enabled: the provider learns that the person signs in to this deployment and returns their verified address and account ID. No mail content is involved.

DPIA. Automated processing of business correspondence with AI models is likely to need a data protection impact assessment by the deployer. This page and the data inventory are the data-flow input for it. Pylota Mail does not provide legal advice and does not act as controller or processor for a self-hosted deployment.

The processors to list in it:

The customer’s SMTP relay provider is the customer’s own choice and contract, not a processor of the deployment.

4. JobRunner

Retention, erasure and export run as JobRunner state machines driven by the object’s alarm (ADR 0005).

           start()                    all steps done/skipped
 queued ──────────▶ running ───────────────────────────────▶ completed
                      │  ▲
          step error  │  │ alarm (backoff)
                      ▼  │
                   (retry step) ── 10th failed attempt on one step ──▶ failed
 queued/running ── cancel (tenant erasure supersedes) ──▶ canceled

• Creation. The handler inserts the jobs row (status queued, a new runner_do_id from unique_id_with_jurisdiction, created_by_key_id = the calling key) and, for erasure, the erasure_requests row (status queued, target_id = the msg_ or thr_ ID for message and thread scope, created_by_key_id), or, for an export, the exports row (status queued, scope, job_id), in one D1 batch; then sends JobRequest::Start { job_id, kind, tenant_id, params }. If Start fails, the every-minute cron starts any job still queued after 60 seconds.
• Steps. Start writes the step list for the job kind into steps (all pending) and arms alarm:step for now. Each alarm runs the first non-finished step for a slice of at most 20 seconds or 1,000 items, stores cursor and counts_json, and re-arms immediately while work remains.
• Idempotency. Every step can be re-run from its cursor with the same result: deletes of missing objects, rows or vectors count as success and are not counted twice (counts come from the store’s own response or from rows deleted in the committed transaction).
• Errors. A failed slice increments attempts, stores last_error (a machine code), and re-arms after 30 s × 2^(attempts − 1), capped at 1 hour. After 10 attempts the job is failed; for erasure the request becomes failed, erasure.failed (with step and error) is emitted, and the erasure_failed alert fires (Observability).
• Mirroring. On each step transition the runner updates jobs.status and jobs.updated_at in D1. When the first step starts it sets jobs.status, and erasure_requests.status or exports.status, from queued to running in one D1 batch. On completion it writes jobs.result_json, jobs.completed_at and, for erasure, the erasure_requests row (completed or completed_with_holds, receipt_json, completed_at). A failed job sets erasure_requests.status or exports.status to failed in the same batch.
• Cancel. A job is canceled only by tenant erasure (section 6.6, step 1), which cancels the tenant’s other queued and running jobs: the runner stops at its next slice, and one D1 batch sets jobs.status, and erasure_requests.status or exports.status, to canceled. A canceled erasure emits no erasure.completed; the tenant erasure that superseded it covers the same data.
• Events go through the runner’s own outbox (Design conventions).
• Deadline. NFR-PRV-1 requires erasure within 24 hours. The erasure_overdue alert fires for any erasure still running 20 hours after created_at.

4.1 Mailbox operations used by jobs

These MailboxRequest variants are added by this design. All run inside the mailbox, all take the caller’s tenant_id and identity_id in the RPC envelope, and all write in one transaction_sync per call.

target is one of Message { id }, Thread { id }, Counterparty { address } or All.

5. Retention

5.1 Scheduling

The */15 cron starts one retention job per tenant per UTC day: it selects up to 50 active tenants whose latest retention job was created before today (UTC) and creates a job for each. A deployment with more tenants catches up over the day’s 96 runs. A separate global job (tenant_id = NULL) runs once per day for control-plane tables.

5.2 Steps of a tenant retention job

Every R2 delete in steps 2, 3 and 5 is sent to BACKUP too when it is configured (section 5.4).

Held threads (section 8) are excluded by RetentionPlan in steps 2 and 3. Messages in held threads keep their raw MIME and rows until the hold ends; the next daily run then purges them.

Webhook replay reaches back 30 days from each event’s occurred_at (or retention.events_days, if shorter). Replay reads payloads from the outbox, which keeps them for events_days, so a tenant with events_days below 30 can replay only that far; a longer events_days keeps the payloads and the delivery log longer but never extends replay past 30 days (Webhooks › Replay). events_days is 1–365.

5.3 Global retention job

5.4 Optional R2 backup copy

R2 has no object versioning and no replication (PutBucketVersioning and PutBucketReplication are not implemented, per the R2 S3 API compatibility page, last updated 2026-07-31, read 2026-10-09). R2 bucket locks exist, but a lock rule blocks deletion, so it would stop retention and erasure from deleting personal data; the design does not use them. Without help, a bug that deletes blobs loses them.

The optional backup covers that case. It is off by default:

• Setting PM_BACKUP_BUCKET makes pmail setup create that bucket in the deployment’s jurisdiction and bind it as BACKUP (Configuration).
• Once per UTC day the */15 cron starts a backup job (jobs.kind = 'backup', tenant_id = NULL). Its one step lists t/ in key order (cursor = the last key) and copies to BACKUP, under the same key and with the same custom metadata, every object uploaded since the previous run’s start. Errors retry under the JobRunner backoff; the result counts copied, skipped and failed objects (backup_objects_total).
• The backup never deletes on its own. Retention and erasure delete each key from BLOBS and BACKUP in the same step, and tenant erasure sweeps t/{tenant_id}/ in both, so a copy never outlives an erasure. An object deleted from BLOBS by anything else stays in BACKUP until a person restores or removes it.
• Restoring is a manual copy back from BACKUP to BLOBS for the affected keys, listed from the mailbox rows that point at missing objects.
• Cost: one list operation per 1,000 objects in t/ each night, and one write per new object.

6. Erasure

6.1 Request

POST /v1/erasure-requests (erasure:manage), or DELETE /v1/identities/{id} (identity scope, reason identity_deleted), or DELETE …/messages/{id} (message scope, reason message_deleted).

• Validation runs before anything is written: the target must exist and be in the key’s scope (Security › Authorisation); otherwise the resource’s *_not_found.
• For counterparty, the address is normalised (lower case, IDNA A-label domain) and counterparty_hash = hex(HMAC-SHA256(PM_HASH_KEY, address)) is stored in D1. The clear address is passed only to the JobRunner, which keeps it in meta.target_address until the finalise step.
• The response is 202 with the erasure request object (status: "queued"). Repeating a request creates a new request and job; erasure is idempotent, so a second run deletes nothing and reports zero counts.
• An erasure request never returns 423 legal_hold: held items are skipped and listed (FR-PRV-4, api.md). Only the single-message DELETE …/messages/{message_id} checks the thread’s hold first and answers 423 legal_hold without creating a request.

6.2 What EraseRows deletes

In one transaction per batch, for each message rowid:

1. DELETE FROM fts WHERE rowid = ?1 and DELETE FROM fts_tri WHERE rowid = ?1.
2. DELETE FROM messages WHERE rowid = ?1, cascading to deliveries, attachments, labels, refs, chunks and verifications.
3. DELETE FROM outbox WHERE payload_json references the message ID (the outbox payload builder stores the message ID in a top-level data.message_id or data.message.id; the delete uses json_extract).
4. DELETE FROM idempotency WHERE message_id = ?1.
5. Update the thread’s counters and participants_json; delete a thread left with no messages.
6. For a counterparty target, also: delete the contacts row for the address, and remove the address from participants_json of every surviving thread.

Counts returned per batch: messages, attachments, FTS rows (rows deleted from fts; fts_tri rows are deleted alongside and not counted), refs, outbox events.

6.3 Message and thread scope

6.4 Counterparty scope (I1)

A message matches when the normalised address equals from_address, appears in to_json, cc_json, bcc_json or reply_to_json, or is a deliveries.address of the message. A message that only mentions the address in its body is not “to or from” the counterparty and is not erased; erase it with message scope if needed.

Counterparty erasure is not an objection: mail the counterparty sends afterwards is stored as usual. To stop contact, the tenant adds a suppression (outbound) or a receive-block entry (inbound).

6.5 Identity scope (FR-IDN-4)

Holds on an identity being deleted. The request completes as completed_with_holds: everything outside held threads is gone, the addresses are tombstoned, and the identity stays deleting. The hold routes stay usable on a deleting identity for tenant and platform keys with erasure:manage. When the daily retention job finds a deleting identity with no remaining holds (removed, or until passed), it creates a new identity-scope erasure request with reason hold_released:{era_id}, audit-logged, which finishes the deletion and emits erasure.completed.

6.6 Tenant scope

Order: stop routing, then mailboxes, then D1 rows, then the vector namespace.

Suppressions are deleted in tenant erasure because the tenant can no longer send; I7 applies to counterparty erasure.

6.7 Probes (F6)

A non-zero probe re-runs the step that should have deleted the item (counted as an attempt). The job completes only with all probes at zero, except held items.

6.8 Waiting for Vectorize

Vectorize mutations are asynchronous: deleteByIds returns a mutation ID and the change becomes visible after a few seconds (Vectorize client API, read 2026-10-09). Deletes are sent in batches of 500, to both indexes while a re-embed is running (Search §6.7). The semantic probe calls getByIds on the deleted IDs every 10 seconds for up to 2 minutes, until none is returned. If IDs remain after that, the probe step fails this attempt: the step that deleted them runs again (re-sending deleteByIds for the remaining IDs) under the job’s backoff (section 4).

6.9 People (console accounts)

A person can delete their own account at /console/settings once they own no workspace; otherwise the request gets 409 owner_required (W34, Cloud sign-up §10). Tenant erasure runs the same deletion for every person it leaves with no workspace (section 6.6, step 4).

1. A person deleting their own account first leaves each workspace as in Console › Members: the members row and the person’s notification_prefs rows for that workspace are deleted, their pending notifications there are dropped (O19), the seat is released and member.removed is emitted.
2. In one D1 batch: delete the person’s sessions, the login_tokens for their address, their oauth_identities, their notification_prefs rows in every workspace, and any waitlist row for their address.
3. In the same batch, scrub the users row rather than delete it, because invitations.invited_by and audit rows refer to its ID: email becomes the row’s own usr_ ID; name, last_tenant_id, terms_version, terms_accepted_at, totp_sealed, totp_enabled_at, totp_last_step and recovery_codes_sealed are cleared; status = 'disabled'. The address is then free, and signing up again creates a new person.
4. Write an audit row user.delete with tenant_id = NULL and only the usr_ ID in details_json.
5. Start a counterparty erasure of the person’s former address, scoped to the system identity (section 6.4), so the sign-in, invitation and notification mail sent to them is deleted now rather than at the 30-day cutoff. Its receipt is kept like any erasure record.

Pending invitations sent to the address by other workspaces stay; they belong to those workspaces and expire after 7 days.

7. Special cases

7.1 Counterparty erasure across identities

The JobRunner iterates every identity of the tenant with the same normalised address, so one request covers every mailbox (FR-PRV-3). identities_affected lists the identities where anything was deleted or held. Only counterparty_hash is stored in D1, so the erasure record does not itself retain the address.

7.2 Suppressions after erasure (I7)

A suppression records an objection to contact (UK and EU GDPR Art. 21) or a delivery failure the sender must respect. After counterparty erasure it keeps address_hash, address_hint (masked, for example j***@example.com), reason, created_at and expires_at, and loses note and source_message_id. Sends to the address are still refused because the send path hashes each recipient and looks it up. The integrator can remove it with DELETE /v1/tenants/{tenant_id}/suppressions/{address}.

7.3 Allow and block lists

sender_lists entries are the tenant’s own configuration and are not changed by counterparty erasure: removing a block entry would re-open contact, and the entry is not a message. The privacy guide tells integrators to remove entries for an erased counterparty with the lists API when appropriate.

7.4 What agent assertions and signed requests disclose

An agent assertion is made to be read by its audience (Agent signing keys §4.2). It discloses the identity’s ID (sub), its primary address (email), its display name (name), the workspace name (org), whether the identity has an accountable human (accountable_human, a boolean), ai_agent: true, the issuer and the times, plus the nonce and ext the caller chose. It never holds the accountable owner’s name or address (FR-IDN-2 data), and the service never inspects ext beyond its size and claim-name rules: what goes there is the integrator’s choice and responsibility. The token is never stored or logged; usage_daily keeps only a count (assertions).

A signed HTTP request discloses to the site the deployment’s origin (Signature-Agent) and the identity’s primary address in the signed From header; nothing is stored but a count (http_signatures). The JWKS and the key directory hold public keys only. The JWKS answers an unknown, deleted, paused or suspended identity with the same 404 identity_not_found, and identity IDs are ULIDs never derived from addresses, so it cannot be used to test whether an address exists.

After identity erasure, only key_tombstones remains: thumbprints with no link to the identity, its tenant or any address. Copies of assertions and signed requests that third parties received are outside the deployment’s reach (section 11).

7.5 Notifications

Notification emails go to people’s console sign-in addresses and never contain content from mail: no subject, sender, snippet or attachment name. A new_mail email names the inbox address and counts messages; only mail visible in the inbox is counted, never quarantined, hidden, spam, loopback or test-tenant mail (Notifications §1, O15). The Notifier object holds person and identity IDs and counts, never addresses or content.

Each notification is an ordinary transactional send from the system identity on the default tenant, so its composed message (the person’s address, counts, inbox addresses, the workspace name and links) is kept in the system identity’s mailbox for 30 days, and out/{msg}.eml for 7 days, whatever the default tenant’s policy says (section 5.2). Deleting the person erases it at once (section 6.9, step 5).

8. Legal holds

• POST /v1/identities/{identity_id}/threads/{thread_id}/hold { "reason", "until" } sets threads.hold_json = { reason, until, set_by, set_at }; DELETE …/hold clears it. Both need erasure:manage and write audit_log rows (hold.set, hold.removed).
• A hold is active while hold_json is set and until is null or later than now. An expired hold is ignored and cleared by the next retention run (audit hold.expired).
• A hold covers the whole thread, including messages that arrive after it was set.
• While active: retention skips the thread (raw and messages); every erasure scope skips it and lists { thread_id, reason } in receipt.held, and the request ends completed_with_holds (FR-PRV-4, I2); identity and tenant deletion behave as in section 6.5.
• Holds do not hide messages: held threads stay readable and searchable within normal scope rules.

9. Subject-access export

POST /v1/exports (erasure:manage) with scope: "counterparty" and counterparty_address, or scope: "identity" and identity_id (FR-PRV-5, I3).

9.1 Job steps

Held, quarantined, hidden and throttled messages are included: an export is a read of everything the deployment holds about the subject. The ZIP is written with a pure-Rust ZIP writer (for example the zip crate with only a pure-Rust deflate backend), pinned at build time.

9.2 ZIP layout

exp_01JA4….zip
├── messages.json
└── eml/
    └── idn_01J9Z3K8V4…/
        ├── 20260914T081203Z_msg_01J9….eml
        └── 20260915T093011Z_msg_01JA….eml

9.3 messages.json

{
  "export_id": "exp_01JA4…",
  "tenant_id": "ten_01J9…",
  "scope": "counterparty",
  "counterparty_hash": "5c1e…",
  "generated_at": "2026-10-09T10:20:00Z",
  "generator": "pylota-mail/1.0.0",
  "identities": ["idn_01J9…", "idn_01JA…"],
  "messages": [
    {
      "id": "msg_01J9…", "identity_id": "idn_01J9…", "thread_id": "thr_01J9…",
      "direction": "inbound", "status": "received", "kind": "normal",
      "from": { "address": "jo@example.net", "name": "Jo Rivera" },
      "to": [ { "address": "bookings.acme@agents.example", "name": "" } ],
      "cc": [], "bcc": [], "reply_to": [],
      "subject": "Change of dates for BK-2291",
      "sent_at": "2026-09-14T08:12:00Z", "received_at": "2026-09-14T08:12:03Z",
      "labels": ["booking"], "flags": [],
      "trust": { "verdict": "pass", "spf": "pass", "dkim": "pass", "dmarc": "pass", "arc": "none",
                 "known_sender": true, "quarantined": false },
      "triage": { "category": "customer_request", "summary": "Asks to move pick-up to Friday.",
                  "needs_reply": 0.92, "urgency": 2, "risk_flags": [] },
      "attachments": [ { "id": "att_01J9…", "filename": "licence.jpg", "content_type": "image/jpeg",
                         "size": 81234, "sha256": "9f2c…" } ],
      "deliveries": null,
      "eml_path": "eml/idn_01J9…/20260914T081203Z_msg_01J9….eml",
      "eml_source": "original",
      "bcc_redacted": false
    }
  ]
}

• deliveries is set for outbound messages: [{ "address", "field", "status", "smtp_code", "updated_at" }].
• In a counterparty export, bcc contains the counterparty’s own address when present and nothing else; other Bcc recipients are never disclosed.
• Messages contain other people’s data. The controller reviews the export before disclosing it.

9.4 Download link

GET /v1/exports/{export_id} returns download_url, minted on each read with the current link key in the signed link format of Security › Signed links:

https://mail.example.com/v1/links/{token}
payload = "l1:{kid}:export:{tenant_id}:{export_id}:{expires_unix_s}"     expires = the export's expires_at

• The download needs no API key; the MAC authenticates it. A bad MAC, an expired link or an expired export returns 404 export_not_found.
• The response is the ZIP with Content-Type: application/zip, Content-Disposition: attachment; filename="exp_….zip" and the attachment-serving headers of Security.
• GET /v1/links/{token} serves both export and large-attachment links (REST API).

10. Receipt

The receipt matches the erasure request object:

{
  "messages_deleted": 14, "attachments_deleted": 9, "r2_objects_deleted": 38,
  "fts_rows_deleted": 14, "refs_deleted": 51, "vectors_deleted": 63,
  "events_deleted": 31, "identities_affected": ["idn_01J9…", "idn_01JA…"],
  "held": [ { "thread_id": "thr_01JA…", "reason": "PCN dispute WM12345678" } ],
  "probe": { "keyword_hits": 0, "semantic_hits": 0 }
}

• status is completed, completed_with_holds (at least one held entry) or failed.
• A receipt is always produced (NFR-PRV-1): a failed job writes the counts reached so far, and erasure.failed carries the failed step and error code.
• The receipt is stored in erasure_requests.receipt_json and jobs.result_json, and sent in erasure.completed.

11. What remains after deletion

Restores and erasure. A D1 or Durable Object restore can resurrect erased data. The restore runbook (Observability) therefore exports every erasure request completed after the restore point before restoring (pmail erasure list --json), and re-submits each one afterwards, with reason reapply_after_restore:{era_id}.

12. Logs

Logs follow Security › Logging rules: no content, no clear addresses, pseudonyms only, invocation_logs = false. Dead-letter records keep pointers in D1 for at most 14 days and are never returned by GET /v1/platform/dlq (pmail dlq list): it shows the queue, kind, tenant and times only. The I5 test greps the captured output of the whole integration run for canaries.

13. Tests