Security and Privacy

MailAtlas stores data on the local filesystem and in SQLite by default. The core CLI commands and Python APIs operate on files you point at, Gmail messages you receive explicitly, IMAP folders you receive explicitly, and outbound messages you ask MailAtlas to draft or send.

File ingest, mailbox receive, export, and sending run against the workspace and providers you configure.

Local storage still contains sensitive data. Treat a MailAtlas workspace as source email data, not as a scrubbed sharing format.

What MailAtlas stores

MailAtlas can store:

• Raw inbound message bytes on disk.
• Normalized HTML and extracted assets on disk.
• Cleaned body text in stored document records.
• Document metadata and parser notes in SQLite.
• Receive account state, cursor state, and run history in SQLite when you use receive.
• IMAP receive cursor state in SQLite when you receive IMAP folders.
• Outbound raw .eml snapshots.
• Outbound body files.
• Copied outbound attachments.
• Provider status and provider response metadata.
• Recipient metadata, including BCC recipients in SQLite.
• Exported artifacts wherever you tell MailAtlas to write them.

What MailAtlas does not do by default

MailAtlas does not provide:

• Hosted storage.
• Hosted mailbox receive.
• Background mailbox receive as a managed service.
• Hidden mailbox receive.
• Automatic publication of private inbox data.
• Autonomous background sending.
• Deliverability management.
• Encryption at rest for the workspace.

Provider credentials

Configure provider credentials through environment variables, CLI flags, Python config, or the Gmail auth helper. The following secrets are used for provider access and are kept out of store.db, raw snapshots, logs, and JSON receive/send results:

Secret type	Examples
IMAP password	MAILATLAS_IMAP_PASSWORD
IMAP OAuth access token	MAILATLAS_IMAP_ACCESS_TOKEN
SMTP password	MAILATLAS_SMTP_PASSWORD
Cloudflare API token	MAILATLAS_CLOUDFLARE_API_TOKEN
Gmail access token	MAILATLAS_GMAIL_ACCESS_TOKEN
Gmail refresh token	Token material from local Gmail OAuth helper

For local Gmail CLI workflows, mailatlas auth gmail stores token material outside the workspace. With mailatlas[keychain] installed, it uses the operating system keychain by default. Without that extra, it uses a user config token file outside the workspace.

Backend applications should store OAuth refresh tokens in their own encrypted credential store and pass short-lived access tokens to MailAtlas at receive or send time.

Workspace sensitivity

A workspace can contain private email content, attachments, inline images, sender and recipient metadata, drafts, sent-message records, BCC recipients, and exported PDFs or Markdown bundles.

Do not commit .mailatlas/ to source control unless you intentionally created a synthetic fixture workspace.

Recommended .gitignore entry:

.mailatlas/

IMAP Receive Privacy

IMAP receive stores cursor state, not mailbox credentials.

If you use OAuth for IMAP:

1. Obtain tokens in your own auth layer or secret source.
2. Pass the access token to MailAtlas at runtime.
3. Keep refresh tokens outside MailAtlas.
4. Rotate or revoke tokens using your provider’s controls.

Gmail receive privacy

Gmail receive stores the messages it fetches in the local workspace. That can include raw message bytes, cleaned body text, HTML snapshots, inline images, attachments, sender and recipient metadata, and exported artifacts.

Gmail receive is read-only. MailAtlas does not delete, archive, label, or mark Gmail messages read.

Use mailatlas auth gmail --capability receive for receive-only local access. Use --capability send,receive only when the same local token should support both actions.

If Gmail reports that the stored history cursor is invalid, run an explicit mailatlas receive --full-sync so the reset is visible in command history and logs.

Outbound email privacy

Sent-message records can contain sensitive email data.

They can include draft or sent body content, copied attachments, recipient lists, BCC recipients in SQLite, provider message IDs, provider error details, and idempotency keys.

MailAtlas omits BCC from local raw MIME snapshots. BCC recipients are still stored in SQLite and included in provider delivery.

Review outbound drafts and dry runs before sending generated or agent-authored email.

Untrusted email HTML and exports

Treat raw stored HTML snapshots as untrusted source data. MailAtlas preserves them in the email workspace so the original message structure remains available; preservation is not sanitization, and you should not serve or open those snapshots as trusted application HTML.

Default HTML export does not copy the stored snapshot verbatim. MailAtlas rebuilds it as inert, presentation-oriented HTML and removes executable elements and unsupported markup, event handlers, forms, unsafe link schemes, automatically loaded remote subresources, unsafe CSS, and unrecognized local files. It omits source-provided data: images, SVG, and unsupported or spoofed assets, then embeds known allowlisted local raster inline images recorded for the document as data URLs. Ordinary http, https, and mailto links may remain, so following a link can still contact an external site.

PDF export re-sanitizes the HTML and embeds only known allowlisted local raster inline images before launching local Chrome or Chromium. The renderer uses a restrictive content security policy, disables JavaScript, keeps Chrome’s normal sandbox enabled, runs with an isolated temporary profile, and denies outbound hosts and proxy connections. A failed render leaves any existing destination PDF unchanged.

These controls narrow the rendering boundary; they do not make Chrome invulnerable or make email content safe to trust. HTML and PDF exports can still contain private text, deceptive content, and clickable links. Keep the browser current and review every export before sharing it. Set MAILATLAS_PDF_BROWSER only when you need to override the browser executable path.

MCP security note

The MCP server exposes local workspace tools to MCP-compatible clients over STDIO.

Live sending is disabled by default. The live send tool is only exposed when the server starts with --allow-send or MAILATLAS_MCP_ALLOW_SEND=1.

Mailbox receive tools are also disabled by default. They are only exposed when the server starts with --allow-receive or MAILATLAS_MCP_ALLOW_RECEIVE=1. Receive-on-read is off unless MAILATLAS_MCP_RECEIVE_ON_READ=1 is set.

Use the draft tool for reviewable generated messages, and enable live sends only in environments where the client is allowed to send email.

Practical guidance

• Treat the workspace as sensitive source data.
• Keep real workspaces out of repositories.
• Use synthetic fixtures for demos, screenshots, and tests.
• Treat stored raw HTML as untrusted even though default HTML and PDF exports are sanitized.
• Review exported JSON, HTML, Markdown, and PDF artifacts before sending them outside your machine or repository.
• Review sent-message records before sharing logs or workspace snapshots.
• Pass credentials through runtime configuration such as environment variables, CLI flags, secret managers, or explicit Python config.
• Use Gmail receive only with a read-only scope unless the same token must also send mail.
• Prefer Gmail API OAuth with the gmail.send scope over SMTP app passwords for personal Gmail sending.
• Revoke old app passwords or test credentials when they are no longer needed.

Operational checklist

Before sharing a workspace or export, check:

• Does it contain raw email?
• Does it contain attachments?
• Does it contain outbound drafts or sent records?
• Does it contain BCC metadata?
• Does it contain exported PDFs or Markdown bundles?
• Does it contain provider error details or message IDs?
• Does it contain receive cursor or run history?
• Is it synthetic data or real user data?