Read Gmail with MailAtlas

Use Gmail receive when your agent needs to read Gmail messages through OAuth and store them in the MailAtlas email workspace as clean, source-linked documents.

This page shows how to:

• Authorize read-only Gmail access.
• Fetch a bounded set of messages from a Gmail label.
• Store Gmail messages as MailAtlas documents.
• Inspect the fetched messages with list and get.

Before you start

You need:

• MailAtlas installed.
• A Gmail account you can authorize.
• A terminal where you can run mailatlas.

Install keychain support if you have not already:

python -m pip install "mailatlas[keychain]"

Set up Google OAuth

MailAtlas uses Google’s OAuth flow to ask for read-only Gmail access. If you have not set up a Google app before, follow Google’s Gmail API quickstart through the steps that create a Google Cloud project, enable the Gmail API, configure the OAuth consent screen, and create OAuth credentials:

• Gmail API Python quickstart
• Create Google Workspace access credentials
• Gmail API scopes

When Google asks for the application type, choose Desktop app.

Set Gmail credentials

After Google creates the credential, export the client ID and client secret:

export MAILATLAS_GMAIL_CLIENT_ID="..."
export MAILATLAS_GMAIL_CLIENT_SECRET="..."

Set the email workspace

Use a separate workspace while testing with a real mailbox:

export MAILATLAS_HOME="$PWD/.mailatlas-gmail-test"

Authorize read-only Gmail access

mailatlas auth gmail \
  --client-id "$MAILATLAS_GMAIL_CLIENT_ID" \
  --client-secret "$MAILATLAS_GMAIL_CLIENT_SECRET" \
  --email user@gmail.com \
  --capability receive

Check that Gmail receive is configured:

mailatlas auth status gmail

mailatlas auth status gmail shows configured accounts and capabilities without displaying token material. The output should include receive in capabilities.

Fetch Gmail messages

mailatlas receive \
  --provider gmail \
  --label INBOX \
  --limit 10

--label INBOX reads from Gmail’s Inbox label. Change it to another Gmail label when needed.

The command prints JSON with counts, document IDs, cursor data, and a run ID. Common statuses:

Status	Meaning
ok	Receive completed. New documents may or may not have been ingested.
duplicate	All fetched messages already existed in the workspace.
not_configured	Gmail auth or required config is missing.

Inspect stored email

mailatlas list
mailatlas get <document-id>

Gmail messages become MailAtlas documents. Your agent can read them the same way it reads imported .eml files.

Inspect receive status

mailatlas receive status

Status output includes:

• configured receive accounts
• Gmail cursor state
• recent receive runs
• the most recent error when one exists

Troubleshooting

cursor_reset_required

If Gmail reports that the stored history cursor is invalid, run an explicit full sync:

mailatlas receive \
  --provider gmail \
  --label INBOX \
  --limit 50 \
  --full-sync

Full sync may return duplicates if messages are already stored. That is expected.

partial or error

Use mailatlas receive status to inspect recent receive runs and the most recent error.

Cleanup

Remove local Gmail auth:

mailatlas auth logout gmail

Remove the test workspace when you no longer need it. The workspace may contain real mailbox data.

rm -rf "$MAILATLAS_HOME"

Next step

• Use Gmail Receive Watch to poll Gmail in the foreground.
• Use Gmail Provider to understand OAuth token storage and capabilities.
• Use MCP Server to expose email tools to an AI agent.
• Use Export Formats to export fetched messages.
• Use Security and Privacy before using a real mailbox workspace.