pushleft
Deploy your first app
Manual contents
Handbook
HandbookPushleftArchitecture
Operate
Install the control planeYour own serversFleetOperations and alertsAuthenticationDomains and DNSUsage and budgetsScheduled jobsAbuse controlsAI provider proxyCustomer mailErrors and performanceLogs and metricsRetentionObject storageContainer registryGit server
Develop
The .pl.yaml manifestOnboard with an AI agentThe pl up demoBuild executorSource ingestionAgent gatewayManaged databasesSecurity findingsTunnels and shellsDev workspacesPrivate hostnamesMesh coordinatorsDesign baseline
Runbooks
Control-plane host failoverControl-plane PostgreSQL failoverControl-plane PostgreSQL restoreCustom domains and certificatesGateway key compromiseIngress host failureNode busyNode disk fullNode drain and replacementNode lostRegistry outageHetzner Robot hostsSecret rotationSecurity incidentStaging fleet on ProxmoxStaging build cacheStuck deploymentVault/OpenBao backup and recovery
Manual · docs/mail.md

Customer mail

Your applications on Pushleft can send transactional mail, such as receipts, sign-in links and notifications, from your own domains. Pushleft creates the DKIM keys, tells you which DNS records to publish, signs every message and delivers it. It stops sending to addresses that bounce or complain.

Console A sending domain with its DKIM, SPF and DMARC records and their checks.

Quick start

  1. Add your sending domain. The command prints the DNS records to publish:

    pl mail domain add example.com

    Publish the records at your DNS host. When the domain is in a Pushleft-managed Cloudflare zone (domain registration), Pushleft writes them for you (Sending domains).

  2. Check the records and wait until the domain is verified:

    pl mail domain verify example.com --wait 120
  3. Create a mail token and store it as an environment secret:

    pl mail token create orders --production | pl secrets set MAIL_TOKEN --production

    The command prints the token on stdout only once. Without --production, the environment is this checkout’s preview/<branch>.

  4. Give the secret to the application in .pl.yaml (manifest secrets):

    roles:
      web:
        secrets: [{ name: MAIL_TOKEN, as: env }]
  5. Send a message from the application with POST /v1/send on the mail endpoint:

    curl https://mail.pushleft.dev/v1/send -H "Authorization: Bearer $MAIL_TOKEN" -H 'Content-Type: application/json' \
      -d '{"from": "Shop <[email protected]>", "to": ["[email protected]"], "subject": "Your order 1042", "text": "Thanks for your order."}'
  6. Check the delivery state of each recipient:

    pl mail log

Features

  • Sending from every verified domain of your organization, with Ed25519 and RSA DKIM signatures.
  • Up to 50 recipients and 10 attachments per message, at most 10 MiB (Sending).
  • Delivery from Pushleft’s own mail server. An external relay takes over when a receiver refuses the platform’s address (ESP fallback).
  • Retries for up to 3 days when a receiving server defers a message.
  • Automatic suppression of addresses that hard bounce or complain.
  • A message log on the console Mail page and in pl mail log, kept for 30 days. Pushleft does not keep subjects or bodies.
  • A daily quota by trust tier. A high bounce or complaint rate can pause your sending.

Pushleft does not send marketing mail or receive inbound mail for customers.

Sending domains

pl mail domain add example.com          # prints the records to publish
pl mail domain verify example.com --wait 120
pl mail domain list
pl mail domain remove example.com

