Glossary
A single email message file on disk. Use mailatlas ingest when you already have one or more .eml files locally.
A mailbox file on disk that can contain many messages. Use mailatlas ingest when you already have an mbox archive locally. An mbox file is not the same thing as IMAP receive.
IMAP receive
Section titled “IMAP receive”The MailAtlas workflow for connecting to a live mailbox over IMAP and fetching selected folders into the local workspace. Use mailatlas receive --provider imap.
Gmail receive
Section titled “Gmail receive”The MailAtlas command and API path for fetching Gmail messages with the Gmail API and storing them as local documents. Use mailatlas receive for one bounded pass or mailatlas receive watch for foreground polling.
Receive account
Section titled “Receive account”A local record for a mailbox receive configuration. It stores provider identity and non-secret options such as label, query, or folder selection.
Receive cursor
Section titled “Receive cursor”The Gmail checkpoint MailAtlas stores in SQLite to avoid reprocessing the same messages on incremental receive runs.
Receive run
Section titled “Receive run”One receive attempt. A run stores status, counts, errors, and links to documents created or skipped as duplicates.
Workspace root
Section titled “Workspace root”The local directory that holds raw email, normalized HTML, extracted assets, exports, outbound records, and store.db.
store.db
Section titled “store.db”The SQLite database inside the workspace root. It stores document metadata, lookup data, dedupe information, Gmail receive cursors, IMAP receive cursors, run history, and outbound records.
Document
Section titled “Document”The normalized MailAtlas record created from one email message. A document is stored in SQLite and linked to files in the workspace root.
A file extracted from a message, such as an inline image or a regular attachment.
Inline asset
Section titled “Inline asset”An asset embedded in an HTML email, often referenced by content ID.
Attachment
Section titled “Attachment”A regular file attached to an email and extracted into the workspace.
Export
Section titled “Export”A derived JSON, Markdown, HTML, or PDF artifact produced from a stored document.
Markdown bundle
Section titled “Markdown bundle”A directory export that contains document.md plus an assets/ directory with copied assets referenced by the Markdown file.
PDF export
Section titled “PDF export”A PDF artifact rendered with local Chrome or Chromium from stored HTML when available, or generated HTML based on cleaned text.
Parser cleaning
Section titled “Parser cleaning”Configurable transformations that remove or normalize noisy email body content, such as boilerplate, forwarded headers, footers, link-only lines, invisible characters, and whitespace.
Provenance
Section titled “Provenance”Metadata that explains where a document came from and how it was processed, including source type, IMAP folder and UID when available, forwarded-chain information, and parser notes.
Source kind
Section titled “Source kind”The input type that produced a document, such as eml, mbox, gmail, or imap.
Outbound record
Section titled “Outbound record”A local audit record created when MailAtlas drafts, dry-runs, queues, sends, or fails to send an outbound message.
Dry run
Section titled “Dry run”An outbound workflow that validates, renders, and stores a message without contacting an email provider.
Provider
Section titled “Provider”An outbound delivery backend configured at runtime, such as SMTP, Cloudflare Email Service, or Gmail API.
Provider credentials
Section titled “Provider credentials”Secrets used to authenticate with a provider, such as SMTP passwords, Cloudflare API tokens, or Gmail OAuth tokens. MailAtlas reads these at runtime and does not write them to store.db, raw snapshots, logs, or JSON receive/send results.
Idempotency key
Section titled “Idempotency key”A caller-provided key used to make retrying outbound sends safer. If the same key already exists, MailAtlas returns the existing outbound record instead of sending a second message.
MCP server
Section titled “MCP server”The optional Model Context Protocol server that exposes local MailAtlas tools to MCP-compatible clients over STDIO.
Send gate
Section titled “Send gate”The explicit runtime configuration required before the MCP server exposes live outbound sending. Draft tools remain available without the live send gate.
Receive gate
Section titled “Receive gate”The explicit runtime configuration required before the MCP server exposes mailbox receive tools.