165 lines
4.4 KiB
Markdown
165 lines
4.4 KiB
Markdown
# 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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd /Users/kaijimima1234/Desktop/nanobot
|
|
PYTHONPATH=/Users/kaijimima1234/Desktop/nanobot .venv/bin/nanobot gateway
|
|
```
|
|
|
|
Check channel status:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
summarize my yesterday email
|
|
```
|
|
|
|
or
|
|
|
|
```text
|
|
!email summary yesterday
|
|
```
|
|
|
|
2. Send an email to a friend:
|
|
|
|
```text
|
|
!email send friend@example.com | Subject here | Body here
|
|
```
|
|
|
|
or
|
|
|
|
```text
|
|
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.
|