POST /v1/mail/domains {"domain": "example.com"} (admins) creates the domain with two DKIM key pairs: Ed25519 (RFC 8463) and RSA-2048, for receivers that verify only RSA.

  • The API writes each private key to Vault, create-only, at organizations/<org>/mail/dkim/<domain with _ for .>/<selector> (field key, base64 PKCS#8).
  • PostgreSQL keeps the public halves and the Vault references. Nothing returns a private key.

The response and GET /v1/mail list the records:

RecordNameValueNeeded
Ownership TXT_pushleft-verify.<domain>a random valuerequired (not for a Pushleft zone)
DKIM Ed25519 TXTpl<id>e._domainkey.<domain>v=DKIM1; k=ed25519; p=…required
DKIM RSA TXTpl<id>r._domainkey.<domain>v=DKIM1; k=rsa; p=… (about 410 characters; DNS hosts split it into strings)required
Return path CNAMEpl-bounces.<domain>the platform bounce domain (PUSHLEFT_MAIL_BOUNCE_DOMAIN)required
SPF TXT<domain>v=spf1 include:<PUSHLEFT_MAIL_SPF_INCLUDE> ~all, merged into an existing SPF recordrecommended
DMARC TXT_dmarc.<domain>v=DMARC1; p=nonerecommended

Verification. pushleft-mail checks pending domains with real DNS queries: at once, then every 60 seconds for an hour, then every 10 minutes. pl mail domain verify checks within 5 seconds. So do POST /v1/mail/domains/{id}/verify and Check now in the console.

  • A domain is verified when Pushleft finds the ownership TXT, both DKIM keys and the return-path CNAME.
  • Pushleft reports SPF and DMARC but does not require them. DMARC alignment comes from the DKIM signature (d=<domain>) and from the return path. The return path is a subdomain of your domain, and the platform controls its SPF.
  • Pushleft checks a verified domain again every 24 hours. A failure shows in last_error, Pushleft then checks hourly, and sending continues. Gap: a domain does not lapse after repeated failures, unlike custom domains.
  • One organization at a time can verify a domain.

Pushleft-managed zones. Your domain can be in (or under) an active, proven Cloudflare zone of the same organization (domain registration). The zone’s ownership proof then covers it, so there is no ownership TXT. The API writes the records as application-managed record sets and queues the controller job that applies them:

  • one set with the DKIM and return-path records;
  • one set with SPF and DMARC.

A clash with an existing SPF or DMARC record therefore never blocks DKIM. When another record set of the zone already holds a record name, Pushleft leaves that record to you.

Sending works only from a verified domain of the token’s organization. The From: domain must match exactly. Removing a domain stops sending from it at once. Its DNS records and Vault keys stay (gap: no Vault delete, as for AI keys).

Tokens

A mail token belongs to one environment. Its format is plm_<prefix>_<secret>. The database keeps only the SHA-256 of the secret (API tokens).

pl mail token create orders --project shop --environment production
pl mail token list
pl mail token rotate <id> --overlap-minutes 10
pl mail token revoke <id>

The API is POST /v1/mail/tokens, POST /v1/mail/tokens/{id}/rotate and DELETE /v1/mail/tokens/{id} (members), as for AI tokens. Each change writes mail_token_created, _rotated or _revoked to the audit trail.

A project cannot be deleted while it has a mail token that still works. Revoke it first.

Sending

Applications reach the service on a public HTTPS hostname, for example https://mail.<base domain>. It runs behind the control plane’s TLS proxy, because application containers can reach public addresses only.

curl https://mail.pushleft.dev/v1/send -H "Authorization: Bearer $PUSHLEFT_MAIL_TOKEN" -H 'Content-Type: application/json' -d '{
  "from": "Shop <[email protected]>", "to": ["[email protected]"], "cc": [], "bcc": [],
  "reply_to": "[email protected]", "subject": "Your order 1042",
  "text": "Thanks for your order.", "html": "<p>Thanks for your order.</p>",
  "headers": {"X-Order": "1042", "List-Unsubscribe": "<https://example.com/u/abc>"},
  "attachments": [{"filename": "receipt.pdf", "content_type": "application/pdf", "content": "<base64>"}],
  "idempotency_key": "order-1042-receipt", "tags": ["receipt"]}'
