SpiderMail

Auto-Reply Agent

This cookbook builds a working auto-reply agent: a script that finds unread mail in a connected mailbox, drafts a context-aware reply, and sends it back in the same thread. It runs end to end on SpiderMail's shipped API — about 40 lines of Python.

By the end you will have a loop that an agent SDR or a support bot can run on a schedule.

What you'll build

A script that, for each unread message:

  1. Reads the message (and its thread for context).

  2. Drafts a reply with AI Compose.

  3. Sends the reply — threading is automatic.

  4. Marks the original read so it isn't answered twice.

Prerequisites

  • A connected mailbox (here alice@yourcompany.com).

  • A SpiderMail token (client_id:api_key:api_secret) — see Authentication.

  • Python 3 with requests (pip install requests).

export SPIDERIQ_TOKEN="cli_xxx:key_xxx:secret_xxx"
export MAILBOX="alice@yourcompany.com"

The script

import os, time, requests

BASE = "https://spideriq.ai/api/v1"
HEAD = {"Authorization": f"Bearer {os.environ['SPIDERIQ_TOKEN']}"}
MAILBOX = os.environ["MAILBOX"]

def get(path, **params):
    return requests.get(f"{BASE}{path}", headers=HEAD, params=params).json()

def post(path, body):
    return requests.post(f"{BASE}{path}", headers=HEAD, json=body).json()

# 1. Find unread messages in the mailbox
inbox = get("/mail/inbox", email=MAILBOX, unread_only="true", limit=20)

for msg in inbox.get("messages", []):
    mid = msg["id"]
    full = get(f"/mail/messages/{mid}")          # opening marks it read

    # 2. Draft a reply with AI Compose
    draft = post("/mail/compose/assist", {
        "action": "write",
        "tone": "professional",
        "context": f"Reply to this email from {full['from_address']}:\n\n{full['body_text']}",
        "subject": full.get("subject", ""),
    })
    reply_text = draft.get("result") or draft.get("rendered_text") or draft["content"]

    # 3. Send the reply — In-Reply-To / References are set for you
    job = post("/jobs/spiderMail/submit", {"payload": {
        "action": "reply",
        "from_email": MAILBOX,
        "reply_to_message_id": mid,
        "body_text": reply_text,
    }})

    # 4. Poll for delivery
    job_id = job["job_id"]
    while True:
        res = get(f"/jobs/{job_id}/results")
        if res["status"] in ("completed", "failed"):
            print(f"msg {mid}: {res['status']}")
            break
        time.sleep(2)

Run it

python auto_reply.py
# msg 5821: completed
# msg 5822: completed

Each unread message gets a threaded reply, and because opening a message marks it read, a second run won't answer the same mail twice.

Warning: An auto-reply agent acts on untrusted email. SpiderMail's inbound scanner quarantines obvious prompt-injection, and the outbound credential blocker stops leaks — but keep a human in the loop for anything consequential, and never let the agent execute instructions found in a message body.

Make it production-ready

  • Schedule it. Run the script on a cron or a worker every few minutes; the inbound poller refreshes the mailbox between runs.

  • Label instead of replying blind. For triage-before-reply, see Triage & Label an Inbox.

  • Brand every reply. Attach a default template to the mailbox so every send carries your signature with zero per-message effort.

  • Filter what you answer. Apply a saved view (e.g. unread + label:lead) via ?view_id= so the loop only handles the mail you want.

Next steps

  1. Triage & Label an Inbox — classify before you act.

  2. Drive it from an MCP agent instead of a script.

  3. AI Compose reference — all the actions and tones.