nanobot/EMAIL_ASSISTANT_E2E_GUIDE.md

Nanobot Email Assistant: End-to-End Guide

This guide explains how to run nanobot as a real email assistant with explicit user permission and optional automatic replies.

1. What This Feature Does

• Read unread emails via IMAP.
• Let the agent analyze/respond to email content.
• Send replies via SMTP.
• Enforce explicit owner consent before mailbox access.
• Let you toggle automatic replies on or off.

2. Permission Model (Required)

channels.email.consentGranted is the hard permission gate.

• false: nanobot must not access mailbox content and must not send email.
• true: nanobot may read/send based on other settings.

Only set consentGranted: true after the mailbox owner explicitly agrees.

3. Auto-Reply Mode

channels.email.autoReplyEnabled controls outbound automatic email replies.

• true: inbound emails can receive automatic agent replies.
• false: inbound emails can still be read/processed, but automatic replies are skipped.

Use autoReplyEnabled: false when you want analysis-only mode.

4. Required Account Setup (Gmail Example)

1. Enable 2-Step Verification in Google account security settings.
2. Create an App Password.
3. Use this app password for both IMAP and SMTP auth.

Recommended servers:

• IMAP host/port: imap.gmail.com:993 (SSL)
• SMTP host/port: smtp.gmail.com:587 (STARTTLS)

5. Config Example

Edit ~/.nanobot/config.json:

{
  "channels": {
    "email": {
      "enabled": true,
      "consentGranted": true,
      "imapHost": "imap.gmail.com",
      "imapPort": 993,
      "imapUsername": "you@gmail.com",
      "imapPassword": "${NANOBOT_EMAIL_IMAP_PASSWORD}",
      "imapMailbox": "INBOX",
      "imapUseSsl": true,
      "smtpHost": "smtp.gmail.com",
      "smtpPort": 587,
      "smtpUsername": "you@gmail.com",
      "smtpPassword": "${NANOBOT_EMAIL_SMTP_PASSWORD}",
      "smtpUseTls": true,
      "smtpUseSsl": false,
      "fromAddress": "you@gmail.com",
      "autoReplyEnabled": true,
      "pollIntervalSeconds": 30,
      "markSeen": true,
      "allowFrom": ["trusted.sender@example.com"]
    }
  }
}

6. Set Secrets via Environment Variables

In the same shell before starting gateway:

read -s "NANOBOT_EMAIL_IMAP_PASSWORD?IMAP app password: "
echo
read -s "NANOBOT_EMAIL_SMTP_PASSWORD?SMTP app password: "
echo
export NANOBOT_EMAIL_IMAP_PASSWORD
export NANOBOT_EMAIL_SMTP_PASSWORD

If you use one app password for both, enter the same value twice.

7. Run and Verify

Start:

cd /Users/kaijimima1234/Desktop/nanobot
PYTHONPATH=/Users/kaijimima1234/Desktop/nanobot .venv/bin/nanobot gateway

Check channel status:

PYTHONPATH=/Users/kaijimima1234/Desktop/nanobot .venv/bin/nanobot channels status

Expected behavior:

• enabled=true + consentGranted=true + autoReplyEnabled=true: read + auto reply.
• enabled=true + consentGranted=true + autoReplyEnabled=false: read only, no auto reply.
• consentGranted=false: no read, no send.

8. Commands You Can Tell Nanobot

Once gateway is running and email consent is enabled:

1. Summarize yesterday's emails:

summarize my yesterday email

or

!email summary yesterday

2. Send an email to a friend:

!email send friend@example.com | Subject here | Body here

or

send email to friend@example.com subject: Subject here body: Body here

Notes:

• Sending command always performs a direct send (manual action by you).
• If consentGranted is false, send/read are blocked.
• If autoReplyEnabled is false, automatic replies are disabled, but direct send command above still works.

9. End-to-End Test Plan

1. Send a test email from an allowed sender to your mailbox.
2. Confirm nanobot receives and processes it.
3. If autoReplyEnabled=true, confirm a reply is delivered.
4. Set autoReplyEnabled=false, send another test email.
5. Confirm no auto-reply is sent.
6. Set consentGranted=false, send another test email.
7. Confirm nanobot does not read/send.

10. Security Notes

• Never commit real passwords/tokens into git.
• Prefer environment variables for secrets.
• Keep allowFrom restricted whenever possible.
• Rotate app passwords immediately if leaked.

11. PR Checklist

• consentGranted gating works for read/send.
• autoReplyEnabled toggle works as documented.
• README updated with new fields.
• Tests pass (pytest).
• No real credentials in tracked files.