RuleLimit
Recipientsto, cc and bcc together: 1 to 50 after removing duplicates. Bcc never appears in the message.
Bodytext, html or both (multipart/alternative)
HeadersX-* (not X-Pushleft-*), List-Unsubscribe, List-Unsubscribe-Post, In-Reply-To, References; at most 20, one ASCII line of at most 998 characters each. Everything else (From, To, Bcc, Received, DKIM-Signature, …) is refused.
Attachmentsat most 10; the encoded message at most PUSHLEFT_MAIL_MAX_MESSAGE_BYTES (10 MiB) → 413 message_too_large
Tagsat most 10, 1–64 characters of letters, digits, _ . : -
Idempotency keyat most 128 characters, per environment; a repeat returns 200 with the first message’s id and "duplicate": true and sends nothing

The answer is 202 with:

  • the message id;
  • the message_id header;
  • one deliveries entry per recipient;
  • the suppressed recipients that Pushleft skipped.

Refusals:

StatusCodeCause
401invalid_tokenunknown, revoked or expired token
400invalid_requestthe rules above
403domain_not_verifiedthe From domain is not a verified domain of the token’s organization
403org_suspendedthe organization is suspended (abuse controls)
402budget_exceededa hard-stop budget is spent (budgets)
403mail_pausedpaused for its bounce or complaint rate
429mail_quotathe recipients of this message would exceed the tier’s mail_per_day (rolling 24 h)
422recipients_suppressedevery recipient is suppressed

Every message gets a Message-ID of <random@from-domain> and two DKIM-Signature headers (relaxed/relaxed, SHA-256; Ed25519 and RSA). Pushleft stores the signed message once. Each recipient is a delivery with its own envelope.

Mail delivery

pushleft-mail is the send API, the policy layer and the delivery engine in one Rust service.

  • The queue is a PostgreSQL table: one row per recipient, leased with FOR UPDATE SKIP LOCKED.
  • The workers resolve the recipient domain’s MX with hickory and speak SMTP to it with lettre (rustls, no OpenSSL).
  • DKIM signatures come from mail-auth (Apache-2.0 OR MIT) with the ring backend.

The alternative was Postfix as the MTA behind a submission and policy service. Postfix is the more proven delivery engine. In this design, though, it would add a second queue next to the PostgreSQL one:

  • Delivery state would come back only by parsing Postfix logs.
  • The per-destination ESP fallback would mean rewriting transport maps at run time.
  • The end-to-end tests could not run Postfix on a developer machine without a container.

Pushleft must own part of an MTA anyway: who may send, retries, per-recipient state, fallback decisions and bounces. Pushleft writes that part, and lettre handles the SMTP protocol itself. Not built yet lists what is missing. Revisit the choice if delivery problems turn out to be protocol edge cases.

Delivery

A worker leases due deliveries (mail_lease). For each one, it does these steps:

  1. MX. It looks up the recipient domain’s MX records: at most 5, by preference. Without MX it uses the domain itself (RFC 5321 5.1). It takes 2 IPv4 addresses per host. NXDOMAIN or a null MX (RFC 7505) is a hard bounce. A DNS failure defers.
  2. SMTP. It connects to port 25 from PUSHLEFT_MAIL_SOURCE_IP with EHLO PUSHLEFT_MAIL_HOSTNAME.
    • It uses STARTTLS when offered, without certificate checks (opportunistic, as most MTAs do). When the TLS handshake fails, it tries once more in plain text.
    • The envelope sender is the VERP address b-<delivery id>@pl-bounces.<domain>, one recipient per transaction.
    • A network error tries the next address. Any SMTP reply decides.
  3. Outcome.
    • 2xx: delivered.
    • 4xx, greylisting included: deferred.
    • 5.1.x, 5.2.1 and plain 550 “no such user”: hard bounce. Pushleft suppresses the address.
    • 5.2.2 (mailbox full), 5.3.x, 5.4.x and 552: soft bounce. The bounce is final, but Pushleft does not suppress the address.
    • 5.7.x, and 554 or texts that name a block, blocklist, Spamhaus, reputation or policy: policy block. The destination refuses the platform, and the address is fine.

