Public
Convert incoming email to clean markdown and archive it
emailmarkdownsqlite
Val Town is a collaborative website to build and scale JavaScript apps.
Deploy APIs, crons, & store data – all from the browser, and deployed in milliseconds.

Email → Markdown

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.

Access — private, behind a Val Town login

Everything except /auth/* sits behind "Log in with Val Town" (std/oauth). Verified against the live endpoint:

RequestResult
GET /api/emails (no session)401 {"error":"unauthorized"}
GET / (no session)redirect → /auth/login → val.town login
GET /auth/loginreaches 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.

How it works

Rendering mermaid diagram...
FileTypeRole
main.tsemailEntrypoint. Convert, store, hand off to route.ts.
convert.tsscriptThe conversion pipeline. Pure — no I/O, no network.
db.tsscriptSQLite schema and queries.
route.tsscriptDelivery seam. Currently a no-op.
view.tshttpBrowse UI + JSON API + .md downloads. Behind the login gate.
index.htmlfileUI shell.
client.tsscriptBrowser code for the shell.
denied.htmlfile403 page for a logged-in account that isn't allowed.
test-convert.tsscriptConversion tests (offline, 4 cases).
test-store.tsscriptEnd-to-end test: handler → SQLite → blob.

The conversion pipeline

  1. 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 *...*.
  2. Quoted reply chains stripped — Gmail/Apple On … wrote:, Outlook -----Original Message----- and its From:/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.
  3. Signature stripped — the RFC 3676 -- delimiter, Sent from my iPhone, Get Outlook for iOS.
  4. 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.

Example output

--- 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.

The browse API

RouteReturns
GET /The browse UI (list, search, markdown pane, copy button, log-out).
GET /api/meThe 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/:idOne full row, including the markdown.
GET /raw/:idThe 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.

Storage

One SQLite row per message, keyed by an autoincrement id:

ColumnNotes
message_idThe RFC 5322 Message-ID — use findByMessageId for dedupe or replay.
from_addr, to_addrsto_addrs is a JSON-encoded array.
subject, received_atreceived_at is ISO 8601, so string sorting is chronological.
sourcehtml or text — which body the markdown came from.
markdownThe full document, frontmatter included.
has_raw_html, size_bytesFlags 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.

Adding a destination later

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.

Testing

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 real main.ts handler 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.

Messages

Max 30MB per message including attachments. Attachments are ignored entirely — only the body is archived.