# email

> Check, send, and auto-reply to emails using standard IMAP/SMTP protocols. Works with Gmail, Outlook, Yahoo, and any IMAP/SMTP compatible email provider.

- Author: Tang Jiu Bin
- Repository: barrontang/nanobot
- Version: 20260208055808
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/barrontang/nanobot
- Web: https://mule.run/skillshub/@@barrontang/nanobot~email:20260208055808

---

# Email Skill

Check, send, and auto-reply to emails using standard IMAP/SMTP protocols.
Works with Gmail, Outlook, Yahoo, and any IMAP/SMTP compatible email provider.

## Prerequisites

### Gmail Setup

1. Enable "Less secure app access" OR create an **App Password**:
   - Go to [Google Account Security](https://myaccount.google.com/security)
   - Enable 2-Step Verification
   - Create an App Password for "Mail"
2. Use the app password (not your regular password)

### Outlook/Microsoft 365 Setup

1. Enable IMAP in Outlook settings
2. For Microsoft 365, use an App Password or OAuth

### Generic IMAP/SMTP

Any provider that supports IMAP and SMTP will work.

## Configuration

Set environment variables:

```bash
# Required
export EMAIL_ADDRESS="your.email@example.com"
export EMAIL_PASSWORD="your-app-password"

# Optional (defaults for your provider)
export EMAIL_IMAP_HOST="imap.example.com"
export EMAIL_IMAP_PORT="993"
export EMAIL_SMTP_HOST="smtp.example.com"
export EMAIL_SMTP_PORT="465"
export EMAIL_SMTP_SSL="1"  # Set to 1/true/yes for implicit SSL (e.g., port 465)
```

For Windows PowerShell:

```powershell
# Required
$env:EMAIL_ADDRESS="your.email@example.com"
$env:EMAIL_PASSWORD='your-app-password'

# Optional (defaults for your provider)
$env:EMAIL_IMAP_HOST="imap.example.com"
$env:EMAIL_IMAP_PORT="993"
$env:EMAIL_SMTP_HOST="smtp.example.com"
$env:EMAIL_SMTP_PORT="465"
$env:EMAIL_SMTP_SSL="1"  # Set to 1/true/yes for implicit SSL (e.g., port 465)
```

### Common Provider Settings

| Provider | IMAP Host | SMTP Host | IMAP Port | SMTP Port |
| --- | --- | --- | --- | --- |
| Gmail | imap.gmail.com | smtp.gmail.com | 993 | 587 |
| Outlook | outlook.office365.com | smtp.office365.com | 993 | 587 |
| Yahoo | imap.mail.yahoo.com | smtp.mail.yahoo.com | 993 | 587 |
| iCloud | imap.mail.me.com | smtp.mail.me.com | 993 | 587 |

Notes:

- If your SMTP server requires implicit SSL (commonly port 465),
  set `EMAIL_SMTP_PORT=465` and `EMAIL_SMTP_SSL=1`.
- If your server supports STARTTLS (commonly port 587),
  keep `EMAIL_SMTP_SSL=0`.

## Usage

### Check Emails

Check recent/unread emails:

```bash
# Check last 10 emails
python nanobot/skills/email/scripts/check_email.py --count 10

# Check unread emails only
python nanobot/skills/email/scripts/check_email.py --unread

# Check specific folder
python nanobot/skills/email/scripts/check_email.py --folder "INBOX"

# Generate daily brief
python nanobot/skills/email/scripts/check_email.py --brief
```

Options:

- `--count N` - Number of emails to fetch (default: 10)
- `--unread` - Only show unread emails
- `--folder FOLDER` - Mailbox folder (default: INBOX)
- `--brief` - Generate daily summary
- `--json` - Output as JSON
- `--mark-read` - Mark fetched emails as read

### Send Email

Send an email:

```bash
python nanobot/skills/email/scripts/send_email.py \
  --to "recipient@example.com" \
  --subject "Hello" \
  --body "This is the email content."
```

Options:

- `--to` - Recipient email (required)
- `--subject` - Email subject (required)
- `--body` - Email body (required)
- `--cc` - CC recipients (comma-separated)
- `--bcc` - BCC recipients (comma-separated)
- `--html` - Send as HTML content
- `--reply-to MESSAGE_ID` - Reply to a specific email

### Auto-Reply

Set up automatic replies based on rules:

```bash
# Reply to emails from specific sender
python nanobot/skills/email/scripts/auto_reply.py \
  --from-contains "support@" \
  --reply "Thank you for contacting us. We will respond shortly."

# Reply to emails with specific subject
python nanobot/skills/email/scripts/auto_reply.py \
  --subject-contains "urgent" \
  --reply "I received your urgent email and will respond ASAP."

# Check and auto-reply in one command
python nanobot/skills/email/scripts/auto_reply.py --run-once
```

## Examples

**Morning email check:**

```bash
python nanobot/skills/email/scripts/check_email.py --unread --brief
```

**Reply to a specific email:**

```bash
python nanobot/skills/email/scripts/send_email.py \
  --to "sender@example.com" \
  --subject "Re: Meeting Tomorrow" \
  --body "Confirmed, see you at 3 PM."
```

**Daily brief for HEARTBEAT:**

```bash
python nanobot/skills/email/scripts/check_email.py --brief --unread
```

## Integration with Heartbeat

Add to `workspace/HEARTBEAT.md`:

```markdown
- [ ] Check email inbox for urgent messages: exec \
  python nanobot/skills/email/scripts/check_email.py \
  --unread --brief
- [ ] Generate daily email summary at 9 AM
```

## Security Notes

- **Never commit credentials** to version control
- Use **App Passwords** instead of your main password
- Store credentials in environment variables or a secure config file
- Consider using OAuth2 for production deployments

## Troubleshooting

### Gmail "Less secure apps" blocked

- Create an App Password instead (recommended)
- Go to Google Account → Security → App Passwords

### Connection timeout

- Check firewall settings for IMAP (993) and SMTP (587) ports
- Verify the correct host/port for your provider

### SSL/STARTTLS mismatch

- If you use port 465, enable `EMAIL_SMTP_SSL=1`
- If you use port 587, ensure `EMAIL_SMTP_SSL=0`

### Authentication failed

- Verify email and password are correct
- For Gmail/Outlook, ensure you're using an App Password
- Check if 2FA is enabled and requires special handling