start using Gmail with your agents
sign up, open a project, and authorise Gmail from its connectors settings.
email is where requests, invoices and alerts land, and a new message is often the moment an agent should start. connecting gmail to a project turns that moment into a run: an agent subscribes to a label or the whole mailbox from a chat, and the next matching message starts a run with the body in hand, in that chat or in a new chat in the same project when the routine opens one per event. the connector reads and nothing else. it does not draft, send or organise mail, and no gmail mcp server can be connected today.
subscribing from a chat
gmail_subscribe takes a resource, the events to watch, and what the agent should do when one arrives. a label routine takes a label id such as INBOX or a label's display name, and fires when a message arrives in the label or is removed from it, and when the label is added to or taken off a message. a mailbox routine fires on every received and sent message. gmail_unsubscribe takes an event routine off again, and the project's Settings → Routines lists every routine the agents hold. gmail batches its pushes, so a busy mailbox can start several runs at once.
each notification carries the event routine, the actor, a one-line summary and a link. a received or sent message also carries its plain-text body: the text part when the email has one, or the html part converted to text without tags. the body is fenced off as untrusted data and capped at 4,000 characters, so an email can inform the agent but cannot instruct it.
limited access during google verification
gmail is in limited access while aldena finishes google's verification. in a project without access, the connector row shows Request access instead of connect, and the request goes to aldena by email. once access is granted for the project, any member connects it and authorises as themselves, and google's consent screen asks for read-only gmail access and nothing more.
going beyond triggers: no gmail mcp server today
no mcp server for gmail can be connected to aldena today. google's gmail mcp server is a developer preview that aldena cannot connect to, and it has no send tool, so it would not let an agent answer mail even if it could. other vendors' servers go in through the project's Settings → Connectors → MCP servers, as the mcp servers page describes, but there is no gmail entry to add there. a triggered agent reports what it found in the chat where it subscribed, or in a new chat in the same project when the routine opens one per event, and a person replies from gmail.
example tasks
- 01
when a new message lands in the invoices label, tell me the amount and the due date.
the label routine starts a run in this chat for each new message, with the plain-text body in the notification. the agent reads the amount and the due date from it and posts them here.
gmail_subscribe - 02
when the vendor emails about the api change, check our client code against it.
the mailbox routine starts a run on each received message. when one is from the vendor, the agent syncs the repository to the conversation's sandbox, checks the client code over bash, and reports what breaks.
gmail_subscribegithub_git_syncbash - 03
stop watching the sales label.
the agent lists its routines, finds the event routine on the sales label, and removes it, so new mail there no longer starts runs.
list_routinesgmail_unsubscribe
what it will not do
the connector does not draft, send, label, archive or delete mail, read old threads, or change mailbox settings, filters or forwarding. it holds read-only access, and no event starts a run while the connection waits for a reconnect.
what starts a run
every Gmail event an agent can subscribe to, grouped by resource. an agent subscribes from a chat with gmail_subscribe, and each matching event starts a run in that chat, or in a new chat in the same project when the routine opens one per event.
message.receivedmessage.removedlabel.addedlabel.removed
message.receivedmessage.sent
what you grant
aldena asks Gmail for exactly this access on the consent screen, the same set for every project. there is nothing to pick, and nothing else is requested.
- Read mail
https://www.googleapis.com/auth/gmail.readonlyWatch the mailbox for received, sent and relabeled mail. Aldena cannot draft, send, label or delete mail.
how to connect Gmail
connecting Gmail takes one authorisation round trip, started from inside the project that needs it.
- open the project's connectors settings
connections belong to a project, not to your account or the team. open the project that needs Gmail, go to settings → connectors, and press connect. other projects stay untouched.
- authorise with a real account
any member of the project can start the connection, and they authorise as themselves. Gmail asks only for the fixed access listed above, with no scopes to choose.
- an agent subscribes from a chat
ask an agent in a project chat to watch something in Gmail. it calls gmail_subscribe with the resource, events and intent, and settings → routines lists each routine it holds.
- a matching event starts a run
each matching event starts a run with the event and its content in hand, in the chat where the agent subscribed or in a new chat in the same project when the routine opens one per event. disconnecting Gmail stops every subscription to it.
data handling and security
a connector holds one credential and turns Gmail events into runs. the credential stays inside the project that connected it, and event text is data, never instructions.
- one connection, one project
the Gmail credential is stored against the project it was authorised in. no agent in another project can use it, and there is no team-wide connection to inherit by accident.
- tokens encrypted at rest
the Gmail token is encrypted before it is stored, and it never appears in a chat or in an agent's prompt. agents get the events, not the credential.
- events only where a routine watches
aldena verifies each delivery came from Gmail. an event starts a run only for a routine it matches, in the chat that set the routine up or in a new chat in the same project when the routine opens one per event. nothing starts while the connection needs a reconnect.
- event content is untrusted
event text may come from a stranger. it reaches the agent as fenced data capped at 4,000 characters, and the agent is told never to follow instructions in it.
- revocation is one click
disconnect Gmail and the project's event routines on it stop at once, along with the stored credential.

each Gmail tool agents hold has its own allow, ask or deny row in the project's permissions. see human in the loop for approvals and isolated projects for isolation.
faq
can an ai agent send or draft email from my gmail account?
no. the gmail connector only starts runs, and aldena asks google for gmail.readonly and nothing else, so it cannot draft, send, label or delete mail. google's gmail mcp server is a developer preview aldena cannot connect to, and it has no send tool either. a triggered agent reports in the chat where it subscribed, or in a new chat in the same project when the routine opens one per event.
what does a gmail event notification contain?
the event routine, the actor, a one-line summary and a link. a received or sent message also carries its plain-text body: the text part when the email has one, or the html part converted to text without tags. the body is fenced off as untrusted data and capped at 4,000 characters.
is gmail available on every project?
gmail is in limited access while google verification finishes, and it is turned on per project by request. until access is granted for a project, the connector shows a request access button instead of connect, so no agent in that project can subscribe to the mailbox.
can an agent watch one label rather than the whole inbox?
yes. a label routine takes a label id such as INBOX or a label's display name, resolved at subscribe time so a later rename does not break it, and fires when mail arrives in the label or leaves it, and when the label is added to or taken off a message. a mailbox routine fires on every received and sent message.
what happens to mail that arrived while gmail needed a reconnect?
it is not replayed. while a connection waits for a reconnect no event starts a run, and reconnecting starts a fresh watch from that moment, so the agent picks up new mail without a burst of old notifications. existing event routines fire again without the agent subscribing twice.
spin up your first project.
one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.
