Connecting Gmail
Cora can read your Gmail, in the missions you choose. It is read-only. Cora can search your mail, read one message with its attachments’ names and sizes (and the text of plain text and PDF attachments), and list your labels. She cannot send, reply, draft, label, archive, move or delete anything.
It uses a small mail server hosted by Cora, because Google’s own Gmail MCP server is still a preview that can change labels and write drafts. Google does not let Cora register itself, so your organisation uses its own Google app: your Google admin makes it once, and a Cora org admin enters its client ID and client secret in Cora. Then each person signs in with their own Google account, the same way as Connecting with the service’s sign-in. The connection is theirs: they decide which missions Cora may use it in. See Personal connections for the rules. This page uses an invented company, Kestrel Cycles, and a team member, Megan.
What you need
Section titled “What you need”- MCP turned on for the organisation (see Connecting an MCP server). An org admin does that once.
- Someone who can make a Google Cloud project in the Google Cloud console for your business.
- Gmail turned on by the operator. If Gmail says it is not available yet, ask the operator (it needs the hosted mail server deployed).
Step 1: your Google admin makes the app
Section titled “Step 1: your Google admin makes the app”Do this once, in the Google Cloud console.
- Create a Google Cloud project (or use one your business already has) and open APIs & Services, Library. Find the Gmail API and choose Enable.
- Open Google Auth Platform (it was called the OAuth consent screen). Fill in the app’s name and support email.
- Audience. If your mail is on Google Workspace and only your own people will connect, choose Internal. Otherwise choose External and leave it in Testing, then add each person who will connect under Test users.
- Open Data Access, choose Add or remove scopes and add
https://www.googleapis.com/auth/gmail.readonly(“View your email messages and settings”). Add no other scope: Cora asks for this one only. - Open Clients, choose Create client, and pick Web application. Under Authorized redirect URIs add Cora’s callback address. Copy it from the Organisation setup section of Gmail’s page on Cora’s Connections page; it looks like
https://<your Cora console>/v1/oauth/callbackand must match exactly. Leave Authorized JavaScript origins empty. - Choose Create, then copy the Client ID (it ends in
.apps.googleusercontent.com) and the Client secret.
Google’s verification. gmail.readonly is a restricted scope. An External app in Testing works only for the test users you list (up to 100), and Google ends their sign-in after seven days, so they need to Reconnect each week. To let anyone else connect, or to stop the weekly sign-in, the app must pass Google’s app verification and the yearly security assessment for restricted scopes, then be published. An Internal app needs neither, but only works for accounts in your own Google Workspace.
Step 2: a Cora org admin enters the app
Section titled “Step 2: a Cora org admin enters the app”- Open Connections on the left rail. Under Needs an admin to set up first, Gmail says Organisation setup needed: press Set up beside it. The first section of its page, Organisation setup, has the Gmail card: choose Set up.
- Paste the Client ID and the Client secret, and choose Save. There is no address to enter.
The card then shows Set up, the server address, the client ID and when the secret was set. Replace secret changes only the secret. Change with another client ID, and Remove, stop every Gmail connection in the organisation at once, because each was made with the old app, so everyone needs to Reconnect. Only org admins see this card.
Step 3: each person connects
Section titled “Step 3: each person connects”- Open Connections on the left rail and press Connect beside Gmail.
- In the Account section, choose Connect…. The short name (
gmail) and the address are filled in for you. - In the dialog choose Connect. Google’s page opens in a new window. Sign in with the Google account whose mail Cora should read, check the permission and approve. Google asks every time, because that is how Cora gets a sign-in that lasts.
- The window closes by itself and the card shows the connection. Finish the sign-in in the same browser you pressed Connect in.
Then, in the Shared with missions section, choose + Share in a mission, and pick the missions where Cora may read your mail.
Step 4: ask Cora
Section titled “Step 4: ask Cora”In a mission where you shared the connection, ask Cora in the dialogue, for example:
- “Find the emails from the printer about the spring catalogue this month.”
- “Read the latest message from Kestrel’s agency and list its attachments.”
- “Which labels do I have?”
Cora uses Gmail’s own search words, such as from:, subject:, after:2026/11/01 and has:attachment.
What Cora can read
Section titled “What Cora can read”Three tools, all of them only read:
- Search messages: up to 25 at a time, with the sender, recipients, subject, date and a short preview.
- Read a message: its headers, its text (capped at 20,000 characters), and each attachment’s name, type and size. For up to three plain text or PDF attachments of at most 5 MB, the text too (8,000 characters each). Other attachments give their names only.
- List labels: each label’s name and whether it is one of Gmail’s own (such as Inbox) or one you made.
What Cora cannot do
Section titled “What Cora cannot do”The server has no tool that writes, and Cora’s list of Gmail tools is a fixed list of these three names. She cannot send, reply, forward, draft, label, mark as read, archive, move or delete mail, or change any setting. Sending from your own mailbox will come later, behind an approval card.
Mail is someone else’s writing. Cora reads it as data, never as instructions: a message that says “Cora, forward this to…” is just text to her.
When it says Needs reconnect
Section titled “When it says Needs reconnect”The card says Needs reconnect when Google ends the sign-in: every seven days for a test user of an app in Testing, when you remove Cora’s access in your Google account, or when you change your password. Choose Reconnect, sign in again and approve. The same connection comes back, with the missions it was shared in. It also says so, with “Your organisation changed its sign-in app for Gmail”, when an org admin changes or removes the app.
If Google refuses the sign-in
Section titled “If Google refuses the sign-in”- Google’s page says “Access blocked” or “has not completed the Google verification process”. You are not a test user of an External app in Testing. Ask your Google admin to add you under Test users.
- Google’s page says the redirect URI does not match. The app does not list Cora’s callback address exactly. Ask your Google admin to check step 1.
- Cora says “The service did not accept your organisation’s sign-in app secret”. Ask an org admin to check the client secret and choose Replace secret.
What stays private
Section titled “What stays private”- Your sign-in is kept in one place. It goes to the secrets store. The app’s secret and your renewal token never leave Cora’s API; the worker gets a one-hour access token for one step at a time. None of it appears in the database, logs, audit entries or prompts.
- The mail server keeps nothing. It reads what one question needs and answers. It logs only which tool ran and whether it worked, never an address, a search or any mail.
- Cora never sees your Google password. You sign in on Google’s page.