Send mail to this val's address and it comes out as clean, archiveable markdown: HTML converted, quoted reply chains and signatures stripped, YAML frontmatter prepended.
Delivery anywhere else — GitHub gists, routing by sender or List-Id — is deliberately stubbed out for now. See Adding a destination.
Everything except /auth/* sits behind "Log in with Val Town" (std/oauth). Verified against the live endpoint:
| Request | Result |
|---|---|
GET /api/emails (no session) | 401 {"error":"unauthorized"} |
GET / (no session) | redirect → /auth/login → val.town login |
GET /auth/login | reaches the login flow (not blocked by the gate) |
Machine endpoints (/api/*, /raw/*) answer 401; a browser gets bounced through the login flow. Someone who logs in but isn't allowed sees denied.html with a log-out button.
The allow-list is ALLOWED_HANDLES at the top of view.ts — lowercase Val Town handles. Add a handle there to give someone read access; they'll need a Val Town account. Members of the val's own org (isOrgMember) are always allowed, so moving this val into a team org doesn't lock that team out.
Why not platform-level restricted app access? It would be tidier — the gate would run before any code — but Val Town requires a multi-member org on a business plan, and this account is personal pro. The std/oauth gate is the equivalent that works here. If the val ever moves to a business-plan org, switch to set_http_privacy: restricted and remove oauthMiddleware — running both means visitors authenticate twice.
Rendering mermaid diagram...
| File | Type | Role |
|---|---|---|
| main.ts | Entrypoint. Convert, store, hand off to route.ts. | |
| convert.ts | script | The conversion pipeline. Pure — no I/O, no network. |
| db.ts | script | SQLite schema and queries. |
| route.ts | script | Delivery seam. Currently a no-op. |
| view.ts | http | Browse UI + JSON API + .md downloads. Behind the login gate. |
| index.html | file | UI shell. |
| client.ts | script | Browser code for the shell. |
| denied.html | file | 403 page for a logged-in account that isn't allowed. |
| test-convert.ts | script | Conversion tests (offline, 4 cases). |
| test-store.ts | script | End-to-end test: handler → SQLite → blob. |
- HTML → markdown via
node-html-markdown.<script>,<style>and<head>are discarded outright, HTML comments stripped (they often carry tracking pixels), and bullets/emphasis are normalised to-and*...*. - Quoted reply chains stripped — Gmail/Apple
On … wrote:, Outlook-----Original Message-----and itsFrom:/Sent:header block,_____dividers,Begin forwarded message:. The earliest marker wins and everything below it goes. A horizontal rule left orphaned by the cut is removed too. - Signature stripped — the RFC 3676
--delimiter,Sent from my iPhone,Get Outlook for iOS. - YAML frontmatter prepended —
from,to,subject,date(ISO 8601),message_id,list_id,source.
Every cut is guarded: if stripping would leave the message empty or nearly so, the cut is skipped instead. A message that is only a signature survives intact.
A plain Thanks,\nChad with no delimiter is not detectable and is intentionally left in place.
---
from: "Alice Example <alice@example.com>"
to: ["chadparker@valtown.email"]
subject: "Quarterly numbers"
date: "2024-01-01T18:00:00.000Z"
message_id: "<abc123@example.com>"
list_id: "Example News <news.example.com>"
source: "html"
---
Hey Chad, the numbers look **good**. Two notes:
- Revenue up 12%
- Churn flat
[Full report](https://example.com/report)
Everything below the original reply header, and the signature, are gone.
| Route | Returns |
|---|---|
GET / | The browse UI (list, search, markdown pane, copy button, log-out). |
GET /api/me | The signed-in account — drives the "signed in as" badge. |
GET /api/emails?q=&limit=&offset= | Summary rows as JSON. q searches sender, subject and body. |
GET /api/emails/:id | One full row, including the markdown. |
GET /raw/:id | The markdown as a downloadable .md file. |
All of these require a session — see Access.
Email content is rendered with textContent, never innerHTML, so a hostile message can't inject markup into the viewer.
One SQLite row per message, keyed by an autoincrement id:
| Column | Notes |
|---|---|
message_id | The RFC 5322 Message-ID — use findByMessageId for dedupe or replay. |
from_addr, to_addrs | to_addrs is a JSON-encoded array. |
subject, received_at | received_at is ISO 8601, so string sorting is chronological. |
source | html or text — which body the markdown came from. |
markdown | The full document, frontmatter included. |
has_raw_html, size_bytes | Flags and the markdown's byte length. |
The original HTML is not in SQLite. It's stored as a blob at raw-html/<id>.html, so a message can be re-converted later (LLM cleanup, better parsing) without being re-sent. Markdown bodies are text and stay queryable; the bulky HTML stays out of table scans.
Everything lands in route.ts → afterStore(), called after the row is already committed. That ordering matters: a third-party outage can never lose a message, and anything added there can be back-filled by replaying the archive instead of re-sending mail.
For a GitHub gist, you'll need a token. Create a classic PAT with the gist scope:
👉 Add GITHUB_TOKEN here: https://www.val.town/x/chadparker/email-to-markdown/environment-variables?key=GITHUB_TOKEN
Wrap the call in try/catch so a GitHub failure doesn't turn a successful archive into a logged error. For content-based routing, from, listId and subject are all already passed to afterStore — list_id (from the List-Id header) is the most reliable signal for newsletters.
Both test scripts are safe to run any time:
test-convert.ts— 4 offline conversion cases (Gmail HTML reply, Outlook header block, bare>quotes, signature-only message). No storage touched.test-store.ts— runs the realmain.tshandler against a synthetic message, then reads the row and blob back. Writes a genuine row (subject prefixed[test]) and a blob.
They exist because import.meta.main doesn't fire under Val Town's evaluator, so a harness inside the module it tests would never run.
Max 30MB per message including attachments. Attachments are ignored entirely — only the body is archived.