Email

​

Overview

• Generated inbox - Lua creates a dedicated email address for your agent (e.g. [email protected])
• Existing email - Use your own email address (e.g. [email protected]) with forwarding

​

How It Works

​

Connection Method 1: CLI

$ lua channels
✅ Using agent: myAgent

? What would you like to do? 🔗 Link new channel
? Select channel type: 📧 Email

? Select email channel mode: 📬 Generate new inbox
? Enter display name (shown in email header): Support Team

📡 Creating Email channel...

✅ Email channel created successfully!

📧 Display Name:    Support Team
📬 Email Address:   [email protected]

────────────────────────────────────────────────────
Your agent's email inbox has been created.
────────────────────────────────────────────────────

Share this address with your customers or use it
in your workflows:
   [email protected]

Emails sent to this address will be handled by
your agent.
────────────────────────────────────────────────────

$ lua channels
✅ Using agent: myAgent

? What would you like to do? 🔗 Link new channel
? Select channel type: 📧 Email

? Select email channel mode: 📧 Use existing email
? Enter display name (shown in email header): Support Team
? Enter sender email address: [email protected]

📡 Creating Email channel...

✅ Email channel created successfully!

📧 Display Name:    Support Team
📧 Sender Email:    [email protected]
📬 Forward To:      [email protected]

────────────────────────────────────────────────────
IMPORTANT: Email Forwarding Setup Required
────────────────────────────────────────────────────

1. Log into your email provider's settings
2. Set up email forwarding or filtering
3. Forward all emails from [email protected] to:
   [email protected]

4. Test by sending an email to [email protected]
   Your agent will respond automatically!
────────────────────────────────────────────────────

​

Connection Method 2: Admin Dashboard

1

Open the dashboard

lua admin

Or visit https://admin.heylua.ai.

2

Open your agent and add a channel

Click Agents in the main side navigation, select your agent’s card, click the + (plus) icon to add a channel, then choose Email.

3

Choose a connection type

In the Connect to Email dialog, enter a Display name (shown in the email header, e.g. “Support Team”) and pick how to connect, then click Connect.

• Generate new email
• Use existing email

Lua creates a new email address your customers can email directly.

Enter your business Email address — you’ll forward mail from it to Lua.

4

Finish setup

• Generated — Lua shows “Your email address is ready!” with the new address. Copy it and share it with your customers.
• Existing — Lua shows a forwarding address. Copy it and set up forwarding from your email provider (see Email Provider Setup below). Your agent only receives email once forwarding is active.

​

Email Provider Setup

​

Testing

To: [email protected]
Subject: Test
Body: Is this working?

​

Accessing Email Metadata in Tools

import { Lua, LuaTool } from 'lua-cli';
import { z } from 'zod';

export default class ThreadedReplyTool implements LuaTool {
  name = 'send_threaded_reply';
  description = 'Send a reply to an email, preserving thread';

  inputSchema = z.object({
    message: z.string(),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const webhook = Lua.request.webhook;

    if (Lua.request.channel === 'email' && webhook) {
      const { messageId, inReplyTo, subject } = webhook.payload;
      
      // Build reply subject
      const replySubject = subject?.startsWith('Re:') ? subject : `Re: ${subject}`;
      
      // Use messageId to thread the reply
      return {
        message: input.message,
        threadId: inReplyTo ?? messageId,
        subject: replySubject,
      };
    }

    return { error: 'Not an email channel' };
  }
}

​

Attachments and Embedded Images

• Regular attachments (the paperclip) — always forwarded, no size restrictions.
• Embedded images (pasted or dragged into the compose window, e.g. in Gmail) — forwarded when they are genuinely part of the message: the image must be referenced from the email’s HTML body, be an image type, and be at least 1 KB (filters out 1×1 spacer pixels). Up to 10 embedded images per email are forwarded.

• Remote-hosted images are not fetched. Images referenced by URL — for example Gmail signature images, which are hosted rather than embedded — are not downloaded. Only data actually transmitted in the email is processed.
• Embedded signature logos may come through. Some email clients (commonly corporate Outlook setups) embed signature logos directly in the message. An embedded logo over 1 KB is indistinguishable from a content image and will reach your agent as an image part. If your users’ emails are signature-heavy, consider instructing your agent to disregard branding imagery.
• Mislabeled attachments are recovered. Some clients mark real attachments as embedded content; these are detected and forwarded as normal attachments rather than dropped.

​

Sending Proactive Emails

import { Channels } from 'lua-cli';

await Channels.email.send({
  to: { email: '[email protected]' },
  subject: 'Your receipt',
  html: '<h1>Thanks for your order!</h1><p>Total: $99.00</p>',
  cc: ['[email protected]'],
  attachments: [
    { filename: 'receipt.pdf', contentType: 'application/pdf', url: 'https://files.example.com/receipt.pdf' }
  ]
});

​

Best Practices

​

Next Steps