Quickstart

This quickstart connects an existing mailbox to SpiderMail and sends your first email — about five minutes end to end. You will need a mailbox you can log into over IMAP/SMTP (a Zoho, Google Workspace, or Outlook account) and a SpiderMail API token.

Tip: If you do not have a token yet, see Authentication — the fastest path is spideriq auth request --email you@yourcompany.com. Throughout this manual, $TOKEN is your client_id:api_key:api_secret bearer token.

1. Connect a mailbox

Register the mailbox with its IMAP and SMTP settings. Use an app-specific password where your provider supports one (Google Workspace and Outlook require it; Zoho recommends it).

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": "zoho",
    "imap_host": "imap.zoho.com",
    "imap_username": "alice@yourcompany.com",
    "imap_password": "APP_PASSWORD",
    "smtp_host": "smtp.zoho.com",
    "smtp_username": "alice@yourcompany.com",
    "smtp_password": "APP_PASSWORD"
  }'

Passwords are encrypted at rest immediately and never returned by the API. See Connecting a Mailbox for per-provider host/port settings.

2. Confirm it connects

Before you rely on a mailbox, test that SpiderMail can reach both servers:

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 imap_ok or smtp_ok is false, the response includes the error — usually a wrong host/port or a password that needs to be an app password.

3. Send your first email

Sending is asynchronous. You submit a job and get a job_id back right away; the worker delivers it over SMTP.

curl -X POST "https://spideriq.ai/api/v1/jobs/spiderMail/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "action": "send",
      "from_email": "alice@yourcompany.com",
      "to": ["bob@example.com"],
      "subject": "Hello from SpiderMail",
      "body_text": "Hi Bob,\n\nThis is my first SpiderMail send.\n\n— Alice"
    }
  }'
# → { "job_id": "...", "status": "processing", ... }

4. Check the result

Poll the job until it completes:

curl "https://spideriq.ai/api/v1/jobs/JOB_ID/results" \
  -H "Authorization: Bearer $TOKEN"
# → { "status": "completed", "data": { "message_id": "<...>", "sent_at": "..." } }

A completed status with a message_id means it was handed to your SMTP server. See Sending, Replying & Forwarding for replies and forwards.

5. Read your inbox

The background poller ingests new inbound mail every few minutes. Once it has run, list the inbox:

curl "https://spideriq.ai/api/v1/mail/inbox?email=alice@yourcompany.com&format=yaml" \
  -H "Authorization: Bearer $TOKEN"

The format=yaml option returns clean, low-token YAML instead of JSON — the default for AI agents. See Reading Your Inbox.

Prefer the CLI or an agent?

Everything above is also available without curl:

# CLI — read surface
spideriq mail mailboxes
spideriq mail list alice@yourcompany.com --unread

For sending and full automation from Claude, Cursor, or another agent, wire up the MCP tools — create_mailbox, send_email, get_inbox, and more.

Next steps

1. Read the Core Concepts to understand mailboxes, threads, and the read-vs-send split.

2. Set up Templates for consistent signatures and branding.

3. Connect an agent in Build with AI Agents.