← Back to Agent
Email Configuration
Connect this agent to an email account so it can send and receive emails autonomously.
Overview
For Everyone
The Email tab connects your agent to a real email account. Once connected, the agent can read incoming emails, compose replies, and send messages autonomously. You can use any email provider — Gmail, Microsoft 365, Yahoo, Zoho, Fastmail, or any custom IMAP/SMTP server.
For Developers
Email configuration is managed through /bridge/agents/:id/email-config endpoints. The system supports three providers: imap (generic IMAP/SMTP with presets), microsoft (Azure AD OAuth), and google (Google OAuth). OAuth flows open a popup window; completion is detected via postMessage. Connection testing hits /email-config/test. Re-authorization for scope changes is available for Google OAuth.
How It Works
- Choose a connection method — Email + Password (IMAP/SMTP), Microsoft OAuth, or Google OAuth.
- Enter the required credentials or configure OAuth.
- Click Save Configuration.
- For OAuth methods, click Authorize to open the sign-in popup.
- Click Test Connection to verify everything works.
The status badge in the header shows the current state: Not Connected, Configured, Awaiting Authorization, Connected, or Error.
Connection Methods
Three connection methods are presented as selectable cards:
| Method | Best For | Requirements |
|---|
| Email + Password Easy | Any email provider | Email address + app password |
| Microsoft OAuth Medium | Microsoft 365 / Outlook orgs | Azure AD app registration |
| Google OAuth Medium | Google Workspace orgs | Google Cloud project with Gmail API |
IMAP/SMTP Setup
The simplest method. Select your email provider from the preset dropdown to auto-fill server settings:
- Microsoft 365 / Outlook — imap: outlook.office365.com:993, smtp: smtp.office365.com:587
- Google Workspace / Gmail — imap: imap.gmail.com:993, smtp: smtp.gmail.com:587
- Yahoo Mail — imap: imap.mail.yahoo.com:993, smtp: smtp.mail.yahoo.com:465
- Zoho Mail — imap: imap.zoho.com:993, smtp: smtp.zoho.com:587
- Fastmail — imap: imap.fastmail.com:993, smtp: smtp.fastmail.com:587
- Custom — Enter your own IMAP/SMTP hosts and ports
Important: Use app passwords, not regular passwords. With 2FA enabled (which it should be), regular passwords won't work. Create app passwords from your provider's security settings.
Microsoft OAuth
For Microsoft 365 organizations:
- Go to Azure Portal → App Registrations
- Create a new registration with redirect URI:
{your-domain}/api/engine/oauth/callback
- Under Certificates & Secrets, create a Client Secret
- Under API Permissions, add:
Mail.ReadWrite, Mail.Send, offline_access
- Enter the Application (Client) ID, Client Secret, and Tenant ID
- Save, then click Authorize to sign in with the agent's Microsoft account
Google OAuth
For Google Workspace organizations:
- Go to Google Cloud Console → Credentials
- Create an OAuth 2.0 Client ID (Web application) with redirect URI:
{your-domain}/api/engine/oauth/callback
- Enable the Gmail API in your project
- Enter the Client ID and Client Secret
- Save, then click Authorize to sign in with the agent's Google account
A "Re-authorize (Update Scopes)" button appears for connected Google accounts when you need to add new API permissions.
Organization Email Config
If your organization has configured a shared OAuth application (Microsoft or Google), a green banner appears at the top. In this case, the Client ID and Secret are inherited automatically — you just need to authorize each agent's individual account.
Client Organization Email
When an agent belongs to a client organization (has a client_org_id), an info banner appears showing the organization name and context. This indicates:
- The agent's email configuration follows organization-level policies.
- If the organization has a configured email domain, it is displayed so you know which domain the agent sends from.
- Any email restrictions set at the organization level (e.g., allowed recipients, sending limits) are shown as warnings.
- The organization's shared OAuth configuration (if any) is inherited automatically — see Organization Email Config above.
Tip: If you manage multiple organizations, check the org banner to confirm you're configuring the right agent's email for the right organization.
Testing the Connection
After saving, click Test Connection. A successful test shows:
- Total inbox messages and unread count
- The confirmed email address
A failed test shows the specific error message. Common issues: wrong password, firewall blocking IMAP, app password not created.
Key Concepts
- App Password — A separate password generated by your email provider for third-party access. Required when 2FA is enabled.
- OAuth Flow — Opens a popup for the user to sign in with the agent's email account and grant permissions. The token is stored server-side.
- Presets — Pre-configured server settings for common email providers. Saves you from looking up IMAP/SMTP hosts and ports.
- Org Email Config — An organization-level OAuth app registration shared across all agents. Simplifies setup in enterprise environments.
- Re-authorization — For Google OAuth, when new API scopes are added, existing agents can re-authorize to gain the new permissions.
Best Practices
- Create a dedicated email for each agent — e.g., support-agent@company.com. Don't share your personal email.
- Use OAuth over IMAP/SMTP when possible — It's more secure (no stored passwords) and supports token refresh.
- Set up the org-level OAuth app — If you have multiple agents, configure the OAuth app once at the org level.
- Always test the connection after setup — Catch config issues before the agent tries to send real emails.
- Rotate app passwords periodically — Treat them like API keys.
Troubleshooting
| Problem | Solution |
|---|
| Connection test fails with "Authentication failed" | Regenerate the app password. Ensure you're using an app password, not the account password. |
| "Awaiting Authorization" badge won't clear | Click the Authorize button to open the OAuth popup. Make sure popups aren't blocked. |
| OAuth popup shows an error | Verify the redirect URI matches exactly. Check that API permissions are granted in Azure/Google. |
| Agent can receive but not send | For IMAP/SMTP: check the SMTP host and port. For M365: ensure Mail.Send permission is granted. |
| "Last Error" banner appears | The error message gives the specific issue. Common: token expired (re-authorize), password changed, account locked. |
Channels — WhatsApp and Telegram messaging setup.
WhatsApp Business — Customer-facing WhatsApp configuration.
Tools — Enable email-related tools (Gmail, Calendar, etc.).
Overview — Agent status and quick actions.