DEPLOY.md's "Implemented so far" line still described the API as it was at the initial skeleton commit (POST/GET /emails only) and claimed attachments[].path/content_type/content_id return a 422 "not yet supported" - all three have been fully implemented (with SSRF-guarded URL fetching for path) since the Round 1a merge. Only topic_id is actually unsupported. This matters for distribution: the product's whole pitch is "switch from Resend with one line," and the deploy doc customers read to evaluate migration was understating the real API surface (domains, api-keys, webhooks, broadcasts, audiences/contacts, segments, contact-properties, topics, templates, suppressions, logs, metrics, inbound mail - none of which were mentioned at all) and incorrectly telling them a commonly-used Resend field (attachment by URL) isn't supported when it is. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
19 KiB
Deploying Scribase Mail to the Scribase box
Target: https://mail.scribase.com on the Scribase box (ssh box), behind the
box's Caddy. Stack: deploy/compose.scribase-mail.yml (web + Postgres + Redis,
local bind mounts, 1.47 GB total memory limit). No Neon, no external database.
Nothing here has been run yet. Do not start while another deploy is running on the box, and check disk first (the image build needs about 3 GB free).
0. Preconditions
-
DNS:
mail.scribase.comCNAME/A to the box (Cloudflare, orange cloud, SSL mode Full (strict)). The*.scribase.comOrigin CA cert is already at/etc/caddy/certs/scribase-origin.{pem,key}(used byscribase-api). -
OCI Email Delivery (eu-frankfurt-1): SMTP credential and an API signing key for a user allowed to
manage email-familyin the compartment. The values used by Rally are in~/.rally-secrets/oci-smtp.env(SMTP) and~/.oci/config(API) on the Mac. -
OCI Logging, for delivered / bounced / complained events: the same API user must be able to create the log group and service logs and read log content. Policy statements (group of the API user, same compartment as
OCI_COMPARTMENT_ID, orin tenancywhen that is unset):Allow group <api-user-group> to manage log-groups in compartment <compartment> Allow group <api-user-group> to read log-content in compartment <compartment>manage log-groupscovers CreateLogGroup/CreateLog; enabling a service log also needs update rights on the email domain, which the existingmanage email-familygrant already gives;read log-contentis what the Logging Search API needs (docs.oracle.com Logging > Logs and Log Groups). Users in the Administrators group need nothing extra. Without these, sending still works and bounces/complaints fall back to the 5-minute suppression-list poll, but there are no "delivered" events. -
DNS for the Resend-compatible API host:
mail-api.scribase.comCNAME/A to the box (orange cloud, same asmail.scribase.com). It must stay a single-level subdomain: Cloudflare Universal SSL and the*.scribase.comOrigin CA cert do not coverapi.mail.scribase.com. -
FROM_EMAILmust be on a domain that is ACTIVE in OCI Email Delivery.scribase.comis already an OCI email domain; useScribase Mail <noreply@scribase.com>or addmail.scribase.comin OCI first.
1. Disk and memory check (on the box)
ssh box 'df -h / && free -m && docker system df'
Stop if / is above 80% after accounting for ~3 GB of build layers. Free space
with docker builder prune -f and docker image prune -f (never prune volumes).
2. Ship the source
The repository is not published yet. From the Mac:
cd ~/products/scribase-mail-studio
git archive --format=tar.gz --prefix=scribase-mail-studio/ HEAD > /tmp/scribase-mail.tgz
scp /tmp/scribase-mail.tgz box:/tmp/
ssh box 'sudo mkdir -p /opt/scribase-mail && sudo chown $USER /opt/scribase-mail \
&& tar -xzf /tmp/scribase-mail.tgz -C /opt/scribase-mail --strip-components=1 \
&& rm /tmp/scribase-mail.tgz'
(Once github.com/caelum0x/scribase-mail-studio exists: git clone into
/opt/scribase-mail and git checkout <sha> instead.)
3. Secrets (on the box)
ssh box
sudo mkdir -p /etc/scribase-mail /srv/scribase-mail/data
# OCI API private key (copy from the Mac: scp ~/.oci/oci_api_key.pem box:/tmp/oci.pem)
sudo install -m 600 -o root /tmp/oci.pem /etc/scribase-mail/oci_api_key.pem && rm /tmp/oci.pem
# The web container runs as root in the image, so 600 root works.
cd /opt/scribase-mail
cp deploy/.env.example deploy/.env && chmod 600 deploy/.env
# Fill in: NEXTAUTH_SECRET (openssl rand -base64 32), POSTGRES_PASSWORD
# (openssl rand -hex 24), SMTP_USER/SMTP_PASS, OCI_TENANCY/OCI_USER/
# OCI_FINGERPRINT, ADMIN_EMAIL, GIT_SHA=<commit>. Billing (optional): section 8.
4. Build and start
cd /opt/scribase-mail
docker compose -f deploy/compose.scribase-mail.yml --env-file deploy/.env build web
docker compose -f deploy/compose.scribase-mail.yml --env-file deploy/.env up -d
docker compose -f deploy/compose.scribase-mail.yml --env-file deploy/.env logs -f web
# expect: "Deploying prisma migrations" ... "Starting web server"
curl -fsS http://127.0.0.1:4350/api/health # {"data":"Healthy"}
docker builder prune -f # reclaim build cache
Migrations (prisma migrate deploy) run on every web start.
5. Caddy
# on the Mac, in infra-box:
cp ~/products/scribase-mail-studio/deploy/scribase-mail.caddy ~/products/infra-box/caddy/sites/
# commit + pull infra-box on the box, then add "scribase-mail" to CADDY_SITES in
# /etc/products/caddy.env and run:
ssh box 'sudo /opt/infra-box/install.sh caddy'
curl -fsS https://mail.scribase.com/api/health
scribase-mail.caddy holds two site blocks, so the one CADDY_SITES entry
also serves the Resend-compatible API host:
| Host | Serves |
|---|---|
mail.scribase.com |
dashboard, native API /api/v1/*, Resend API at /api/resend/* |
mail-api.scribase.com |
Resend API only: Caddy runs rewrite * /api/resend{uri}, so /emails?limit=2 reaches /api/resend/emails?limit=2 and nothing else of the app is exposed |
Checked with infra-box/caddy/test/validate.sh and a caddy:2 container (query
strings preserved).
# expect 401 {"statusCode":401,"name":"missing_api_key",...}
curl -sS https://mail-api.scribase.com/emails
6. Smoke test
- Open
https://mail.scribase.com/login, sign in withADMIN_EMAIL(one-time code fromFROM_EMAIL). - Admin > Email provider: SMTP relay and Email Delivery API both "Connected".
- Domains > add a test domain (e.g.
mail.scribase.comif not in OCI yet), publish the CNAME/TXT records, wait for "Verified". - Developer settings > API keys > create, then:
curl -sS https://mail.scribase.com/api/v1/emails \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"from":"hello@<domain>","to":"<you>","subject":"Scribase Mail test","html":"<p>ok</p>"}'
The email should reach SENT within seconds (approved sender auto-created on
the first send) and DELIVERED within about 1-5 minutes (OCI Logging ingest
delay plus the one-minute poll).
- Delivery events. On its first run the delivery log poll job creates the
scribase-maillog group (OCI_LOG_GROUP_NAME) and, for every verified domain, anemaildeliveryservice log per category (outboundrelayed,outboundaccepted) with the OCI email domain as resource. This also covers domains that existed before this feature; nothing to click in the Console. Check in OCI Console > Observability > Logging > Log groups, or:
docker logs scribase-mail-web 2>&1 | grep -E "DeliveryLogPollJob|OciDeliveryLogs"
A "Could not enable delivery logs" warning with 404/NotAuthorized means the IAM policy above is missing (retried every 30 minutes). If a domain's logs were already enabled from the Console into another log group in the same compartment, that is fine: the search covers the whole compartment.
- Resend SDK compatibility. Point the official SDK at the API host; only the
base URL changes (API keys are Scribase Mail
us_...keys):
# Node: RESEND_BASE_URL or the baseUrl option
RESEND_BASE_URL=https://mail-api.scribase.com RESEND_API_KEY=$KEY node -e '
const { Resend } = require("resend");
new Resend().emails.send({ from: "hello@<domain>", to: "<you>", subject: "SDK test",
html: "<p>ok</p>", scheduledAt: "in 2 min" }).then(console.log)'
# Python: RESEND_API_URL=https://mail-api.scribase.com
The path-prefix form https://mail.scribase.com/api/resend works too (the
SDK concatenates base URL and path). Implemented: emails (send, batch,
get, update, cancel, reschedule, received inbound mail + attachments),
domains, api-keys, webhooks, broadcasts, audiences/contacts,
segments, contact-properties, topics, templates, suppressions,
logs, metrics. Attachments support both content (base64) and path
(fetched server-side with SSRF guards: HTTPS only, no redirects, no
private/reserved IPs, 40 MB cap) plus content_type/content_id for
inline images. topic_id is the one field still rejected with a 422
(not supported yet) instead of being silently dropped; every other
unknown field is also rejected rather than dropped. API keys with
"Sending access" can only call POST /emails and POST /emails/batch
(Resend semantics) on both APIs. Default rate limit is 10 req/s per team
(Admin > Teams to change it per team), shared by both APIs.
In cloud mode a new team's first emails are HELD for review: open
Admin > Review, check the preview, and click Approve (or "Approve and trust
team" for your own team). The email should then reach SENT within seconds
(approved sender auto-created on the first send). A test with a link to a
listed phishing domain should be refused with 400 Email rejected by content screening.
7. Backups
# nightly dump, keep 14 days (add to the box crontab)
0 3 * * * docker exec scribase-mail-postgres pg_dump -U scribase_mail -Fc scribase_mail \
> /srv/scribase-mail/backups/$(date +\%F).dump && find /srv/scribase-mail/backups -mtime +14 -delete
8. Billing (Dodo Payments)
Billing is optional. Without the Dodo keys the app runs normally and the
billing page shows "Billing not configured". Prices and quotas live in one
file, packages/lib/src/constants/pricing.ts; the Dodo products below must
match it (Free 3,000/mo + 100/day + 1 domain; Pro $20 with 50,000/mo and 10
domains; Scale $90 with 100,000/mo and 1,000 domains; $0.90 per 1,000 extra
emails on Pro and Scale).
Do everything in test mode first, then repeat in live mode.
Production state (2026-10-08, created via the Dodo API in live mode on the
shared business): meter mtr_0NpFcOMHHeIraqL8p95ok (event
scribase_mail.email.sent, sum over emails), Pro pdt_0NpFcORN2iMOkMVRw7VBG,
Scale pdt_0NpFcOUMth7PWNLxeoKTA (usage-based price: fixed $20 / $90 monthly,
meter at price_per_unit "0.09" = 0.09 cents per email, free threshold
50,000 / 100,000), webhook ep_3KNwODDOloA51pjBbf2ZX2Buiu9. The event name is
namespaced because Dodo meters are business-wide and other products share the
business; set DODO_USAGE_EVENT_NAME to match. Over the API,
price_per_unit is in the lowest denomination (cents), not dollars.
- Meter (Dashboard > Products > Meters > Create):
name
Emails sent, event nameemail.sent, aggregation Sum over metadata keyemails, unitemails. Copy the id (mtr_...). The app reports one event per team per UTC day (idscribase-mail:usage:<teamId>:<date>, so repeats are ignored). - Pro product (Products > Create > Subscription): name
Scribase Mail Pro, $20.00 every 1 month, tax category SaaS. Under usage pricing attach theEmails sentmeter: price per unit0.0009(=$0.90 per 1,000), free threshold50000. Copy the id (pdt_...). - Scale product:
Scribase Mail Scale, $90.00 monthly, same meter at0.0009, free threshold100000. Copy the id. - Customer portal (Settings > Customer portal): enable cancel and payment-method update. Optionally put Pro and Scale in one product collection to allow switching from the portal.
- Webhook (Developer > Webhooks > Create): URL
https://mail.scribase.com/api/webhook/dodo. Subscribe tosubscription.active,subscription.renewed,subscription.updated,subscription.plan_changed,subscription.on_hold,subscription.cancelled,subscription.failed,subscription.expired,payment.succeeded,payment.failed. Copy the signing secret (whsec_...). The Dodo business is shared with other products: events for other product ids are acknowledged and ignored. - API key (Developer > API keys): create a key for this app.
- On the box, add to
deploy/.env(never commit it):
DODO_PAYMENTS_API_KEY=...
DODO_PAYMENTS_WEBHOOK_KEY=whsec_...
DODO_PAYMENTS_ENVIRONMENT=test_mode # live_mode with live keys
DODO_PRODUCT_ID_PRO=pdt_...
DODO_PRODUCT_ID_SCALE=pdt_...
DODO_USAGE_METER_ID=mtr_...
DODO_USAGE_EVENT_NAME=email.sent
then docker compose ... up -d web (no rebuild needed).
8. Test: Settings > Billing > Pro > Upgrade, pay with a Dodo test card.
The team flips to Pro after subscription.active (the return page polls).
Dashboard > Webhooks > delivery log should show 200s; a resent delivery
returns {"status":"duplicate"}. After a day of sending, Dashboard >
Meters shows the email.sent events.
9. Go live: recreate meter, products and webhook in live mode, swap all
seven values, set DODO_PAYMENTS_ENVIRONMENT=live_mode, restart web.
Behaviour: active/past_due grant the plan; on_hold (renewal failed)
keeps the plan but applies Free limits until the payment is fixed;
cancelled/expired/failed return the team to Free. Cancel from the app
ends the plan at the end of the paid period. Warm-up caps for new teams still
apply on every plan (the stricter limit wins).
Inbound MX (Wave 3 — receiving emails)
Receiving email requires a separate mx Docker service and firewall changes.
DNS
- Add
inbound.scribase.com→ box public IP as a Cloudflare DNS record with the grey cloud (DNS only, not proxied). Cloudflare's proxy does not forward raw SMTP. - For each customer domain that has Receiving enabled, show them the MX
record that appears in Dashboard > Domains > DNS Records:
MX @ 10 inbound.scribase.com.
OCI firewall
OCI Compute instances have a default security list that blocks inbound port 25. You must open it explicitly:
- OCI Console → Networking → Virtual Cloud Networks → your VCN →
Security Lists → your instance's security list → Add Ingress Rule:
- Source CIDR:
0.0.0.0/0 - Protocol: TCP
- Destination port: 25
- Source CIDR:
- Also check the instance's OS firewall (iptables/nftables):
sudo iptables -I INPUT -p tcp --dport 25 -j ACCEPT
Note
: OCI blocks outbound port 25 from Compute instances but inbound TCP port 25 is allowed once you add the security list rule. This has been documented in OCI docs but always verify against the current console.
Start the MX service
# Add to deploy/.env:
INBOUND_ENABLED=true
INBOUND_INTERNAL_SECRET=$(openssl rand -hex 32)
INBOUND_MX_HOSTNAME=inbound.scribase.com
# optional: INBOUND_SSL_KEY_PATH / INBOUND_SSL_CERT_PATH for STARTTLS
cd /opt/scribase-mail
docker compose -f deploy/compose.scribase-mail.yml --env-file deploy/.env \
--profile mx build mx
docker compose -f deploy/compose.scribase-mail.yml --env-file deploy/.env \
--profile mx up -d mx
docker compose ... logs -f mx
# expect: "[inbound] MX server listening on port 25 (STARTTLS)"
Test from a remote machine:
# Check MX record resolves
dig MX yourdomain.com
# Send a test mail (Resend API or swaks)
swaks --to test@yourdomain.com --from sender@example.com \
--server inbound.scribase.com --port 25
Rollback
cd /opt/scribase-mail
docker compose -f deploy/compose.scribase-mail.yml --env-file deploy/.env down # keeps data
# remove "scribase-mail" from CADDY_SITES and re-run install.sh caddy
To roll back to a previous build, set GIT_SHA to the previous image tag
(docker images scribase-mail) and up -d again. Data stays in
/srv/scribase-mail/data.
Abuse controls (content screening + review queue)
Every email (API, SMTP proxy, campaigns, scheduled) passes one gate in the send queue right after the limit check:
- Reject: link to a host on a threat feed or in
SCREENING_BLOCKED_DOMAINS, or an executable/script/disk-image attachment (.exe .js .scr .iso .lnk ...). The API and SMTP proxy return400 Email rejected by content screening: <reason>; campaigns are refused when scheduled. Each such rejection is a strike; 3 strikes in 7 days block the team (blockedReason: CONTENT: ...) and emailADMIN_EMAIL. - Hold: raw-IP links, URL shorteners, link text showing a different
domain than the href,
javascript:/data:links, base64-only bodies, macro/html/svg attachments, marketing mail without unsubscribe, or a heuristic score >= 5 (phishing/crypto/gift-card language, all-caps subject, hidden text, forms...). Thresholds live inapps/web/src/lib/constants/sending-policy.ts(SCREENING_POLICY). - First sends: in cloud mode a new team's emails are held until it has
sent 20 emails and is 48 hours old (
FIRST_SENDS_REVIEW/FIRST_SENDS_REVIEW_EMAILS/FIRST_SENDS_REVIEW_HOURS), unless the team is admin-verified or trusted.
Held emails show as HELD in the customer's email log and in
GET /api/v1/emails/{id} (latestStatus). The admin gets at most one email
per 30 minutes about the queue. Review at Admin > Review
(/admin/review): the preview runs in a sandboxed iframe with a CSP that
blocks scripts and every remote load. Actions: Approve, Approve and trust team
(ends the first-sends review for that team), Approve all from this team,
Reject (optional note shown to the customer), Reject and block team.
Threat feeds are downloaded every 6 hours (SCREENING_FEED_CRON) into Redis
as a ~3 MB hash index (8 bytes per host); a refresh briefly uses ~30 MB. If a
feed download fails the previous index is kept; if Redis is down, screening
continues with heuristics only. Default feed:
Phishing.Database
active phishing domains (MIT license, commercial use allowed, ~390k hosts).
Shared platforms the feed lists (sites.google.com, vercel.app, ...) are
exempt so legitimate mail isn't rejected; subdomains on them still match.
Feeds deliberately not used by default because their terms forbid or
restrict commercial use: Spamhaus DNSBLs, Google Safe Browsing Lookup v4,
OpenPhish community feed (non-commercial only), abuse.ch URLhaus/ThreatFox
(Auth-Key required; commercial use may need a paid subscription), Phishing
Army (CC BY-NC). Add a feed to SCREENING_FEED_URLS only after checking its
terms.
Notes
- Self-hosted mode (
NEXT_PUBLIC_IS_CLOUD=false) lets anyone who can sign in create a team and send through the owner's OCI tenancy once their domain is verified. Keep email sign-in limited (for example onlyADMIN_EMAILand invited users) until abuse controls are in place. - Delivery events come from the OCI Email Delivery "OutboundRelayed" log
(
relay-> delivered,bounce-> bounced, hard = permanent / soft = transient,complaint-> complained), read every minute via Logging Search (DELIVERY_LOG_POLL_CRON). OCI open/click/unsubscribe records are ignored; Scribase Mail tracks those itself. The suppression-list poll stays as a fallback; the same bounce/complaint for the same recipient is counted once. - OCI daily/rate limits apply to the whole tenancy, shared with Rally and other products. Set Admin > Email provider > Send rate accordingly.