Retries. Pushleft tries a deferred delivery again on a fixed schedule (PUSHLEFT_MAIL_RETRY_SECONDS). The waits are 5 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h, 16 h and then daily. After 3 days in the queue (PUSHLEFT_MAIL_MAX_QUEUE_SECONDS), it becomes a soft bounce (“gave up after N attempts”). A greylisting server sees the second attempt after 5 minutes, as greylisting expects.

Limits per destination.

  • At most PUSHLEFT_MAIL_DOMAIN_CONCURRENCY (4) deliveries per destination domain are in flight across all workers. mail_lease enforces this.
  • At most PUSHLEFT_MAIL_DOMAIN_PER_MINUTE (120) start per minute per process. Above that, the delivery goes back for 30 seconds, and the attempt does not count.
  • PUSHLEFT_MAIL_WORKERS (16) bounds the tasks per process.

Paused and suspended organizations. Pushleft does not lease their queued deliveries. They wait, and expire as soft bounces once they are older than the retry window.

ESP fallback

The ESP relay is an SMTP URL in Vault, named by PUSHLEFT_MAIL_ESP_RELAY_REFERENCE. For example, vault://platform/mail/esp-relay#url can hold smtps://user:[email protected] or smtp://user:[email protected]:587?tls=required. Pushleft refuses plain SMTP, except to a loopback relay. The relay gets the same signed message and VERP envelope.

A relay that delivers while the connection waits, such as inbox2’s relay on its own IP, adds ?passthrough=true to the URL. Such a relay marks a reply that came from the recipient’s mail server with [remote <host>]. Pushleft classifies a marked reply like a direct delivery: a hard bounce suppresses the address, a policy block fails the delivery, a soft bounce or a 4xx is tried again. An unmarked reply is the relay’s own, such as a failed login, and is handled like any relay refusal. Pushleft waits up to 180 seconds for the reply, not 60.

A delivery goes through the ESP when:

ConditionHow
A destination rejects us with a policy blockat once, in the same attempt; the block is recorded
3 policy blocks from one destination domain within an houran automatic 24-hour fallback rule for that domain (mail_fallback_rules, automatic = true)
The platform’s IP is on a blocklist, or a domain blocks itan operator rule: * or the domain, below
The delivery is older than PUSHLEFT_MAIL_FALLBACK_AFTER_SECONDS (4 h) and was tried directly at least onceat the next attempt
pushleft-api mail fallback set '*' --reason "IP listed on Spamhaus SBL" --hours 48
pushleft-api mail fallback set outlook.com --reason "S3150 block" --operator alice
pushleft-api mail fallback list
pushleft-api mail fallback clear '*'

The operator commands run with the migration-owner or a BYPASSRLS DATABASE_URL, like the other operator commands.

  • Without --hours, a rule has no end.
  • A 4xx or connection error from the relay defers.
  • Any 5xx from the relay makes the delivery failed, because it is about the relay account and not the recipient.
  • A policy block with no relay configured is also failed.
  • failed deliveries are not bounces and do not count against the customer.

Bounces and complaints

Return path. Each delivery’s envelope sender is b-<delivery id>@pl-bounces.<customer domain>. pl-bounces.<domain> is a CNAME to the platform bounce domain, whose MX is the mail host. The delivery id is a random UUID, so a forged bounce cannot name a delivery it has not seen.

Bounce receiver. PUSHLEFT_MAIL_INBOUND_BIND (port 25 on the mail host) is a receive-only SMTP listener.

  • It accepts recipients of the VERP form (any domain) and fbl@ (feedback loops).
  • It refuses every other recipient with 550.
  • It reads at most 2 MiB per message.
  • It keeps only the outcome, never the message.

It reads two kinds of report:

  • DSN (RFC 3464). A multipart/report with a message/delivery-status part whose recipient block says Action: failed. Pushleft records it as a bounce of the delivery that the VERP recipient names. The bounce is hard for 5.x.x statuses that mean a bad address, and soft otherwise. Pushleft ignores delayed, delivered, auto-replies and other mail. A hard bounce suppresses the address. Every bounce records record_mail_event(org, delivery, 'bounced'), also for a delivery that was accepted earlier.
  • Feedback loops (ARF, RFC 5965). A message/feedback-report with Feedback-Type: abuse or fraud. Pushleft records it as a complaint about the delivery in Original-Mail-From, or else in any VERP address in the report (the quoted Return-Path). It suppresses the address and records complained, which can pause the organization at once.

