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.

The examples come in three flavors — pick your tab. curl talks to the API directly, TypeScript uses the @spideriq/core SDK, and CLI uses the spideriq command.

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).

# tab:curl
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"
  }'

// tab:TypeScript
import { createClient } from "@spideriq/core";

const client = createClient({ token: process.env.SPIDERIQ_TOKEN });

await client.createMailbox({
  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.

# tab:curl
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"
    }
  }'

// tab:TypeScript
const job = await client.submitJob("spiderMail", {
  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",
});
console.log(job.job_id);

4. Check the result

Poll the job until it completes:

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

// tab:TypeScript
const result = await client.getJobResults(job.job_id);
console.log(result.status); // "completed"

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. Use format=yaml for clean, low-token output — the default for AI agents.

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

// tab:TypeScript
const inbox = await client.getInbox({ mailbox: "alice@yourcompany.com" });
console.log(inbox.messages);

# tab:CLI
spideriq mail list alice@yourcompany.com --format yaml

See Reading Your Inbox.

Next steps

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

2. Build a real agent in the Cookbooks — auto-reply, triage, personalized sending.

3. Connect an agent in Build with AI Agents, or wire up your MCP client.