Connect Mail to Custom Agents

Custom Agents can connect to your Gmail to automate email workflows. Once connected, agents can read, organize, draft, and send emails on your behalf through automated triggers or by chatting with the agent directly.

Mail connections work with Gmail or Notion Mail. Using Notion Mail is not required to make use of the Mail connection capabilities.

The Mail connection for Custom Agents is available on any plan with access to Custom Agents.

The below actions are supported in both Notion Mail and Gmail:

Notion Mail-only actions

The below actions are supported only if using Notion Mail:

1. Chat with your agent. Give it specific direction on how to handle mail events.

   • This can also be done manually in a Custom Agent's Settings. Go to Tools & Access, then choose + Add connection → Mail → Connect

2. Under Settings → Tools & Access, grant the permissions your agent needs:

   Modify inbox, Draft, and Send. Choose if the Agent should Require confirmation before executing an action.

3. Test the connection. If the agent’s behavior isn’t what you expect, chat with your agent to clarify instructions.

Tip: Be specific in your instructions. For example: "Archive all emails from newsletters with the word 'weekly' in the subject line" or "Draft a polite reply to customer inquiries and save them for my review."

Add a mail-based trigger in your Custom Agent’s Settings.

1. Go to Triggers. Click + Add trigger → Mail → Connect.

2. Under Mail, choose from the following triggers:

   • New email received: Runs when a new email arrives in the connected mailbox.

   • New email sent: Runs when you send a new email from the connected mailbox.

   • New email received or sent: Runs when a new email is either received or sent.

   • Label applied to email: Runs when a specific label is applied to an email.

3. Choose the Inbox you want the trigger to run on.

4. Add a filter to narrow which events fire a Mail trigger. Each trigger can be filtered to only run when an email fits a specified From, To, Subject, Body, or Domain attribute.

When you connect Mail, you can choose your Agent’s permissions:

• Modify inbox: Archive, trash, apply labels, set reminders, block senders, and unsubscribe.

• Draft: Create drafts.

• Send: Send emails from your account.

• Require confirmation: Requires a user to approve or cancel an action before it executes. When toggled off, the agent can take the allowed actions without approval.

Tip: Use permissions and triggers (like running only when a label is applied) if you want to restrict which emails the agent processes.

If you share a Custom Agent that’s connected to Mail, anyone who has access to that Agent can view emails in the connected inbox. A warning will be shown before taking this action.

To get the best results, give your Custom Agent specific instructions.

• Inbox organizer: Automatically triage incoming messages by applying labels, archiving low-priority emails, and setting reminders for important ones.
  Tell your Custom Agent: "When I receive an email, check if it's a newsletter. If yes, apply the 'Newsletter' label and archive it. If it's from a customer, star it and apply the 'Customer' label."

• Inbox cleanup assistant: Unsubscribe from unwanted mailing lists and archive or delete promotional emails automatically.
  Tell your Custom Agent: "Review my inbox for subscription emails. Unsubscribe from any newsletters I haven't opened in 30 days and archive them."

• Email-to-database sync: Extract key information from emails and create or update records in a Notion database.

  Tell your Custom Agent: "When I receive an email from a new contact, create a page in my CRM database with their name, email, and company. Add a link to the original email."

• Auto-reply assistant: Draft responses to common inquiries and save them for your review before sending.

  Tell your Custom Agent: "When I receive an email asking about pricing, draft a friendly reply with our standard pricing information and save it as a draft for me to review."

If your Custom Agent encounters errors, give the run a “thumbs down” and chat with the Agent to diagnose the issue. Then try these steps:

Connection errors

If you can’t find Mail in Tools & Access, Mail disconnects, or your agent says it can’t access email:

• Confirm your Agent is connected to the correct email account.

• Verify you have permission to edit the agent (Can edit or Full access).

• Disconnect and reconnect the Mail connection, then refresh Notion.

Trigger errors

If your agent isn’t running when email is received, is running multiple times, or can’t access email content:

• Check the agent’s Activity to confirm whether the trigger is firing vs. firing but failing.

• Verify the Mail connection is still active in Tools & Access.

• For label-based triggers, confirm the label name matches exactly.