Register fbl@<bounce domain> with the feedback loops that offer one: Microsoft JMRP and SNDS, Yahoo CFL, Comcast and others. Gmail has no per-message loop, so watch Postmaster Tools.

ESP events. Bounces and complaints of fallback deliveries arrive from the ESP. POST /v1/esp/events with Authorization: Bearer <secret> (PUSHLEFT_MAIL_WEBHOOK_SECRET_FILE) takes one event or {"events": [...]} (at most 100):

{"type": "bounce", "message_id": "<9f0c…@example.com>", "recipient": "[email protected]", "bounce_class": "hard", "detail": "smtp; 550 5.1.1"}

type is bounce, complaint or delivered (ignored). Pushleft finds the delivery by the Message-ID header and the recipient. Pushleft does not parse provider-specific formats. Map the provider’s notification to this shape in a small forwarder:

ProviderBounceComplaintMessage-IDRecipient
Amazon SES (SNS notification, Message JSON)notificationType = "Bounce", bounce.bounceType = "Permanent" → hard, "Transient" → softnotificationType = "Complaint"mail.commonHeaders.messageIdeach bounce.bouncedRecipients[].emailAddress / complaint.complainedRecipients[]
Postmark (webhook)RecordType = "Bounce", Type = "HardBounce" → hard, else softRecordType = "SpamComplaint"the Message-ID header (add it to the webhook’s headers, or look it up with MessageID)Email

SES and Postmark also send bounces to the envelope sender when they keep it. With SES custom MAIL FROM off, SES forwards to the original Return-Path. Those bounces reach the bounce receiver directly.

Suppressions.

  • GET /v1/mail/suppressions (viewers) lists them.
  • POST /v1/mail/suppressions {"address", "reason": "unsubscribe" | "manual"} (members) adds one.
  • DELETE /v1/mail/suppressions/{address} (admins) removes one. The audit trail records mail_suppression_removed.

Pushleft skips suppressed recipients at send time and lists them in suppressed. Unsubscribe links are your job (List-Unsubscribe is allowed). Pushleft does not host an unsubscribe page.

Limits, metering and the log

Counting. Each accepted recipient is one sent mail event and one mail_messages usage unit (record_mail_event, idempotency key mail:<delivery id>). A message to 3 recipients therefore counts 3 against mail_per_day and in the usage ledger. Bounce and complaint rates are per recipient, as ESPs count them.

The checks of customer mail quotas run twice per message:

  1. in mail_admit, before Pushleft builds the message;
  2. in mail_enqueue, under a lock on the organization.

Concurrent requests therefore cannot overrun the quota.

The log. GET /v1/mail/messages?recipient=&limit= and GET /v1/mail/messages/{id} (viewers), pl mail log and the console Mail page show each message’s sender, environment, tags and size. Per recipient they show:

  • the status: queued, delivered, bounced (hard or soft) or failed;
  • the route: direct or esp;
  • the attempts, the last SMTP code and error, and complaints.

Pushleft does not show or keep subjects and bodies. It deletes the signed message as soon as every delivery is final (body_retained). It deletes the metadata after 30 days (mail_retention_sweep, hourly). The service logs ids, organization, destination domain, route and outcome only.

Operations

