How to Connect Gmail to Codex With Aident Loadout

The safest way to connect Gmail to Codex is to authorize Gmail through Aident Vault, discover the current Gmail Actions, inspect the exact schema and permission boundary, and prove access with one bounded IDs-only search. Do not retrieve message content, create a draft, send mail, change labels, archive, or delete anything until the intended mailbox, query, and approval boundary are explicit.

This guide is for developers and operators who want Codex to work with Gmail without placing a password, OAuth token, client secret, or downloaded credential file in a prompt or repository. A successful first check confirms one connected account and one opaque message result. It does not expose a subject, sender, recipient, body, attachment, or thread content.

The safe connection boundary

Google authorization proves which account is connected and which scopes were approved. It does not make every message, Gmail Action, or mutation appropriate for the current task.

Prerequisites

You need:

• the installed public aident CLI;

• access to the intended Gmail account;

• authority to review and approve the Google consent flow;

• a narrow Gmail search query for the first check; and

• a trusted local session where returned identifiers can be reviewed without copying them into source control.

Install or update Aident with the canonical setup prompt:

Follow https://aident.ai/SETUP.md

Then confirm the current Aident account and Vault inventory:

aident account auth status
aident vault vault --action status

Stop if the Aident account is not the intended one. Do not substitute a Gmail password, app password, OAuth token, client secret, or downloaded credentials file. The credential-safety guide for AI agents explains why provider secrets should stay outside the agent conversation.

1. Discover the current Gmail Actions

Search by the job and target staging when the command supports it:

aident capabilities search \
  --targetEnv staging \
  --types '["action"]' \
  --query "Gmail search one message ID without reading content or writing" \
  --limit 10

On August 29, 2026, the staging catalog returned a Gmail email-fetch Action with filters, pagination, result limits, IDs-only mode, payload controls, and spam or trash controls. Copy the exact canonical name from your own result because catalog versions and accepted inputs can change.

The catalog also exposes Actions for message content, threads, drafts, labels, forwarding, settings, sending, trash, and other mutations. That breadth is useful later. It is not a reason to load every schema into Codex context or test a write during connection setup.

2. Inspect the exact contract

Load the selected Action metadata:

aident capabilities get \
  --name "<current Gmail email-fetch Action>"

Review:

• the required Gmail integration and connected account;

• every input, default, and pagination rule;

• which identifiers, headers, snippets, or payload fields can appear;

• operation type and risk level;

• pricing and credit behavior; and

• whether spam, trash, full payloads, or verbose detail are included.

The inspected August 29 schema defaulted to one result, but it also defaulted IDs-only mode off, payload inclusion on, and verbose retrieval on. A default one-result limit therefore did not make the request metadata-only. The schema allowed up to 500 results and supported Gmail search syntax through a query input. For a connection proof, explicitly set IDs-only mode on, payload inclusion off, verbose mode off, and spam or trash inclusion off.

The catalog conservatively marked this retrieval Action as operation type write and risk level 2. Treat that metadata as a review gate. Do not silently relabel it because the underlying Gmail method sounds read-only.

3. Connect Gmail through Vault

If Vault reports no connected Gmail account, start the connection with the exact integration ID returned by discovery:

aident vault vault \
  --action connect \
  --integrationId "<current Gmail integration ID>"

Open the Aident-hosted URL, choose the intended Google account, and review the consent screen. Google's Gmail scope reference distinguishes read-only, compose, send, modify, settings, and full-mail access. Google recommends choosing the most narrowly focused scope that supports the job. The actual consent screen and current integration contract are authoritative for your connection.

After consent, verify the exact integration:

aident vault vault \
  --action status \
  --integrationId "<current Gmail integration ID>"

Expected result: one ready connected user account. Stop if the alias or provider identity is wrong. Do not replace or disconnect another account until its owner reviews the change.

4. Preflight one bounded IDs-only search

Choose a query that proves access without exposing content. A recent date window is safer than a full-mailbox search:

aident capabilities preflight \
  --name "<current Gmail email-fetch Action>" \
  --input '{
    "user_id": "me",
    "query": "newer_than:30d",
    "max_results": 1,
    "ids_only": true,
    "include_payload": false,
    "verbose": false,
    "include_spam_trash": false
  }'

On August 29, the reviewed input validated and the estimate was free. Check your own result. If preflight rejects the input, reports an estimate outside your ceiling, or requires a risk acknowledgement, resolve that exact gate instead of calling Gmail directly.

