Connecting a Mailbox

To send and receive with SpiderMail, you first connect a mailbox — an existing email account you own. You supply its IMAP settings (for reading) and SMTP settings (for sending), and SpiderMail stores the credentials encrypted with Fernet at rest. Passwords are never returned by the API afterward.

Before you start

Use an account you can log into over IMAP and SMTP. Web-only or POP-only accounts will not work.
Create an app-specific password and use that instead of your normal password. All five named providers (Zoho, Gmail, Google Workspace, Outlook, iCloud) require one.
You do not need the IMAP/SMTP host and port — they come from the provider preset. Have them ready only for generic_imap or a non-standard server.

Register a mailbox

Send the account's connection settings to POST /mail/mailboxes:

curl -X POST "https://spideriq.ai/api/v1/mail/mailboxes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "alice@yourcompany.com",
    "display_name": "Alice from YourCompany",
    "provider": "google_workspace",
    "imap_host": "imap.gmail.com",
    "imap_port": 993,
    "imap_username": "alice@yourcompany.com",
    "imap_password": "APP_PASSWORD",
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_username": "alice@yourcompany.com",
    "smtp_password": "APP_PASSWORD"
  }'

The provider field is one of zoho, gmail, google_workspace, outlook, icloud, or generic_imap. display_name is the friendly "from" name recipients see.

You usually only need email_address, provider and the two passwords. Every host, port, username and sent-folder is filled in from the provider's preset, and letting the preset do it is the only reliable way to get iCloud right (see below). Supply hosts yourself only when your server is non-standard — or when you are on generic_imap, which infers nothing.

Note: From an agent or the CLI, use the create_mailbox MCP tool — it takes a single password and the same host/port fields. See MCP Tools.

Supported providers

Call GET /mail/providers for the live list — it returns exactly these values, so you never have to hard-code them.

::table
Provider | IMAP host | SMTP host | IMAP port | SMTP port | Sent folder
zoho | imap.zoho.com | smtp.zoho.com | 993 | 465 | Sent
gmail | imap.gmail.com | smtp.gmail.com | 993 | 465 | [Gmail]/Sent Mail
google_workspace | imap.gmail.com | smtp.gmail.com | 993 | 465 | [Gmail]/Sent Mail
outlook | outlook.office365.com | smtp.office365.com | 993 | 587 | Sent Items
icloud | imap.mail.me.com | smtp.mail.me.com | 993 | 587 | Sent Messages
generic_imap | (you supply) | (you supply) | 993 | 587 | Sent

All five named providers require an app-specific password. generic_imap does not assume one.

iCloud needs two different usernames

iCloud is the one provider where the two protocols disagree, and it is the most common reason an iCloud connection fails:

IMAP username — the part before the @ (e.g. jane)
SMTP username — the full address (e.g. jane@icloud.com)

Let the preset handle this by omitting both usernames. Sending the full address for both will fail on IMAP.

Two more iCloud limits worth knowing: you may hold at most 25 app passwords, and changing your Apple Account password revokes every one of them at once — including the one SpiderMail is using.

Fastmail — connect it as `generic_imap`

"provider": "fastmail" is rejected. Fastmail is deliberately not a preset: its Basic tier has no IMAP or SMTP access and cannot create app passwords, so a preset would promise a connection most Fastmail plans cannot make.

On a plan that does include IMAP/SMTP, Fastmail works — connect it explicitly:

::table
Field | Value
provider | generic_imap
imap_host | imap.fastmail.com
imap_port | 993
smtp_host | smtp.fastmail.com
smtp_port | 465
sent folder | Sent

You will need a Fastmail app password. GET /mail/providers advertises this under the generic_imap entry's routed_providers — providers that work but are not preset values of their own.

How TLS is chosen for sending

SpiderMail picks the SMTP encryption mode from the port, so set the right port for your provider:

::table
SMTP port | Mode | Notes
465 | SSL/TLS | Implicit TLS from connect. Used by the Zoho, Gmail and Google Workspace presets.
587 | STARTTLS | Connection upgrades to TLS. Used by the Outlook and iCloud presets.
other | plain | Not recommended.

If you let the preset choose the port, this is already correct for your provider.

Test the connection

Always verify a new mailbox before relying on it. This checks IMAP and SMTP independently:

curl -X POST "https://spideriq.ai/api/v1/mail/mailboxes/alice@yourcompany.com/test" \
  -H "Authorization: Bearer $TOKEN"
# → { "email_address": "...", "imap_ok": true, "smtp_ok": true }

If either is false, the response carries the specific error (imap_error / smtp_error):

::table
Symptom | Likely cause | Fix
imap_ok / smtp_ok false, "auth failed" | Using the normal password with 2FA on | Create and use an app-specific password
"connection refused" / timeout | Wrong host or port | Re-check against the table above
smtp send works, no inbound mail | IMAP wrong or mailbox inactive | Re-test; confirm is_active is true

Warning: Storing the wrong encryption credentials shows up as silent "invalid credentials" later. If a previously working mailbox starts failing, re-run the test endpoint first — it isolates IMAP vs SMTP for you.

Next steps

Manage your mailboxes — list, update, set defaults, delete.
Send your first email.
See the full Mailbox API.