pushleft-mail runs on the mail host (below) with deploy/systemd/pushleft-mail.service and mail.env.example. GET /healthz returns 204, and GET /readyz checks the database. The API needs PUSHLEFT_MAIL_BOUNCE_DOMAIN, optionally PUSHLEFT_MAIL_SPF_INCLUDE and PUSHLEFT_MAIL_URL, and its Vault token. Without them, adding a domain answers 503.

  • Database role. pushleft_mail, LOGIN NOBYPASSRLS, no table grants. It has EXECUTE on the ten mail_* functions of migration 0054 only (deploy/README.md). The API needs DELETE on mail_suppressions.
  • Vault. The mail service’s token carries deploy/vault/pushleft-mail.hcl: read on organizations/data/+/mail/dkim/* and platform/data/mail/*. The API’s token carries deploy/vault/pushleft-api.hcl: create only on the DKIM paths. Write the relay URL once with an operator token: bao kv put -mount=platform mail/esp-relay url='smtps://…'.
  • Platform DNS.
    • bounces.mail.<base>: MX 10 mta1.mail.<base>, plus A.
    • mta1.mail.<base>: A = the outbound IP.
    • _spf.mail.<base>: TXT v=spf1 ip4:<outbound IP> include:<ESP SPF, e.g. amazonses.com> -all.
    • The same SPF on bounces.mail.<base>, because every customer’s return path is a CNAME to it.
  • Alerts (control-plane.sql):
    • mail_queue_stale (ticket): deliveries of active organizations queued for over an hour.
    • mail_bounce_spike (page): over 5 % bounces or 0.1 % complaints platform-wide in the last hour, with at least 200 sends.
    • mail_esp_fallback_active (ticket): a live fallback rule.

On mail_bounce_spike:

  1. Find the organization: SELECT org_id, kind, count(*) FROM mail_events WHERE occurred_at > now() - interval '1 hour' GROUP BY 1, 2.
  2. Pause or suspend it (abuse controls).
  3. Check the blocklists below.

On mail_esp_fallback_active for an automatic rule, read the rejection text in the log of a recent delivery to that domain. Then follow that receiver’s postmaster process. The rule ends after 24 hours.

Robot mail host

The decision is to deliver from Pushleft’s own IP addresses on Hetzner Robot from day one. This section is the checklist for that host. Plan: none of it is done yet.

  1. A server of its own. Mail reputation belongs to an IP address. Use a dedicated Robot server, or at least a dedicated additional IPv4. This keeps customer workloads off the address. Hetzner can then close port 25 on it after complaints without touching anything else. Run pushleft-mail there, and nothing customer-facing.

  2. Port 25. Hetzner blocks outbound port 25 on new accounts and some products. Robot servers usually have it open. Confirm with an outbound test (nc -vz gmail-smtp-in.l.google.com 25), and ask Hetzner support to unblock it if needed. Open inbound port 25 in the Robot firewall for the bounce receiver.

  3. PTR (reverse DNS). In Robot, set the PTR of the outbound IPv4 to PUSHLEFT_MAIL_HOSTNAME (for example mta1.mail.pushleft.dev). Add an A record of that name back to the IP (forward-confirmed reverse DNS). Set PUSHLEFT_MAIL_SOURCE_IP to that IP. Delivery is IPv4 only. Leave IPv6 out until it has its own PTR and SPF.

  4. Warm-up. A new IP has no reputation. A large volume at once gets it throttled or blocked. Raise the volume over about four weeks, and watch bounces, deferrals and Postmaster data at each step. A schedule to start from (messages per day, all destinations):

    DaysPer dayNotes
    1–350–200Pushleft’s own mail and trusted customers only
    4–7500
    8–142 000 → 5 000open standard tier customers
    15–2110 000 → 20 000
    22–3050 000then follow demand

    Hold the volume with the tier quotas (org_tiers.mail_per_day, set lower during warm-up), PUSHLEFT_MAIL_DOMAIN_PER_MINUTE and PUSHLEFT_MAIL_DOMAIN_CONCURRENCY. Send the overflow through the ESP with an operator rule: for example * for the first days, then only the big mailbox providers. Do not push the IP.

  5. Blocklist monitoring. Check at least weekly, and on every mail_bounce_spike or mail_esp_fallback_active:

    • Spamhaus (ZEN, including the PBL; a Robot IP must not be in the PBL);
    • Barracuda and SpamCop;
    • UCEPROTECT level 1 (levels 2 and 3 list whole ranges; mostly ignore them);
    • Microsoft SNDS (sign up with the IP);
    • Google Postmaster Tools (verify bounces.mail.<base> and the customer domains that agree);
    • Yahoo Sender Hub.

    On a listing: set pushleft-api mail fallback set '*', find the organization (bounce and complaint rates per organization, above), stop it, then request delisting.

  6. abuse@ and postmaster@. The bounce receiver accepts only VERP addresses and fbl@. A person must read postmaster@ and abuse@ of the bounce domain and of the domain of PUSHLEFT_MAIL_HOSTNAME. Point those names’ MX at the platform mailbox for abuse@ (abuse mailbox), not at this host. Register abuse@ at abuse.net. Reports that arrive there go into the operator queue as abuse reports.

  7. Platform DNS as in Operations, and DMARC for the platform’s own domains.

Tests

  • cargo test -p pushleft-mail tests:
    • request validation: recipient limit, header allowlist, attachment size, tags;
    • the built message (Bcc absent);
    • DKIM signatures with both keys, verified by mail-auth’s verifier, and a tampered body that fails;
    • SMTP reply classification, the retry schedule and give-up, and the fallback decision;
    • VERP round trips and the per-domain rate;
    • DSN and ARF parsing, and the bounce receiver’s recipients and DATA handling;
    • token parsing and the relay URL rules.
  • cargo test -p pushleft-api mail:: tests the DNS records (also as a valid managed-zone record set) and key generation.
  • npm run test:mail (scripts/mail-e2e.sh) runs the real API, CLI and mail service against PostgreSQL, the DNS stub and scripts/fixtures/mail-fakes.py. The fakes are a Vault with separate API and mail policies and an ESP relay with SMTP AUTH. A fake recipient MX checks both DKIM signatures with its own pure-Python verifier. The mail service runs as a role with only its functions. The test covers:
    • domain verification through pl mail domain, and tokens through pl mail token;
    • direct delivery with VERP and independently verified DKIM, Bcc and idempotency;
    • greylisting, hard bounce and suppression;
    • policy block to ESP, the automatic and operator fallback rules, and queue-age fallback;
    • DSN and ARF on the bounce receiver, and the ESP webhook;
    • the complaint pause and unpause, suspension, hard-stop budget and tier quota;
    • unverified domains and other organizations’ domains, and isolation;
    • metering per recipient, retention, and no message content in the logs.

Not proven. No message has gone to a real mailbox provider yet. These are untested: deliverability, the reputation of a Robot IP, the PTR and port 25 on Hetzner, and a real ESP relay and its events. The fake MX does not offer STARTTLS, so the TLS path (and its plain-text retry) has only run in lettre’s own tests.

Planned

  • SMTP submission (port 587) for applications that cannot call an HTTP API.
  • MTA-STS and DANE (outbound TLS is opportunistic only) and IPv6 delivery.
  • Several outbound IPs or IP pools per tier.
  • Connection reuse and pipelining (one transaction per recipient).
  • Parsing SES/SNS and Postmark events directly (a forwarder maps them to the generic webhook), SNS signature checks.
  • Non-RFC 3464 bounces (free-text bounces are ignored), DMARC aggregate reports (rua), a hosted unsubscribe page.
  • Lapse of a verified domain whose records disappear; Vault deletion of removed keys; DKIM key rotation.
  • STARTTLS on the bounce receiver.
  • Sending a domain’s mail through Amazon SES as a paid upgrade (decided 2026-11-01, not built). The domain gets its own SES sender that can send only for that domain.
  • Customer mail through inbox2 (decided earlier, Cut 3; confirmed 2026-11-11). Own-IP delivery and its warm-up move to inbox2, which already has an extra IP. An inbox2 agent warms the IP up with inbox2’s own mail and builds a delivery API that Pushleft calls. This replaces the Robot mail host below. Until then, customer domains can relay through SES (the * fallback rule, each domain verified in SES). Phase (pitchslide) sends through Messy meanwhile.
Rendered from the repository at build time. Edit docs/mail.md to change it.