# Gmail and Google Calendar

Connect Gmail and Google Calendar so an app or an <Term id="agent">agent</Term> can work with your mail and events.

- **Gmail** reads the inbox an app works from, such as orders, invoices or support requests, and sends replies or reports from your own address. The <Term id="knowledge-graph">knowledge graph</Term> links each email to its customer or order.
- **Google Calendar** reads your events and finds free time: plan around meetings, find a free slot, or start the day with a short brief of what is coming up.

Both are under **Productivity** and connected by your <Term id="studio">Studio</Term>'s AI with a Google sign-in.

## Before you start [#before-you-start]

- A <Term id="project">project</Term>. Its Studio's AI does the work. See [Create a project](/docs/projects/create-a-project).
- The Google account whose mail or calendar the app should use. A shared address (for example an orders inbox) is often better than a person's own.
- **Start with read-only access and add sending when you need it.**

## Connect it [#connect-it]

<Steps>
<Step>
### Open Gmail [#open-gmail]
Go to <AppLink to="connectors" />, search for **Gmail** and open it.
</Step>
<Step>
### Send the request to a project's AI [#send-the-request-to-a-projects-ai]
Under **Connect it with your Studio's AI**, choose the **Project** that should use Gmail. **What the AI is asked** starts as "Connect Gmail to this project so it can read and send email." Edit it to say exactly what you want, for example: "Read new emails in the orders inbox every 15 minutes and add each order to the orders table. Do not send anything yet". Then select **Send to AI**.

The AI starts at once if the Studio is open, or when it next opens. Select **Open Studio** to go there.

<Screenshot src="/docs/_media/connect-data-with-ai-in-dashboard-data-page.png" alt="Connecting Gmail with a project's AI from the Connectors page" />
</Step>
<Step>
### Finish the connection [#finish-the-connection]
The AI drafts the connection and never asks for a key in the chat. The draft shows as **Waiting for you**. Select **Connect** to open the **Connect Gmail** dialog.

Choose **Sign in with Google**. The dialog shows the only site this sign-in is used with. Sign in with the Google account that can see the files and approve the access Google asks for. The connection then shows **Signed in as** your account.
</Step>
<Step>
### Choose what the AI may do [#choose-what-the-ai-may-do]
Under **What the AI may do with it**, choose **Can read** (nothing there changes) or **Can read and change** (the AI may also add, change and remove things). Then select **Connect**.

<Screenshot src="/docs/_media/slack-connector-how-to-connect-in-ui.png" alt="The Connect Gmail dialog with the access choice" />
</Step>
<Step>
### Test it and tell the AI [#test-it-and-tell-the-ai]
The dialog says **Gmail is connected**. Select **Test it**, then **Tell the AI** so it carries on.
</Step>
</Steps>

You can also start inside a project: in **Settings**, **Keys**, describe it in **What do you want to connect?** and select **Ask AI to connect**.

For Google Calendar, open **Google Calendar** instead and follow the same steps. For example: "Every weekday at 8:00, read today's events on my calendar and write a short brief."

<Callout type="warn" title="Sending mail is a change">
  Reading mail only needs **Can read**. Sending needs **Can read and change**. Consider an agent with an **Asks you first** step so a person approves each send. See [Runs and approvals](/docs/agents/runs).
</Callout>

## What you get [#what-you-get]

- **Mail as data.** The AI can turn emails into rows: sender, subject, date, and the fields you care about (an order number, an amount). Those rows land in a <Term id="nexus">Nexus</Term> table you can query in the <AppLink to="data.sql" />.
- **Links in the knowledge graph.** One question shows an email with its customer or order. See [Knowledge graph](/docs/data/knowledge-graph).
- **Calendar-aware agents.** An agent can read events and free time before it schedules work or writes a brief.

## Test, pause and reconnect [#test-pause-and-reconnect]

A project's connections are listed in its **Settings**, under **Keys**, with their status.

<Screenshot src="/docs/_media/manage-connections-by-toggle-on-off-per-project.png" alt="A project's connections in Settings, Keys" />

| Status | What it means |
| --- | --- |
| **Waiting for you** | Drafted by the AI. Select **Connect** to finish it. |
| **Works** | Connected and usable by the project. |
| **Needs reconnecting** | The key or sign-in stopped working. Select **Reconnect**. |
| **Paused** | Nobody can use it until you select **Resume**. |

From the same row: **Test**, **Pause**, **Turn off here** (this project stops using it) or **Remove** (deletes the key, and every Studio using it stops reaching Gmail or Google Calendar).

A connection belongs to the project it was made in. Owners and admins see all of them under **Your connections** on <AppLink to="connectors" />. It stays off for other projects until an admin switches it on under **Projects that may use** it.

## If the test fails [#if-the-test-fails]

**Test** reports one of these:

- It works: the project reached the service.
- The key was rejected: select **Reconnect** and enter a new one.
- The service cannot be reached: check that it is up and accepts outside connections, then test again.
- Internet is off: the project's internet is **Off**. Turn it on in its **Settings**. With **Only allowed**, the Studio reaches only its connections and the sites you add.
- It is not connected yet: select **Connect**.

Specific to Google:

- **Limited: permissions were not granted.** Some actions will fail. Select **Reconnect** and approve everything the job needs.
- **Was signed in as an account. Sign in again to keep using it.** A password change or an expired grant ended it. Select **Reconnect**.
- **Sending fails but reading works.** The connection has **Can read** only, or sending was not approved at sign-in. Change it to **Can read and change** and select **Reconnect**.

## Use your own sign-in app [#use-your-own-sign-in-app]

If your organization only allows sign-ins through its own registered app, choose **Use your own app instead** in the connect dialog. Register an app with the provider, add the **Return address for your app** Klarety shows, then paste its **Client id** and **Client secret** and select **Save your app**. The secret is sealed and never shown again.

## Where your key goes [#where-your-key-goes]

The key or sign-in is encrypted with a managed key service the moment you select **Connect**, and not even the AI can read it. The Studio never holds the key. If the one site it is sent to is not the service's own address, Klarety warns you and asks you to type the site to confirm.

## Next steps [#next-steps]

- [What agents do](/docs/agents)
- [Runs and approvals](/docs/agents/runs)
- [Microsoft Teams and Outlook](/docs/connectors/teams-outlook)