Preflight validates the selected input against the current Aident contract. It does not prove the connected Gmail account is correct or authorize any later content read or mailbox change.

5. Verify the connection without reading email content

Execute only the inspected IDs-only search:

aident capabilities execute \
  --name "<current Gmail email-fetch Action>" \
  --input '{
    "user_id": "me",
    "query": "newer_than:30d",
    "max_results": 1,
    "ids_only": true,
    "include_payload": false,
    "verbose": false,
    "include_spam_trash": false
  }'

Expected result: one opaque message identifier, with no subject, sender, recipient, snippet, body, attachment, or decoded payload. Do not paste the identifier or raw provider response into an issue, pull request, reusable prompt, or analytics event.

The August 29 first-party check used the connected Gmail account, preflighted a free one-result request, and returned one IDs-only result successfully. The opaque provider identifiers were reviewed locally and not added to the article or repository. No message content was read, and no draft, send, label, archive, trash, delete, forwarding, or settings Action ran.

Verify all of the following before continuing:

1. The intended Gmail account is connected.

2. The request returned at most one result.

3. The result contains no message content or personal header data.

4. Spam and trash were excluded.

5. No Gmail state changed.

6. The selected Action, bounded input, and content-free result summary are documented without identifiers.

6. Start a fresh boundary before reading content

The next task should name the exact mailbox job. For example, a support operator might need unread messages from one sender during one date window. Before reading any headers or body content:

1. Write the Gmail query and explain why each filter is needed.

2. Set the smallest useful result limit.

3. Decide whether IDs, metadata, headers, snippets, or full bodies are necessary.

4. Inspect the current Action schema again.

5. Preflight the identical input.

6. Execute one page and review the returned fields before paginating.

7. Stop when the stated job is complete.

Google's users.messages.list reference supports Gmail search-box syntax in the q parameter, returns message identifiers, and paginates with a page token. Google also documents a 500-message maximum per page. A larger allowed limit is not a recommendation to retrieve a large mailbox.

If your next job is approval-gated follow-up, continue with the Notion CRM email workflow. That article owns the business workflow. This page owns connection, consent review, schema inspection, and the first content-free proof.

7. Put drafts and mailbox changes behind separate approval

Reading one message does not authorize a draft, and creating a draft does not authorize sending it. For any write:

1. Discover and inspect the exact mutation Action.

2. Identify the mailbox, message or thread, recipients, and current state.

3. Show the complete proposed draft or before-and-after mailbox change.

4. Review recipients, claims, attachments, labels, notifications, and rollback.

5. Preflight the identical mutation input.

6. Execute only after approval for that exact target and change.

7. Read back the resulting draft or mailbox state without sending another message.

Use Aident's approval-workflow guide to keep Action-risk acknowledgement separate from credit approval. Sending, forwarding, deleting, changing settings, and modifying mailbox state deserve their own explicit boundaries.

Reusable Codex prompt

Follow https://aident.ai/SETUP.md

Connect Gmail through the installed public aident CLI. Start with account auth
status and Vault status. Search the staging catalog for the current Gmail Action
that can return message IDs without reading content or writing. Inspect the exact
schema, connected account, output fields, defaults, operation type, risk, and
pricing. If Gmail is disconnected, return the Aident Vault connection URL and
stop for me to complete consent. After I confirm, preflight one search for
newer_than:30d with user_id me, max_results 1, ids_only true, include_payload
false, verbose false, and include_spam_trash false. Show the estimate before
execution. Execute only that IDs-only search. Return a content-free success
summary, not the provider identifiers. Do not read subjects, senders, recipients,
snippets, bodies, attachments, or threads. Do not create drafts, send, forward,
label, archive, trash, delete, or change settings. Stop after the one-result
connection proof

Connect Gmail to Codex and verify one content-free result

Sources

• Google Gmail API scopes, reviewed August 29, 2026.

• Google OAuth consent and scope guidance, reviewed August 29, 2026.

• Google users.messages.list reference, reviewed August 29, 2026.

• Google Gmail MCP search-threads reference, reviewed August 29, 2026.

• Aident Loadout setup, reviewed August 29, 2026.

• Aident Loadout overview, reviewed August 29, 2026.

Refresh this guide when Google changes Gmail scopes, search semantics, pagination, or MCP behavior, or when Aident changes the Gmail connection flow, fetch schema, risk metadata, pricing, or Vault behavior.