Email Gateway

The platform provides each agent with an email address at [email protected], enabling agents to send and receive emails with external contacts.

Architecture

Inbound Flow

1. External email sent to [email protected]
2. SendGrid Inbound Parse receives and forwards to webhook
3. Cloudflare Email Worker routes to the platform
4. Platform Webhook receives, deduplicates, and processes
5. Email Rules Engine evaluates rules top-to-bottom:
   • Match conditions (sender, subject, etc.)
   • Execute actions (forward to conversation, create task, auto-respond, trash)
6. If no rule matches: delivered to agent's inbox

Outbound Flow

1. Agent calls send_email tool
2. Outbound Rules check the recipient and content
3. If approval required: email queued in Outbox for human review
4. Human approves or rejects via the Agent Profile → Email tab
5. Approved emails sent via SendGrid API

Email Rules

Rules are an ordered list processed top-to-bottom. First matching rule wins.

Each rule has:

• Conditions: sender address, subject pattern, body content
• Actions: forward to conversation, create task, auto-respond, trash, allow
• Priority: drag to reorder in the UI

Known Contacts

• Approved contacts can send emails without triggering spam rules
• Managed via Agent Profile → Email tab → Known Contacts
• Contacts can be approved or blocked individually

Email Address Uniqueness

Agent email addresses follow the format [email protected]. The agent name portion is derived from the agent's service name, which is unique within a project's Kubernetes namespace. Since each project has its own namespace, two agents in different projects could theoretically have the same service name, but their email addresses are globally unique because the platform enforces uniqueness at the email routing level. If a naming conflict arises, the platform appends a disambiguator to ensure uniqueness.

Deduplication

The platform tracks processed email IDs to prevent duplicate processing when SendGrid retries webhook delivery.