Skip to main content
Email integration allows nanobot to monitor an inbox via IMAP and reply via SMTP, functioning as a personal email assistant.

​
Features

  • ✅ IMAP polling for incoming mail
  • ✅ SMTP for sending replies
  • ✅ Email address-based access control
  • ✅ Automatic reply mode
  • ✅ Consent-based mailbox access
  • ✅ Gmail and other providers supported

​
Prerequisites

  • A dedicated email account for your bot (e.g., Gmail)
  • IMAP and SMTP access enabled
  • App-specific password (if using Gmail)

​
Setup

1

Create dedicated email account

Create a new email account for your bot:Example: [email protected]
2

Enable IMAP access

For Gmail:
  1. Go to Gmail Settings → See all settings
  2. Click Forwarding and POP/IMAP tab
  3. Under IMAP access, select Enable IMAP
  4. Click Save Changes
3

Generate app password

For Gmail:
  1. Go to Google Account settings
  2. Enable 2-Step Verification if not already enabled
  3. Go to App Passwords
  4. Select app: Mail
  5. Select device: Other (enter “nanobot”)
  6. Click Generate
  7. Copy the 16-character app password
Use this app password for both IMAP and SMTP in the config
4

Configure nanobot

Edit ~/.nanobot/config.json:
{
  "channels": {
    "email": {
      "enabled": true,
      "consentGranted": true,
      "imapHost": "imap.gmail.com",
      "imapPort": 993,
      "imapUsername": "[email protected]",
      "imapPassword": "your-app-password",
      "smtpHost": "smtp.gmail.com",
      "smtpPort": 587,
      "smtpUsername": "[email protected]",
      "smtpPassword": "your-app-password",
      "fromAddress": "[email protected]",
      "allowFrom": ["[email protected]"]
    }
  }
}
5

Start the gateway

nanobot gateway
You should see:
Email channel connected
Monitoring inbox: [email protected]
6

Test the connection

  1. Send an email to your bot’s address (e.g., [email protected])
  2. Wait for IMAP polling (usually a few seconds)
  3. Your bot should reply automatically!

​
Configuration Options

​
enabled
boolean
required
Enable the email channel
​
consentGranted
boolean
required
Safety gate: Must be true to allow mailbox accessSet to false to fully disable email channel without removing config.
​
imapHost
string
required
IMAP server hostnameCommon values:
  • Gmail: imap.gmail.com
  • Outlook: outlook.office365.com
  • Yahoo: imap.mail.yahoo.com
​
imapPort
number
required
IMAP server port (usually 993 for SSL)
​
imapUsername
string
required
IMAP username (usually your full email address)
​
imapPassword
string
required
IMAP password (use app password for Gmail)
​
smtpHost
string
required
SMTP server hostnameCommon values:
  • Gmail: smtp.gmail.com
  • Outlook: smtp.office365.com
  • Yahoo: smtp.mail.yahoo.com
​
smtpPort
number
required
SMTP server port (usually 587 for TLS or 465 for SSL)
​
smtpUsername
string
required
SMTP username (usually your full email address)
​
smtpPassword
string
required
SMTP password (use app password for Gmail)
​
smtpUseTls
boolean
default:"true"
Use STARTTLS for SMTP (default: true for port 587)
​
smtpUseSsl
boolean
default:"false"
Use SSL for SMTP (default: false, set true for port 465)
​
fromAddress
string
required
Email address to send replies from (usually same as bot’s email)
​
allowFrom
array
required
List of email addresses allowed to interact with the botExamples:
​
autoReplyEnabled
boolean
default:"true"
If false, bot reads/analyzes emails but doesn’t send automatic replies

​
Common Email Providers

{
  "imapHost": "imap.gmail.com",
  "imapPort": 993,
  "smtpHost": "smtp.gmail.com",
  "smtpPort": 587,
  "smtpUseTls": true,
  "smtpUseSsl": false
}
Requires app password: https://myaccount.google.com/apppasswords

​
Read-Only Mode

If you want nanobot to read and analyze emails without sending automatic replies:
{
  "channels": {
    "email": {
      "enabled": true,
      "consentGranted": true,
      "autoReplyEnabled": false,
      "imapHost": "imap.gmail.com",
      "imapPort": 993,
      "imapUsername": "[email protected]",
      "imapPassword": "your-app-password",
      "allowFrom": ["[email protected]"]
    }
  }
}
SMTP settings are optional when autoReplyEnabled is false.

​
Troubleshooting

Common Gmail authentication issues:
  1. Not using app password:
  2. 2-Step Verification not enabled:
  3. IMAP not enabled:
    • Gmail Settings → Forwarding and POP/IMAP → Enable IMAP
  4. Less secure apps:
    • Google deprecated this option
    • Use app passwords instead
If IMAP/SMTP connection times out:
  1. Check firewall settings (ensure ports 993 and 587 are open)
  2. Verify server hostnames are correct
  3. Try different ports (465 for SSL SMTP)
  4. Check internet connectivity
  5. Verify email provider doesn’t block automated access
  1. Verify sender email is in allowFrom list
  2. Check consentGranted is set to true
  3. Check autoReplyEnabled is not set to false
  4. Look for errors in logs: nanobot gateway -v
  5. Verify SMTP settings are correct
  6. Check email quotas (some providers limit sends per day)
If you see TLS or SSL errors:For port 587 (STARTTLS):
{
  "smtpPort": 587,
  "smtpUseTls": true,
  "smtpUseSsl": false
}
For port 465 (SSL):
{
  "smtpPort": 465,
  "smtpUseTls": false,
  "smtpUseSsl": true
}
If bot replies are marked as spam:
  1. Use a proper fromAddress (not a personal email)
  2. Add SPF/DKIM records if using custom domain
  3. Avoid spammy content in replies
  4. Don’t send too many emails too quickly
  5. Ask recipients to mark as “Not Spam”

​
Complete Example

Full configuration with all options: 
{
  "channels": {
    "email": {
      "enabled": true,
      "consentGranted": true,
      "imapHost": "imap.gmail.com",
      "imapPort": 993,
      "imapUsername": "[email protected]",
      "imapPassword": "abcd efgh ijkl mnop",
      "smtpHost": "smtp.gmail.com",
      "smtpPort": 587,
      "smtpUsername": "[email protected]",
      "smtpPassword": "abcd efgh ijkl mnop",
      "smtpUseTls": true,
      "smtpUseSsl": false,
      "fromAddress": "[email protected]",
      "allowFrom": ["[email protected]"],
      "autoReplyEnabled": true
    }
  }
}

Configuration Overview

Learn about channel configuration

Security Settings

Set up access control

Build docs developers (and LLMs) love

Get started for freeTalk to us