21e7058862
Fork anchor, strip all push notification code (APNs, FCM, WebPush), rename from anchor to mailship, add new database schema for subscriptions + events tables, and add HTTP API for email notification registration and NIP-9a relay push callbacks. - POST /subscription/email — register for email digests - DELETE /subscription/:key — unsubscribe - POST /notify/:id — NIP-9a relay push callback - GET /confirm?token=... — confirm email - GET /unsubscribe?token=... — unsubscribe Co-authored-by: mplorentz
84 lines
No EOL
2.5 KiB
Markdown
84 lines
No EOL
2.5 KiB
Markdown
# 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 (POST /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) |
|
|
| `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
|
|
|
|
### POST /subscription/email
|
|
Register for email digests.
|
|
|
|
```
|
|
Body: { email, frequency, pubkey }
|
|
Auth: NIP-98 (planned)
|
|
Response: { key, callback }
|
|
```
|
|
|
|
### 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
|
|
|
|
```sh
|
|
pnpm install
|
|
pnpm run build
|
|
pnpm run start
|
|
```
|
|
|
|
## Forked from Anchor
|
|
|
|
Mailship is a fork of [Anchor](https://github.com/coracle-social/anchor), stripped of push notification support and adapted for NIP-9a relay push event intake. |