Skip to content
MailAtlas

MailAtlas Docs

MailAtlas is an open-source email infrastructure layer for developers building local email workflows, AI agents, retrieval systems, and data applications. These docs show how to ingest email from files, receive Gmail or IMAP messages, inspect stored documents, export structured outputs, and send provider-backed email while preserving a local audit trail.

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

Start with your input

Section titled “Start with your input”

Choose the path that matches where the email lives now. Each path writes to the same local workspace model.

Files Files

Use the Quickstart when you already have individual .eml files on disk and want to verify ingest, inspect, and export behavior end to end.

 Quickstart Archive Archive

Use mbox ingest when email is already exported as a mailbox archive and you want MailAtlas to create one stored document per message.

 Mbox Mailbox Mailbox

Use IMAP receive when MailAtlas should connect to a live mailbox, fetch selected folders, and keep the same local workspace current.

 IMAP Gmail Gmail receive

Use Gmail Receive when MailAtlas should fetch Gmail messages with a read-only OAuth token and store them in the local workspace.

 Gmail API Outbound Outbound email

Use Outbound Email when your application needs to render, store, send, and audit messages through SMTP, Cloudflare, or Gmail.

 Send
Section titled “Recommended first path”

Run one file-based ingest before connecting a live mailbox or building on the Python API. This confirms the install, creates a workspace, and shows the document model with the least setup.

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


export MAILATLAS_HOME="$PWD/.mailatlas"
mailatlas ingest path/to/message.eml
mailatlas list

If you want sample data:

Terminal window
git clone https://github.com/mailatlas/sample-data.git
mailatlas ingest sample-data/fixtures/eml/atlas-market-map.eml
mailatlas list

Choose your interface

Section titled “Choose your interface”
CLI CLI

Use the CLI for terminal workflows, scripts, inspection, exports, provider-backed sends, self-checks, and local 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 the MCP server when MCP-compatible clients should inspect local email data, prepare outbound drafts, or optionally send through an explicit runtime gate.

 MCP Server

Choose your workflow

Section titled “Choose your workflow”
  • ingestUse mailatlas ingest when you already have .eml files or an mbox mailbox file on disk.
  • receiveUse mailatlas receive when MailAtlas should fetch Gmail or IMAP messages from a live mailbox and store them locally.
  • getUse mailatlas list to find documents, then mailatlas get to inspect or export one document as JSON, Markdown, HTML, or PDF.
  • sendUse mailatlas send when MailAtlas should render a local outbound audit record and send through a configured provider.

Core Concepts

Section titled “Core Concepts”

MailAtlas has a small local data model. Learn these concepts before building on the CLI, Python API, MCP server, or provider integrations.

Inbound email follows this shape:

.eml file, mbox archive, Gmail message, or IMAP message
        |
MailAtlas document
        |
raw message + cleaned text + HTML snapshot + assets + metadata
        |
CLI, Python API, MCP server, exports, retrieval, or review workflows

Outbound email follows the same local-first pattern:

draft or send request
        |
rendered body + raw .eml snapshot + copied attachments
        |
outbound record + provider status
Overview Core Concepts

Learn how workspaces, documents, assets, parser metadata, exports, and outbound records fit together.

 model Workspace Workspace Model

Understand the local workspace root: store.db, raw messages, HTML snapshots, assets, exports, IMAP receive state, and outbound records.

 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 transforms noisy email bodies into cleaned text for retrieval, exports, analytics, 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, dry-run, send, and audit outbound messages through configured providers.

 send

Common terms

Section titled “Common terms”
.eml

A single email message file on disk.

mbox

A mailbox file on disk that can contain many messages.

Workspace root

The local directory that holds raw email, HTML snapshots, extracted assets, exports, outbound records, and SQLite metadata.

Document

The normalized MailAtlas record created from one inbound email message.

Asset

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

Parser metadata

Structured notes that describe how a message was parsed, cleaned, and traced back to its source.

Export

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

Outbound record

A local audit row plus rendered files for a draft, dry run, queued message, sent message, or failed send.

Next step

Section titled “Next step”

New users should start with Installation, then Quickstart. After that, move to IMAP Receive, Outbound Email, or the Python API depending on how you plan to use MailAtlas.