v1.1

RAD Markdown Specification

The RAD (Readable Agent Document) format defines how newsletter content is structured for AI agent consumption. Every issue processed by Read By Agents, including full archive conversions, conforms to this specification.

Document Structure

A RAD document is a UTF-8 encoded Markdown file with YAML frontmatter. The structure is:

---
title: "Newsletter Subject Line"
date: "2026-04-01"
newsletter: slug-name
esp: beehiiv
word_count: 1247
has_sponsored_content: true
rad_version: "1.1"
---

# Main heading (usually newsletter title)

Body content in standard Markdown...

## Sponsored

Sponsored content isolated under its own heading.

Frontmatter Fields

Field	Type	Description
`title`	string	The newsletter issue's subject line. Always quoted to handle special characters.
`date`	string	Publication date in `YYYY-MM-DD` format. Extracted from the email's `Date:` header, not the processing time.
`newsletter`	string	URL-safe slug identifying the newsletter (e.g. `morning-digest`, `morning-brew`).
`esp`	string	The email service platform that sent the newsletter. One of the supported platforms listed below, or `unknown`.
`word_count`	integer	Word count of the body content (excluding frontmatter).
`has_sponsored_content`	boolean	Whether the issue contains detected sponsored or advertising content.
`rad_version`	string	Specification version this document conforms to.

URL Scheme

Every issue receives a permanent, predictable URL:

https://files.readbyagents.com/{newsletter}/{date}.md

For example: https://files.readbyagents.com/btcbreakdown/2026-04-01.md

If multiple issues arrive on the same date, a suffix is appended: {date}-2.md, {date}-3.md.

These URLs are permanent and will not change. For newsletters that publish once per day (the common case), agents can construct URLs directly from the slug and date. For newsletters with multiple daily issues, query /api/feed/{slug} to discover all issue URLs.

Content Guarantees

No tracking links. All ESP tracking redirects are resolved to their final destination URLs.
No merge tags. ESP-specific template variables ({{NAME}}, *|EMAIL|*) are stripped.
No PII. Subscriber email addresses, user IDs, and tracking identifiers are removed from links and content.
No navigation chrome. ESP UI elements (Upgrade, Subscribe, Unsubscribe buttons) are removed.
No tracking pixels. Open-tracking images are stripped.
Sponsored content isolation. When detected, advertising content is placed under a dedicated ## Sponsored heading.
Clean heading hierarchy. Content uses standard Markdown headings (##, ###) derived from the newsletter's own structure.
UTF-8 throughout. Quoted-printable and base64 content is decoded to proper UTF-8.

Supported Email Platforms

RAD includes platform-specific handlers that understand each ESP's HTML patterns, tracking link formats, and chrome elements:

Beehiiv

Substack

Ghost

ConvertKit / Kit

Mailchimp

Klaviyo

ActiveCampaign

Buttondown

Brevo

MailerLite

WordPress / Jetpack

Newsletters from unrecognized platforms are processed with a generic handler that applies standard cleanup rules.

API Access

RAD documents are accessible through multiple interfaces:

Method	Endpoint	Description
REST	`GET /api/directory`	List all newsletters with metadata
REST	`GET /api/feed/{slug}`	List all issues for a newsletter
REST	`GET /api/issue/{slug}/{date}`	Retrieve a specific issue's markdown
Direct	`GET files.readbyagents.com/{slug}/{date}.md`	Raw markdown file
Discovery	`GET /llm.txt`	Machine-readable site description for LLMs

The directory and feed endpoints return JSON. The issue endpoint returns text/markdown directly. Direct file access and discovery return plain text. No authentication required. CORS enabled for all REST endpoints.

Versioning

The rad_version field in frontmatter indicates which version of this specification the document conforms to. Version changes are backwards-compatible: new fields may be added, but existing fields will not be removed or have their meaning changed.

Version	Changes
`1.0`	Initial format. Basic frontmatter, markdown body.
`1.1`	Added `has_sponsored_content`, sponsored content isolation, async URL resolution, platform-specific handlers.

Claim your newsletter and get your entire archive converted to this format. Free forever. For integration guides, see the homepage. For engineering decisions, read our research blog.