Attachments

SpiderMail handles attachments in both directions: you can attach files to a send, and inbound attachments are automatically processed so their text is searchable and readable without downloading the raw file — useful when an agent needs to act on a PDF or spreadsheet someone emailed in.

Sending attachments

Add an attachments array to the send payload. Each attachment is the file's bytes, base64-encoded, with a filename. The MIME type is optional — SpiderMail detects it from the content if you omit it.

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": "The proposal you asked for",
      "body_text": "Hi Bob, the proposal is attached.",
      "attachments": [
        { "filename": "proposal.pdf", "content_base64": "JVBERi0xLjQK...", "mime_type": "application/pdf" }
      ]
    }
  }'

Each attachment object takes:

• filename (string, required) — the name the recipient sees.

• content_base64 (string, required) — the file contents, base64-encoded.

• mime_type (string, optional) — auto-detected from the content if omitted.

Tip: When attaching from the dashboard compose window, the practical limits are 25 MB per file and 50 MB per message. Keep individual files modest — large base64 payloads slow the request down.

Inbound attachment processing

When the poller ingests a message that has attachments, SpiderMail extracts the text from each one and stores it alongside the message. You get:

• A preview — roughly the first 1,500 characters of extracted text.

• The full extracted text — inline for smaller files, or a retrieval key for large ones.

• Metadata — filename, MIME type, size, detected type, page count for PDFs, and whether OCR was used.

This means an agent can read what a PDF or spreadsheet says without ever downloading the binary.

::table
Type | How text is extracted
PDF | Text layer, with OCR fallback for scans
DOCX / office docs | Converted and extracted
Images | OCR
CSV / spreadsheets | Parsed to text
TXT / code files | Read directly

Files up to 50 MB are processed. There is no AI summary step — the extracted text is handed to the consuming agent, which summarizes on its own if needed.

Reading attachments back

Inbound attachment summaries come back with the message by default. Fetching a message includes them:

curl "https://spideriq.ai/api/v1/mail/messages/5678?include_attachments=true&format=yaml" \
  -H "Authorization: Bearer $TOKEN"

Set include_attachments=false to skip them when you only need the message body. Each summary carries the filename, mime_type, size_bytes, detected type, preview, page/row counts, and ocr_used.

Note: Attachment text is extracted in the background by the worker, not in your request path — so a freshly arrived message may briefly show the attachment metadata before its extracted text is ready.

Next steps

1. Back to Sending, Replying & Forwarding.

2. Search across messages and their attachment text.

3. Attachment fields in the API Reference.