Sending, Replying & Forwarding

Sending, replying, and forwarding all go through one endpoint — POST /jobs/spiderMail/submit — with an action of send, reply, or forward. Sending is asynchronous: you submit the job, get a job_id immediately, and the SpiderMail worker delivers it over your mailbox's SMTP server. You then poll the job for the delivery result.

The send job

Every send is a job wrapped in a payload. from_email must be a mailbox you have connected, and body_text is always required.

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"],
      "cc": ["manager@yourcompany.com"],
      "subject": "Quick question about your services",
      "body_text": "Hi Bob,\n\nI noticed your team is hiring...\n\n— Alice"
    }
  }'
# → { "job_id": "...", "status": "processing" }

Each action has its own required fields:

::table
Action | What it does | Required fields
send | A brand-new email | from_email, to, subject, body_text
reply | Respond in an existing thread | from_email, reply_to_message_id, body_text
forward | Pass an existing message to new recipients | from_email, reply_to_message_id, to, body_text

Poll for the result

The submit call returns before the email is delivered. Poll the job until it reaches a terminal state:

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 the email was accepted by your SMTP server and stored in your Sent folder inside SpiderMail. A failed status carries the real error (for example SMTPAuthenticationError) so you can fix the cause.

Replying — threading is automatic

To reply, reference the message you are replying to by its SpiderMail message id. SpiderMail looks up the original, sets the In-Reply-To and References headers for you, and the reply threads correctly in the recipient's client.

curl -X POST "https://spideriq.ai/api/v1/jobs/spiderMail/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "action": "reply",
      "from_email": "alice@yourcompany.com",
      "reply_to_message_id": 1234,
      "body_text": "Thanks Bob — how does Thursday at 2pm look?",
      "reply_all": false
    }
  }'

Set reply_all to true to include the original recipients. You do not pass to or subject on a reply — SpiderMail derives them from the original message.

Forwarding

Forwarding takes both the original message id and new recipients:

curl -X POST "https://spideriq.ai/api/v1/jobs/spiderMail/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "action": "forward",
      "from_email": "alice@yourcompany.com",
      "reply_to_message_id": 1234,
      "to": ["legal@yourcompany.com"],
      "body_text": "FYI — can you review the terms in this thread?"
    }
  }'

Plain text, HTML, and Markdown

body_text is always required — it is the plain-text part every email carries. You have two ways to add rich formatting:

• Write Markdown in the body and SpiderMail renders professional HTML for the recipient automatically.

• Pass body_html directly for full control over the markup.

When both a text and an HTML part are present, the email is sent as multipart/alternative and the recipient's client picks the version it prefers — standard, well-behaved email.

# HTML control via body_html
-d '{ "payload": {
  "action": "send", "from_email": "alice@yourcompany.com",
  "to": ["bob@example.com"], "subject": "Welcome",
  "body_text": "Hi Bob, welcome aboard!",
  "body_html": "<p>Hi Bob,</p><p>Welcome <strong>aboard</strong>!</p>"
} }'

Sending from an agent

From an MCP-connected agent, use the send_email tool — same actions, same fields, no job wrapper:

send_email(action="reply", from_email="alice@yourcompany.com",
           reply_to_message_id=1234, body_text="Sounds good — Thursday works.")

The tool returns the job_id and a next_step hint. See MCP Tools.

Note: SpiderMail scans every outbound body for credentials (API keys, tokens, private keys) and blocks the send if it finds any, returning a security error instead of delivering. See Agent Security.

Next steps

1. Attach files to a send.

2. Use AI Compose to draft and polish a message.

3. Apply a template for a consistent signature.

4. Full payload reference: Job submission.