Channels.email.send. Two modes exist: a generated inbox, where Lua creates the address from a display name you choose, and an existing address, where you forward mail from your own mailbox to an address Lua gives you. Both are available in the admin dashboard and in lua channels.
Verified against lua-cli 3.33.0.
Before you begin
- A display name for the agent’s mail, shown in the
Fromheader. - For an existing address: access to that mailbox’s forwarding settings, or to your mail provider’s routing rules.
- An agent with a promoted production version; see Release an agent.
1
Link the address
- Dashboard
- CLI
In the admin dashboard open Agents, select the agent, select + in the Channels section of its Overview tab, and choose Email in Connect a channel. Under Connection type pick Generate new email or Use existing email, enter the Display name (and, for an existing address, the Email address), and select Connect. Email Channel Created then shows the new address; Email Channel Connected shows the address to forward your mail to, with forwarding steps for Gmail and Outlook.
2
Provider console: forward your mail (existing address only)
In your mail provider, forward everything that arrives at your address to the forwarding address Lua printed. Gmail and Google Workspace send a confirmation to the forwarding address before they activate it; the agent receives that confirmation, so complete the step from the provider’s side. Until forwarding is active, nothing reaches the agent.
3
Verify
Send an email to the connected address with the subject
Test and a question in the body. The reply arrives in the same thread with subject Re: Test. The inbound turn is in the agent’s logs.Channel behavior
Lua.request.webhook.payload is typed unknown; narrow it before reading fields. On a generated inbox the payload is the provider’s message object instead, with snake_case fields such as message_id, in_reply_to, references, subject, from, to, cc, text, and attachments.
Send email from code
Channels.email.send takes a recipient as email (any address) or userId (resolved from the end user’s history), an optional subject, and exactly one body: text as plain text, html sent as-is, or richBody, Markdown and ::: components rendered into the same branded template the agent’s replies use. cc, bcc, and attachments (fetched from a URL server-side) are optional. To keep a follow-up in an existing thread, pass the inbound email’s messageId as inReplyTo and its chain in references; these are honored on the forwarding channel.
src/tools/SendReceiptTool.ts
messageId is the provider’s message ID and status is accepted when the call returns; see the Channels reference.
Limits
- Generated address: the local part is the display name lowercased, with spaces and underscores turned into hyphens, other characters except letters, digits,
.and-removed, and cut to 30 characters; a four-character suffix is added if the name is taken.Support Teambecomessupport-team@…. - Outbound attachments: the raw bytes of all attachments on one email total at most 28 MB.
- Inbound embedded images: at least 1 KB each, at most 10 per email.
- Linking an existing address a second time doesn’t create a second channel: the channel already registered for that address is updated, including the agent it belongs to, and the same forwarding address is returned. Each generated-inbox link creates a new inbox.
Troubleshooting
Nothing arrives on an existing address
Nothing arrives on an existing address
Forwarding isn’t active. Check the provider’s forwarding rule and, for Gmail or Workspace, that the forwarding address was confirmed. Test by emailing your own address, not the forwarding address.
email send requires a text, html, or richBody body
email send requires a text, html, or richBody body
Channels.email.send was called with none of the three bodies. Pass exactly one.Attachments exceed the 28MB limit
Attachments exceed the 28MB limit
The attachments on one email add up to more than 28 MB of raw data. Split them across emails or link to the file instead.
Next steps
Send proactive messages
Receipts, reports, and reminders from jobs and webhooks.
Channels reference
Every field of
Channels.email.send and the delivery status model.Response formatting
What each component becomes in email.
About channels
The inbound and outbound channel vocabularies.