MailAtlas Docs

MailAtlas makes email accessible to AI agents. It imports email from live mailboxes or archives, turns complex messages into clean source-linked views, and gives agents a queryable email workspace for reading, exporting, and sending.

MailAtlas is currently alpha. Expect CLI, schema, and packaging details to keep improving as the project matures.

Choose how your agent gets email

Start with the source you already have. Live mailboxes, individual email files, and mailbox archives all write to the same email workspace.

Mailbox Live mailbox

Connect selected folders over IMAP so your agent can work from current mailbox data in the same email workspace.

IMAP Gmail Gmail mailbox

Fetch Gmail messages with read-only OAuth and store them as clean, source-linked documents for your agent.

Gmail API Files Email files

Import individual .eml files when you want the fastest local check or already have messages exported to disk.

Quickstart Archive mbox archive

Import an exported mailbox archive and create one clean, source-linked document per message.

Mbox

Install

Install MailAtlas from PyPI, then choose the source you want to connect or import.

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install mailatlas

For a quick local check, import one sample email file:

git clone https://github.com/mailatlas/sample-data.git
export MAILATLAS_HOME="$PWD/.mailatlas"
mailatlas ingest sample-data/fixtures/eml/atlas-market-map.eml
mailatlas list

What MailAtlas handles for you

MailAtlas handles MIME structure, HTML, attachments, embedded images, metadata, and provenance so your agent can work with clean email views without losing the original source context.

Use MailAtlas from your agent stack

CLI CLI

Use the CLI for local runs, scripts, inspection, exports, provider-backed sends, self-checks, and MCP server startup.

CLI Overview Python Python API

Use the Python API when you want to embed MailAtlas in an application, worker, notebook, test suite, or pipeline.

Python API MCP MCP server

Use MCP tools when agent clients should read email, inspect exports, prepare drafts, and optionally send through an explicit approval gate.

MCP Server

What your agent can do

• receiveFetch Gmail or IMAP messages from a live mailbox and store clean source-linked documents locally.
• ingestImport .eml files or an mbox archive from disk.
• readUse mailatlas list and mailatlas get to find, inspect, and query stored email.
• exportWrite JSON, Markdown, HTML, or PDF views from stored messages while keeping assets and source links connected.
• sendSend through SMTP, Cloudflare, or Gmail and store sent messages in the same email workspace.

Core Concepts

MailAtlas stores email in a workspace your agent can query. Each message keeps its clean text, HTML view, attachments, embedded images, metadata, exports, and source reference together, so the agent can read the clean version and still trace back to the original email when needed.

Overview Core Concepts

Learn how email workspaces, documents, assets, parser metadata, exports, and sent messages fit together.

model Workspace Workspace Model

Understand the email workspace: stored messages, HTML snapshots, assets, exports, receive state, sent messages, and SQLite lookup.

workspace Document Document Schema

Review the normalized document fields, asset fields, parser metadata, source provenance, and path behavior used by the CLI and Python API.

document Cleaning Parser Cleaning

Tune how MailAtlas turns complex email source into clean text and HTML views for agents, exports, review, and tests.

cleaning Export Export Formats

Choose between JSON, Markdown, HTML, and PDF outputs, and understand how exported files relate to stored documents and assets.

export Outbound Outbound Email

Render and send messages through configured providers, then store sent email in the same workspace.

send

Common terms

.eml

A single email message file on disk.

mbox

A mailbox file on disk that can contain many messages.

Email workspace

The local copy of received and sent email that your agent can query, inspect, and export.

Document

The clean, structured MailAtlas record created from one email message.

Source email

The original message MailAtlas keeps linked to cleaned text, HTML, assets, metadata, and exports.

Asset

An inline image or regular file attachment extracted from a message and linked to a document.

Provider

The mailbox or sending service MailAtlas connects to, such as IMAP, Gmail, SMTP, or Cloudflare.

Export

A derived JSON, Markdown, HTML, or PDF artifact written from a stored document.

Sent message

A message MailAtlas rendered and sent through a configured provider, stored in the same email workspace as received email.

Next step

New users should start with Installation. Then use Manual IMAP Sync for a live mailbox or Quickstart for sample email files. After that, use Outbound Email, Python API, or MCP Server depending on how your agent will use MailAtlas.