mplorentz 5abec46cb7 Make subscription upsert idempotent via PUT

Switch the subscribe endpoint from POST to an idempotent PUT so clients can
always upsert without a stateful lookup first.

- Add GET /subscription/email?pubkey= lookup so clients can avoid re-POSTing.
- insertSubscription no longer clears confirmed_at unless the email address
  changes; a frequency change keeps the existing confirmation.
- registerSubscription only sends a confirmation email when the subscription
  is new, unconfirmed, or the email address changed.
- Update integration test and README for the PUT endpoint.

2026-09-03 11:47:21 -04:00

4 KiB

Raw Blame History

Mailship

A Nostr email notification server. Receives events pushed from relays via NIP-9a, stores them, and sends daily or weekly digest emails.

Architecture

Flotilla ──HTTP──▶ Mailship (PUT /subscription/email)
  │                   NIP-98 auth
  │                   returns {key, callback}
  │
  └──kind 30390──▶ relay or NPB
                         │
                    event matches filter
                         │
                         ▼
                    POST /notify/:subId ──▶ Mailship
                         {id, relay}         │
                           UUID in path      ├── fetch event from relay
                           is the auth       ├── store in SQLite (dedup)
                                             │
                                        cron fires ──▶ render digest ──▶ Postmark ──▶ email

Configuration

Variable	Required	Description
`MAILSHIP_SECRET`	✓	A nostr private key hex string for the server's identity
`MAILSHIP_NAME`	✓	Name of this Mailship instance
`MAILSHIP_URL`	✓	Public URL of this instance
`BASE_URL`	✓	Base URL for callback URLs (same as MAILSHIP_URL typically)
`EVENT_VIEWER_URL`		Base URL of the app event links open in (defaults to Flotilla at `https://app.flotilla.social`, or anything handling the same `/spaces/<relay>/<hash>` and `/<nevent>` URL shapes)
`BRAND_NAME`		Name used in email branding (default: `Flotilla`)
`BRAND_ACCENT`		Accent color string used in email branding (default: `#7161FF`)
`BRAND_LOGO`		URL of the logo image shown in the email header. Defaults to `<EVENT_VIEWER_URL>/logo.png`; if empty/unset, a colored brand name is shown instead
`POSTMARK_API_KEY`	✓	Postmark API key for sending emails
`POSTMARK_SENDER_ADDRESS`	✓	Verified sender email in Postmark
`DEFAULT_RELAYS`	✓	Comma-separated list of default relays
`INDEXER_RELAYS`	✓	Comma-separated list of indexer relays
`SEARCH_RELAYS`	✓	Comma-separated list of search relays
`PORT`		Port to run on (default: 3000)

API

PUT /subscription/email

Idempotently register or update an email subscription. Re-sends the confirmation email only when the subscription is new or the email address changed; a frequency change keeps the existing confirmation.

Body: { email, frequency, pubkey }
Auth: NIP-98 (planned)
Response: { key, callback }

GET /subscription/email?pubkey=...

Look up an existing subscription, so clients can avoid re-registering (and re-confirming) when settings haven't changed. Returns 404 if none exists.

Response: { key, callback, email, frequency, confirmed }

DELETE /subscription/:key

Unsubscribe.

Auth: NIP-98 (planned)
Response: { ok: true }

POST /notify/:id

NIP-9a relay push callback. Called by relays or NPB when matching events are found.

Body: { id, relay }
Response: { ok: true, stored: boolean }
Returns 404 if subscription not found or inactive.

GET /confirm?token=...

Confirm email address via link from confirmation email.

GET /unsubscribe?token=...

Unsubscribe via link from digest email.

Development

pnpm install
pnpm run build
pnpm run start

Previewing the digest email

To iterate on the email template, render it with sample data and open the result in your browser:

pnpm run preview:digest
open digest-preview.html

Docker

Quick start

cp .env.template .env
# Fill in your secrets in .env
docker compose up -d

Build and run manually

docker build -t mailship .
docker run -d \
  -p 4738:4738 \
  -v mailship-data:/data \
  --env-file .env \
  mailship

Tests

pnpm test          # Run integration tests
pnpm test:server   # Start server for manual testing

Forked from Anchor

Mailship is a fork of Anchor, stripped of push notification support and adapted for NIP-9a relay push event intake.

4 KiB Raw Blame History