# LNemail

> LNemail is a privacy-focused, anonymous disposable email service powered by Bitcoin Lightning Network payments. Users pay with Lightning to get a fully functional email account instantly -- no signup, no personal information, no passwords required. Accounts are valid for one year, and renewable from then on.

- Base URL: `https://lnemail.net`
- API base: `https://lnemail.net/api/v1`
- Authentication: Bearer token in `Authorization` header (token provided on account creation)
- Payments: All operations require Lightning Network invoice payments (BOLT11)
- Account price: 1000 satoshis (creates a 1-year email account)
- Send price: 100 satoshis per outgoing email
- Attachment limit: 8 MB total per outgoing email
- Email addresses are randomly generated (e.g., `sereneforest630@lnemail.net`)

## API Documentation

- [Create Email Account](https://lnemail.net/api/v1/email): `POST /api/v1/email` -- Creates a new email account and returns a Lightning invoice. Optional JSON body: `{"include_email": bool, "include_token": bool}` to embed details in the invoice memo. Returns: `email_address`, `access_token`, `payment_request` (BOLT11 invoice), `payment_hash`, `expires_at`, `price_sats`.
- [Check Payment Status](https://lnemail.net/api/v1/payment/{payment_hash}): `GET /api/v1/payment/{payment_hash}` -- Poll this endpoint after paying the invoice. Returns `payment_status` ("pending", "paid", "expired", "failed"). When paid, also returns `email_address` and `access_token`.
- [Get Account Info](https://lnemail.net/api/v1/account): `GET /api/v1/account` -- Returns the authenticated account's `email_address` and `expires_at`. Requires Bearer token.
- [List Emails](https://lnemail.net/api/v1/emails): `GET /api/v1/emails` -- Lists all emails in the inbox (newest first). Returns `{emails: [{id, subject, sender, date, read}]}`. Requires Bearer token.
- [Get Email Content](https://lnemail.net/api/v1/emails/{email_id}): `GET /api/v1/emails/{email_id}` -- Retrieves full email content including `body`, `body_plain`, `body_html`, `attachments` (with `filename`, `content_type`, `size`, `content`, `encoding`). Requires Bearer token.
- [Delete Email](https://lnemail.net/api/v1/emails/{email_id}): `DELETE /api/v1/emails/{email_id}` -- Deletes a single email. Requires Bearer token.
- [Bulk Delete Emails](https://lnemail.net/api/v1/emails): `DELETE /api/v1/emails` -- Deletes multiple emails. JSON body: `{"email_ids": ["id1", "id2"]}`. Requires Bearer token.
- [Send Email](https://lnemail.net/api/v1/email/send): `POST /api/v1/email/send` -- Initiates sending an email by generating a Lightning invoice. JSON body: `{"recipient": str, "subject": str, "body": str, "in_reply_to": str|null, "references": str|null, "attachments": [{filename, content_type, content (base64)}]}`. Returns: `payment_request`, `payment_hash`, `price_sats`, `sender_email`, `recipient`, `subject`. Requires Bearer token.
- [Check Send Status](https://lnemail.net/api/v1/email/send/status/{payment_hash}): `GET /api/v1/email/send/status/{payment_hash}` -- Returns both `payment_status` and `delivery_status` ("pending", "sent", "failed", "expired") for an outgoing email, plus `delivery_error` and `retry_count` if applicable.
- [Recent Sends](https://lnemail.net/api/v1/email/sends/recent): `GET /api/v1/email/sends/recent` -- Returns the last 10 sent emails with `payment_hash`, `recipient`, `subject`, `payment_status`, `delivery_status`, `created_at`, `sent_at`. Requires Bearer token.
- [Health Check](https://lnemail.net/api/health): `GET /api/health` -- Returns `{status, version, timestamp}`.

## Guides

- [Terms of Service](https://lnemail.net/tos): Usage policies, prohibited content, and service limitations.

## Usage Flow

- [Account Creation Flow]: 1) `POST /api/v1/email` to get an invoice. 2) Pay the BOLT11 Lightning invoice with any Lightning wallet. 3) Poll `GET /api/v1/payment/{payment_hash}` until `payment_status` is "paid". 4) Save the `email_address` and `access_token` -- the token is your only authentication credential.
- [Sending Email Flow]: 1) `POST /api/v1/email/send` with Bearer auth and email details. 2) Pay the returned Lightning invoice. 3) Poll `GET /api/v1/email/send/status/{payment_hash}` until `delivery_status` is "sent". Failed deliveries are automatically retried with escalating delays.
- [Reading Email Flow]: 1) `GET /api/v1/emails` with Bearer auth to list inbox. 2) `GET /api/v1/emails/{email_id}` to read full content and attachments.

## Optional

- [OpenAPI Schema](https://lnemail.net/openapi.json): Full OpenAPI/Swagger specification auto-generated by FastAPI.
- [Nostr NIP-05](https://lnemail.net/.well-known/nostr.json): Nostr identity verification endpoint for the lnemail.net domain.