Send Personalized Email

This cookbook sends personalized, one-to-one emails to a list of recipients through your own mailbox — each rendered from a reusable template, each sent as its own job, with delivery confirmed. It's how an agent runs a small, genuine outreach or notification batch without a bulk-mail platform.

Note: SpiderMail sends one-to-one through your connected mailbox at your provider's normal rate limits — it is not a mass-mailing or cold-blast tool. Use it for real, personalized messages (onboarding nudges, follow-ups, notifications), and respect your provider's sending limits.

What you'll build

1. A template once, with {{ first_name }} / {{ topic }} variables.

2. A loop that submits one personalized send per recipient.

3. Delivery polling that reports which sends landed.

Prerequisites

• A connected mailbox and a token.

• Python 3 with requests.

1. Create the template

curl -X POST "https://spideriq.ai/api/v1/mail/templates" \
  -H "Authorization: Bearer $SPIDERIQ_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "intro-outreach",
    "template_type": "full",
    "html_source": "<p>Hi {{ first_name }},</p><p>I noticed your work on {{ topic }} and wanted to reach out.</p><p>— Alice</p>"
  }'

Preview it with sample values before you rely on it — see Email Templates.

2. Send the batch

Because SpiderMail renders an outgoing message with the mailbox's default template, set the template on the mailbox and pass per-recipient values through body_text. Here we keep it explicit and send a personalized plain-text + HTML body per recipient:

import os, time, requests

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

recipients = [
    {"email": "sam@acme.com",  "first_name": "Sam",  "topic": "edge caching"},
    {"email": "lee@globex.com","first_name": "Lee",  "topic": "API design"},
]

jobs = []
for r in recipients:
    body = (f"Hi {r['first_name']},\n\nI noticed your work on {r['topic']} "
            f"and wanted to reach out.\n\n— Alice")
    job = requests.post(f"{BASE}/jobs/spiderMail/submit", headers=HEAD, json={"payload": {
        "action": "send",
        "from_email": MAILBOX,
        "to": [r["email"]],
        "subject": f"Quick note on {r['topic']}",
        "body_text": body,
    }}).json()
    jobs.append((r["email"], job["job_id"]))

# 3. Confirm delivery
for email, job_id in jobs:
    while True:
        res = requests.get(f"{BASE}/jobs/{job_id}/results", headers=HEAD).json()
        if res["status"] in ("completed", "failed"):
            print(f"{email}: {res['status']}")
            break
        time.sleep(2)

Run it

python send_batch.py
# sam@acme.com: completed
# lee@globex.com: completed

Each recipient gets a distinct, personalized email from your mailbox, and you get a per-recipient delivery result.

Make it better

• Brand it once. Set the template as the mailbox default with template_variables for the sender block, so every send carries your signature automatically.

• Polish the copy. Run each body through AI Compose before sending.

• Watch your limits. A failed result carries the real SMTP error (e.g. rate limiting) verbatim — back off and retry rather than hammering your provider.

Tip: One send = one job = one billable unit. Submit the batch, collect the job_ids, then poll them together (as above) rather than blocking on each send serially.

Next steps

1. Email Templates — variables, types, and mailbox defaults.

2. Sending reference — the full job payload.

3. Auto-Reply Agent — handle the replies that come back.