TriLuna Try it free

email-tool-setup-guide

Email Tool Setup Guide for TriLuna Platform

Quick Reference

Email Tool Webhook URL: https://api.triluna.app/api/email-tool/webhook Tool Name: email Tool ID: 5 Admin Page: https://triluna.app/admin/tools Requirements: Enterprise plan only

Step-by-Step Setup

Step 1: Configure Email Credentials (API)

Enterprise users must configure their IMAP/SMTP credentials before using the email tool.

API Endpoint: POST /api/email-credentials

Example using curl (get auth token from TriLuna dashboard):

curl -X POST https://api.triluna.app/api/email-credentials \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "nik@triluna.app",
    "email_username": "nik@triluna.app",
    "email_password": "mailpass",
    "imap_host": "mail.triluna.app",
    "imap_port": 993,
    "imap_secure": true,
    "smtp_host": "mail.triluna.app",
    "smtp_port": 587,
    "smtp_secure": false
  }'

Response (success):

{
  "success": true,
  "message": "Email credentials saved successfully",
  "email_address": "nik@triluna.app",
  "connection_status": "success"
}

Note: The API automatically tests the IMAP connection before saving. If the connection fails, you’ll get an error with details.

Step 2: Enable Email Tool for Your Agent in ElevenLabs

Option A: Via ElevenLabs Dashboard UI

  1. Go to ElevenLabs Conversational AI Dashboard
  2. Find your agent (e.g., agent_0001k5zakhj8ffs95cj76pa71vae)
  3. Click “Edit” or “Configure”
  4. Navigate to the “Tools” or “Custom Tools” section
  5. Click “Add Custom Tool” or “Add Webhook”
  6. Enter the following details:
    • Tool Name: email (or any name you prefer for display)
    • Webhook URL: https://api.triluna.app/api/email-tool/webhook
    • Method: POST
    • Description: “Search, read, and draft emails during conversations”
  7. Configure the tool parameters: 
    {
  "agent_id": "{{agent_id}}",
  "conversation_id": "{{conversation_id}}",
  "action": "string (search_emails, read_email, create_draft, create_reply_draft)",
  "search_query": "string (for search_emails)",
  "email_id": "string (for read_email)",
  "draft_to": "string (for create_draft)",
  "draft_subject": "string (for create_draft)",
  "draft_body": "string (for create_draft/create_reply_draft)",
  "reply_to_id": "string (for create_reply_draft)"
}
  8. Save the configuration

Option B: Via ElevenLabs API

Use the ElevenLabs API to add the tool to your agent programmatically:

curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/{agent_id}" \
  -H "xi-api-key: YOUR_ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_config": {
      "tools": [
        {
          "type": "webhook",
          "name": "email",
          "description": "Search, read, and draft emails during conversations",
          "url": "https://api.triluna.app/api/email-tool/webhook",
          "method": "POST",
          "parameters": {
            "type": "object",
            "properties": {
              "action": {
                "type": "string",
                "enum": ["search_emails", "read_email", "create_draft", "create_reply_draft"],
                "description": "The email operation to perform"
              },
              "search_query": {
                "type": "string",
                "description": "Search query for finding emails (e.g., 'from:john@example.com')"
              },
              "email_id": {
                "type": "string",
                "description": "ID of email to read (from search results)"
              },
              "draft_to": {
                "type": "string",
                "description": "Recipient email address for draft"
              },
              "draft_subject": {
                "type": "string",
                "description": "Subject line for draft email"
              },
              "draft_body": {
                "type": "string",
                "description": "Body content for draft email"
              },
              "reply_to_id": {
                "type": "string",
                "description": "ID of email to reply to"
              }
            },
            "required": ["action"]
          }
        }
      ]
    }
  }'

Step 3: Test the Email Tool

Once configured, test the email tool during a conversation with your agent:

Example conversation:

  • User: “Search my emails for messages from John”
  • Agent: (calls email tool with action: "search_emails", search_query: "from:john")
  • Agent: “I found 3 emails from John. The most recent one is…”

Example conversation (reading):

  • User: “Read the first email”
  • Agent: (calls email tool with action: "read_email", email_id: "123")
  • Agent: “That email says…”

Example conversation (drafting):

  • User: “Draft a reply saying thank you”
  • Agent: (calls email tool with action: "create_draft", draft_to: "john@example.com", draft_subject: "Re: ...", draft_body: "Thank you...")
  • Agent: “I’ve created a draft reply. You can review and send it from your email client.”

Email Tool Actions

1. search_emails

Search for emails using IMAP SEARCH.

Parameters:

  • action: “search_emails”
  • search_query: Text to search for (searches across all fields)

