Open-source email ingestion

MailAtlas: email ingestion for AI agents and data apps.

Read .eml files, import mbox mailbox files, or sync selected IMAP folders into one local workspace. MailAtlas keeps raw messages, cleaned text, HTML, inline images, file attachments, and metadata together so the same email can power AI, search, audits, and analytics.

Try file ingest See IMAP sync

Start with files when your email is already on disk. Use sync imap when you need MailAtlas to connect to a live mailbox and fetch folders incrementally.

Open source No hosted service required Stores IMAP cursors, not mailbox credentials Preserves inline images and attachments JSON, Markdown, HTML, PDF exports

.eml One message file on disk

Use this when you already have individual messages saved locally and want the fastest ingest path.

mbox One mailbox file on disk

Use this when another system exported a mailbox file and you want to normalize every message inside it.

sync imap Selected folders from a live mailbox

Use this when the messages still live in an inbox and you want MailAtlas to fetch them incrementally.

Use MailAtlas if

Your goal is reusable application data, not inbox UX.

You need cleaned text plus links back to the raw email, HTML, inline images, and file attachments.
You want one repeatable ingest layer for retrieval, analytics, audit trails, or agent workflows.
You care about deterministic exports such as JSON, Markdown, HTML, and PDF.
You want to start with files and add manual IMAP sync later without changing the stored shape.

Do not confuse it with

MailAtlas is an ingestion layer, not a mailbox product.

It is not background mailbox sync or a managed connector service.
It is not hosted inbox search, inbox chat, or a full mailbox client.
It is not just a MIME decoder. The point is normalized, inspectable outputs you can reuse.
It is not trying to hide the source. Raw provenance stays attached to the stored document.

Start with files

The quickest proof is fixture-based ingest from disk.

Install the CLI, ingest the shipped fixtures, and inspect the stored records before pointing MailAtlas at your own email. This is the fastest way to verify the shape and export flow end to end.

recommended path

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

mailatlas ingest eml \
  path/to/message.eml \
  --db .mailatlas/store.db \
  --workspace .mailatlas/workspace

mailatlas list \
  --db .mailatlas/store.db \
  --workspace .mailatlas/workspace

Use python -m pip install "mailatlas[api]" only if you want the published API extra.
Use uv tool install mailatlas or Homebrew if you prefer a tool-style install.
Clone the repo if you want the shipped fixtures or the example API app.
Use sync imap instead when the messages are still in a live mailbox.
Export JSON, HTML, or Markdown anywhere with --out; PDF export is optional.

What MailAtlas stores per message

One document, plus links back to raw email, attachments, and derived artifacts.

The default workspace is a reference implementation. It keeps raw bytes, normalized HTML, extracted inline images and attachments, and SQLite metadata together so you can inspect them locally or move the data into your own services later.

reference workspace

.mailatlas/
  store.db
  workspace/
    raw/
    html/
    assets/
    exports/

stored document
 subject Port dwell times normalize after weather disruptions 
 author Harbor Labs Charts <charts@harborlabs.example> 
 cleaning dropped_line_count: 0 
 html path html/<document-id>.html 
 asset refs assets/<document-id>/001-route-heatmap.svg and any extracted attachments 
 exports --out ./document.json or workspace/exports/<document-id>.pdf 

MailAtlas: email ingestion for AI agents and data apps.

Your goal is reusable application data, not inbox UX.

MailAtlas is an ingestion layer, not a mailbox product.

The quickest proof is fixture-based ingest from disk.

One document, plus links back to raw email, attachments, and derived artifacts.

Choose files or a live mailbox and inspect the stored shape.