Adding Senders
Senders are the mailbox accounts that actually send your campaign emails. You can create internal mailboxes (via the integrated mail server) or connect external SMTP accounts.
Internal Mailboxes (Recommended)
If you're using the integrated docker-mailserver (default setup), you can create mailboxes directly:
Add a verified domain first
You need at least one verified domain before creating internal senders.
Create the sender
Go to Senders → Add Sender. Select your domain and enter a prefix (e.g., alex creates alex@yourdomain.com).
Mailbox is auto-created
Cleanmails automatically creates the mailbox on docker-mailserver with a secure random password, configures SMTP and IMAP credentials, and tests the connection.
External SMTP Accounts
Connect any external email account (Gmail, Outlook, custom SMTP):
Click Add Sender → External
Select "External SMTP" mode.
Enter credentials
Provide:
- Email — The full email address
- Name — Display name for the From header
- SMTP Host — e.g., smtp.gmail.com
- SMTP Port — Usually 587 (STARTTLS) or 465 (SSL)
- Username — Usually the email address
- Password — App password (for Gmail, generate at myaccount.google.com)
- IMAP Host (optional) — For reply detection
- IMAP Port — Usually 993
Connection test
Cleanmails tests both SMTP and IMAP connections before saving. If SMTP fails, the sender is not created.
All sender passwords are encrypted with AES using your MASTER_KEY before storage. They are never exposed in API responses.
Sender Properties
| Property | Description |
|---|---|
| Daily Limit | Max emails per day (default: 50). Prevents over-sending. |
| Health Score | 0-100 reputation indicator. Decreases on bounces, increases on successful sends. |
| Warmup Mode | When enabled, sender participates in warmup (not used for campaigns). |
| Status | ready, warmup, or restricted |
| Cooldown | Auto-paused for 30 min after 3 consecutive errors |
Sender Health
Health score changes:
- Successful send: +1 (up to 100)
- Soft bounce: -5
- Hard bounce: -10 to -15
- Permanent failure: -10
Senders with health below 20 are excluded from campaign assignment.
After 3 consecutive errors, a sender is automatically put in cooldown for 30 minutes. This prevents hammering a broken connection and protects reputation.