Example:

{
  "agent_id": "agent_0001k5zakhj8ffs95cj76pa71vae",
  "conversation_id": "conv_123",
  "action": "search_emails",
  "search_query": "meeting"
}

Response:

{
  "success": true,
  "action": "search_emails",
  "query": "meeting",
  "count": 5,
  "emails": [
    {
      "id": "123",
      "from": "john@example.com",
      "to": "nik@triluna.app",
      "subject": "Meeting tomorrow",
      "date": "2025-10-11T10:00:00Z",
      "snippet": "Let's meet at 3pm..."
    }
  ]
}

2. read_email

Read full email content by ID.

Parameters:

  • action: “read_email”
  • email_id: ID from search results

Example:

{
  "agent_id": "agent_0001k5zakhj8ffs95cj76pa71vae",
  "action": "read_email",
  "email_id": "123"
}

Response:

{
  "success": true,
  "action": "read_email",
  "email": {
    "id": "123",
    "from": "john@example.com",
    "to": "nik@triluna.app",
    "subject": "Meeting tomorrow",
    "date": "2025-10-11T10:00:00Z",
    "body": "Full email body content here..."
  }
}

3. create_draft

Create a new email draft.

Parameters:

  • action: “create_draft”
  • draft_to: Recipient email
  • draft_subject: Email subject
  • draft_body: Email body

Example:

{
  "agent_id": "agent_0001k5zakhj8ffs95cj76pa71vae",
  "action": "create_draft",
  "draft_to": "john@example.com",
  "draft_subject": "Re: Meeting tomorrow",
  "draft_body": "Thanks for the invitation. I'll be there at 3pm."
}

Response:

{
  "success": true,
  "action": "create_draft",
  "message": "Draft created successfully and saved to Drafts folder. The user can review and send it from their email client."
}

4. create_reply_draft

Create a reply draft to an existing email.

Parameters:

  • action: “create_reply_draft”
  • reply_to_id: ID of email to reply to
  • draft_body: Reply body content

Example:

{
  "agent_id": "agent_0001k5zakhj8ffs95cj76pa71vae",
  "action": "create_reply_draft",
  "reply_to_id": "123",
  "draft_body": "Thanks for the invitation. I'll be there at 3pm."
}

Troubleshooting

”Email account not configured”

The user hasn’t set up their IMAP/SMTP credentials yet. They need to:

  1. Call POST /api/email-credentials with their email settings
  2. Verify the connection test passes

”Email integration is only available for Enterprise plan users”

The user needs to upgrade to an Enterprise plan. Check their subscription at:

SELECT u.email, sp.name as plan
FROM users u
LEFT JOIN subscription_plans sp ON u.subscription_plan_id = sp.id
WHERE u.email = 'nik@triluna.app';

“IMAP connection test failed”

Common causes:

  • Incorrect IMAP server or port
  • Wrong username or password
  • Firewall blocking IMAP connections (port 993 or 143)
  • Server requires app-specific password (Gmail, Outlook.com)

Test the connection manually:

curl -X POST https://api.triluna.app/api/email-credentials/test \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Tool not appearing in ElevenLabs

If the email tool doesn’t appear:

  1. Verify it’s in the database: SELECT * FROM webhook_tools WHERE tool_name = 'email'
  2. Check is_active is 1 (true)
  3. Check the webhook URL is accessible: curl https://api.triluna.app/api/email-tool/webhook
  4. Try manually adding the webhook URL in ElevenLabs custom tools

Checking User Configuration

Get user ID for nik@triluna.app:

SELECT id, email, subscription_plan_id FROM users WHERE email = 'nik@triluna.app';

Check if user has email credentials configured:

SELECT * FROM email_credentials WHERE user_id = (
  SELECT id FROM users WHERE email = 'nik@triluna.app'
);

Check webhook tool usage:

SELECT * FROM webhook_logs
WHERE tool_id = 5
ORDER BY created_at DESC
LIMIT 10;

Admin Interface

The email tool should appear at: https://triluna.app/admin/tools

It will show:

Next Steps

  1. ✅ Email tool is active and configured in database
  2. ⏳ Configure IMAP/SMTP credentials for nik@triluna.app
  3. ⏳ Add email tool to agent in ElevenLabs dashboard
  4. ⏳ Test email search/read/draft during conversation
  5. 🔮 Future: Add UI in TriLuna dashboard for easier credential management

Related Documentation:

  • Full technical docs: /docs/email-tool-integration.md
  • Gmail OAuth (future): GitHub Issue #379
  • MS365 OAuth (future): GitHub Issue #380