# fw-nodes-email

Email (SMTP/IMAP) nodes for Flowire workflow automation.

## Nodes

### Send Email

Send emails via SMTP with support for HTML content, CC/BCC/Reply-To headers, and file attachments (base64-encoded).

- **Credential:** SMTP (host, port, username, password, TLS/SSL)
- **Inputs:** from address, to, subject, body, optional CC/BCC/Reply-To, optional attachments
- **Outputs:** success status, message ID, recipient list

### Read Emails

Fetch emails from a mailbox via IMAP with filtering and folder selection.

- **Credential:** IMAP (host, port, username, password, SSL)
- **Inputs:** folder, IMAP search filter (e.g. `UNSEEN`, `FROM "user@example.com"`), max results, mark as read, include attachment content
- **Outputs:** list of emails (headers, plain/HTML body, attachment metadata), count, folder

### Email Trigger

Stream trigger node that fires workflows in real-time when new emails arrive via IMAP IDLE.

- **Credential:** IMAP
- **Inputs:** folder to monitor
- **Outputs:** event type, sender, recipients, subject, date, plain/HTML body, attachments, raw event
- **Stream handler:** `ImapIdleStreamHandler` — maintains a persistent IMAP IDLE connection and yields events on new mail (re-issues IDLE every 25 minutes per RFC 2177)

## Credentials

| Type | Default Port | Encryption                         |
|------|--------------|------------------------------------|
| SMTP | 587          | STARTTLS (or 465 for implicit SSL) |
| IMAP | 993          | SSL/TLS                            |

## Installation

```bash
pip install fw-nodes-email
```

Enable in your backend `.env`:

```env
INSTALLED_NODE_PACKAGES=fw-nodes-core,fw-nodes-email
```

## Entry Points

```toml
# Nodes (flowire.nodes)
email_send    = "fw_nodes_email.nodes.send_email:SendEmailNode"
email_read    = "fw_nodes_email.nodes.read_emails:ReadEmailsNode"
email_trigger = "fw_nodes_email.nodes.email_trigger:EmailTriggerNode"

# Stream handlers (flowire.stream_handlers)
imap_idle = "fw_nodes_email.handlers.imap_idle:ImapIdleStreamHandler"
```

## Development

```bash
just install    # Install dependencies
just test       # Run tests
just lint       # Run linter
just format     # Format code
```
