From nanotars-imap-read
Adds read-only IMAP email access to NanoTars agent containers for Gmail, Yahoo, Outlook, and custom servers. Guides app password setup and .env configuration.
npx claudepluginhub terrifiedbug/nanotars-skills --plugin nanotars-imap-readThis skill uses the workspace's default tool permissions.
Read-only email access for agent containers via IMAP. Supports multiple providers simultaneously.
Configures Gmail access for NanoTars agents via gog CLI, enabling search, read, and send email capabilities. Reuses Google Calendar OAuth if configured.
Reads, searches, and manages IMAP emails (Gmail, ProtonMail Bridge). Checks new/unread messages, fetches content, marks read/unread via Node.js CLI scripts.
Adds Google Calendar (gog CLI with OAuth) and CalDAV (iCloud, Nextcloud, Fastmail via cal CLI) access to NanoTars by guiding authentication and configuring environment variables.
Share bugs, ideas, or general feedback.
Read-only email access for agent containers via IMAP. Supports multiple providers simultaneously.
Before installing, verify NanoTars is set up:
[ -d node_modules ] && echo "DEPS: ok" || echo "DEPS: missing"
docker image inspect nanoclaw-agent:latest &>/dev/null && echo "IMAGE: ok" || echo "IMAGE: not built"
if grep -q "ANTHROPIC_API_KEY\|CLAUDE_CODE_OAUTH_TOKEN" .env 2>/dev/null || [ -f "$HOME/.claude/.credentials.json" ]; then echo "AUTH: ok"; else echo "AUTH: missing"; fi
If any check fails, tell the user to run /nanotars-setup first and stop.
Check existing configuration:
grep "^IMAP_READ_ACCOUNTS=" .env 2>/dev/null && echo "ALREADY_CONFIGURED" || echo "NEEDS_SETUP"
ls plugins/imap-read/plugin.json 2>/dev/null && echo "PLUGIN_EXISTS" || echo "NO_PLUGIN"
If ALREADY_CONFIGURED, ask the user if they want to add another account or reconfigure.
Gather account details for each email provider. Collect:
imap.gmail.comimap.mail.yahoo.comoutlook.office365.comGmail:
- Go to https://myaccount.google.com/apppasswords
- You must have 2-Step Verification enabled
- Select "Other" as the app name, enter "NanoTars"
- Copy the 16-character password (spaces don't matter)
Yahoo:
- Go to https://login.yahoo.com/account/security
- Click "Generate app password"
- Select "Other app", enter "NanoTars"
- Copy the generated password
Outlook/Hotmail:
- Go to https://account.microsoft.com/security
- Under "Additional security", enable 2-Step Verification if not already
- Go to "App passwords" > Create a new app password
- Copy the generated password
Build IMAP_READ_ACCOUNTS JSON array and save to .env:
sed -i '/^IMAP_READ_ACCOUNTS=/d' .env
echo 'IMAP_READ_ACCOUNTS=[{"name":"Gmail","host":"imap.gmail.com","port":993,"user":"user@gmail.com","pass":"xxxx xxxx xxxx xxxx"}]' >> .env
(Substitute actual account details. JSON must be on a single line.)
Test credentials before deploying:
python3 -c "
import imaplib, json
accounts = json.loads('''THE_JSON_ARRAY_HERE''')
for a in accounts:
try:
m = imaplib.IMAP4_SSL(a['host'], a.get('port', 993))
m.login(a['user'], a['pass'])
m.select('INBOX', readonly=True)
_, data = m.search(None, 'UNSEEN')
count = len(data[0].split()) if data[0] else 0
print(f\"{a['name']}: OK - {count} unread emails\")
m.close(); m.logout()
except Exception as e:
print(f\"{a['name']}: FAILED - {e}\")
"
Plugin Configuration -- Ask the user which groups should have access to email reading:
mainIf the user wants to restrict access, update plugins/imap-read/plugin.json after copying (step 6) to set "groups" to the list of group folder names:
"groups": ["main"]
If all groups (or the user doesn't care), leave as "groups": ["*"].
Restricting access means only those groups' agents will have email reading tools. Other groups won't see the IMAP tools or credentials.
Also ask about channel types. If the user wants this plugin available on all channel types (WhatsApp, Discord, etc.), leave "channels": ["*"]. To restrict, set "channels" to specific types (e.g., ["whatsapp"]). Most users will want the default.
Copy plugin files:
cp -r ${CLAUDE_PLUGIN_ROOT}/files/ plugins/imap-read/
Rebuild and restart:
npm run build
nanotars restart # or launchctl on macOS
Tell the user:
Email access is configured. Test it by sending a WhatsApp message like "check my email" or "how many unread emails do I have?"
plugins/imap-read/plugin.json exists with the correct containerEnvVars, and that .env has the variable set.If this plugin is already installed and you want different credentials for a specific group (e.g., a work account for one group, personal for another):
Check which groups exist:
ls -d groups/*/
Ask the user which group should get separate credentials.
Collect the new IMAP email accounts for that group.
Write to the group's .env file (creates if needed):
echo 'IMAP_READ_ACCOUNTS=[{"name":"Work","host":"imap.gmail.com","port":993,"user":"work@company.com","pass":"app-password"}]' >> groups/{folder}/.env
These values override the global .env for that group's containers only.
Restart NanoTars:
nanotars restart
rm -rf plugins/imap-read/.env:
sed -i '/^IMAP_READ_ACCOUNTS=/d' .env