How to Give OpenAI Codex Access to Your Email

To let Codex work with your email, give it a readable copy of your messages. For a local archive you can reuse, use mailmd. It copies email into Markdown files, which are plain-text documents, on your computer. Start Codex in the folder with those files, and it can read them.

Codex can read this copy without getting your mailbox password. You enter your account details into mailmd yourself. When Codex reads a message, it sends the content it uses to the service that runs its AI model. Keep this in mind when deciding which messages to copy.

Why use mailmd with Codex #

A Markdown file is a plain-text document that people and coding tools can read. mailmd creates one file per message and keeps headers such as sender and date. It turns HTML email into readable text and saves attachments beside each message. It works with IMAP mailboxes, which use a standard protocol for accessing email. It connects to Gmail through the Gmail API and to Outlook.com or Microsoft 365 through Microsoft Graph, Microsoft's service for accessing account data.

mailmd is free, open source, and read-only: it does not mark messages as read, send mail, or change or delete messages in your mailbox. The archive stays on your computer, and Codex can search it with its normal tools. Because mailmd does not provide an email search engine, Codex searches the files directly.

OpenAI also documents email plugins for supported Codex interfaces. Installing a plugin does not authorize a mailbox by itself; you must connect the account separately. Gmail authorization includes permission to read, compose, and send email, according to OpenAI’s Gmail data controls. mailmd is a good fit when you want Codex to work from a local copy rather than connect directly to the mailbox.

Set up mailmd and copy your email #

You can ask Codex to set up mailmd by starting a coding-agent session and giving it this prompt:

Set up mailmd so you can read my email. Use https://github.com/vincentsch/mailmd: read its AGENTS.md and follow the steps. Connect my mailbox and run the first sync. Then show me where the files are.

You enter your password or complete the provider’s login yourself, so the agent does not see your password. Review the requested access before approving it.

To set it up by hand, install mailmd and connect your account:

curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh

Choose the connection command that matches your mailbox:

mailmd connect imap --email you@example.com
mailmd connect gmail --client-secret client_secret.json
mailmd connect outlook --client-id <id>

Use the IMAP option for IMAP mailboxes, including Gmail with an app password. Use the Gmail API option for Gmail, or the Outlook option for Outlook.com and Microsoft 365. For Gmail or Microsoft API connections, create an OAuth app in Google Cloud or Microsoft Entra. This app lets you authorize mailmd to access your account. Some IMAP providers require an app password; mailmd indicates when one is needed.

Then copy your messages:

mailmd sync

The archive is saved under ~/mail/<account>. mailmd includes archived Gmail messages through All Mail when connecting over IMAP, while spam and trash are excluded unless requested. You can use --folder, --exclude, or --since to choose what to copy. Later syncs add new mail and update read and starred marks. Deleted server messages remain in the archive with a deleted-on-server mark.

Ask Codex to work with the archive #

Start Codex in the folder where mailmd saved the archive, then give it a specific task, such as:

Search my email archive for messages from the last month about the renewal. Summarize the relevant messages with their dates and senders. Do not draft or send a reply.

A narrow request makes it easier to check the results against the original messages. Codex reads the local files with its usual tools, but the content it uses goes to the model provider. Avoid copying sensitive mail if that does not fit your privacy requirements.

mailmd saves login details outside the archive. Those details are not encrypted and are readable only by your user account. The tool has no mailmd server or telemetry. Keep the archive in a folder protected by your usual computer backup and account security. You can also schedule mailmd sync --quiet to keep the copy current.

Know what the archive does and does not do #

mailmd copies mail for reading and searching. It is not a mail client, does not send messages, and does not delete mail from your mailbox. It also does not free mailbox storage automatically; delete messages from the email service yourself only after confirming you have the copy you need.

To remove access, disconnect the account through mailmd’s account setup and stop any scheduled sync. The local archive remains on your computer unless you delete it. For more about setup and supported accounts, see the mailmd project.