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.
Where your provider supports it, create an app-specific password and use that instead of your normal password. Google Workspace and Outlook require app passwords when 2FA is on; Zoho recommends one.
Have the provider's IMAP/SMTP host and port ready (typical values below).

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, google_workspace, or outlook. display_name is the friendly "from" name recipients see. If you omit imap_port it defaults to 993; smtp_port defaults to 587.

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.

Typical provider settings

These are the standard values for each supported provider. Confirm against your provider's current documentation if a connection test fails.

::table
Provider | IMAP host | SMTP host | IMAP port | SMTP port
zoho | imap.zoho.com | smtp.zoho.com | 993 | 587
google_workspace | imap.gmail.com | smtp.gmail.com | 993 | 587
outlook | outlook.office365.com | smtp.office365.com | 993 | 587

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
587 | STARTTLS | Most common; connection upgrades to TLS. The default.
465 | SSL/TLS | Implicit TLS from connect.
other | plain | Not recommended.

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.