Email JSON Reference

This is the complete reference for the email JSON format used in the outbox pattern.

Full schema

{
  "to": ["[email protected]"],
  "cc": ["[email protected]"],
  "bcc": ["[email protected]"],
  "subject": "Email subject line",
  "body": "Plain text email body",
  "in_reply_to": "<[email protected]>",
  "references": "<[email protected]> <[email protected]>",
  "attachments": [
    {
      "filename": "report.pdf",
      "content": "base64-encoded-content"
    }
  ],
  "log": "attachment",
  "log_content": "Custom log content",
  "status": "pending"
}

Field reference

to (required)

Array of recipient email addresses.

"to": ["[email protected]", "[email protected]"]

At least one recipient is required.

cc (optional)

Array of CC (carbon copy) recipients.

"cc": ["[email protected]"]

bcc (optional)

Array of BCC (blind carbon copy) recipients.

"bcc": ["[email protected]"]

subject (required)

Email subject line. Plain text string.

"subject": "Re: Your question about APIs"

For replies, include “Re: ” prefix to maintain threading.

body (required)

Email body. Plain text string.

"body": "Hello!\n\nHere's the information you requested.\n\nBest,\nYour Agent"

Use \n for newlines. HTML is not supported.

in_reply_to (optional)

Message-ID of the email being replied to. Used for threading.

"in_reply_to": "<[email protected]>"

Include angle brackets. This header tells email clients which message you’re replying to.

references (optional)

Space-separated list of Message-IDs in the thread. Used for threading.

"references": "<[email protected]> <[email protected]>"

Should include all Message-IDs in the thread, oldest first.

attachments (optional)

Array of file attachments.

"attachments": [
  {
    "filename": "report.pdf",
    "content": "JVBERi0xLjQKJeLjz9..."
  },
  {
    "filename": "data.csv",
    "content": "bmFtZSxhZ2UKQWxpY2..."
  }
]

Each attachment has:

• filename — Name shown to recipient
• content — Base64-encoded file contents

log (optional)

Controls session log inclusion. Values:

• "attachment" — Include log as attachment
• "inline" — Include log in email body
• "none" — No log (default)

"log": "attachment"

log_content (optional)

Custom content for the log (when log is set).

"log_content": "Session summary: discussed API integration..."

status (required)

Always set to "pending" when creating the file.

"status": "pending"

The platform updates this to "sent" or "failed" after processing.

Examples

Simple reply

{
  "to": ["[email protected]"],
  "subject": "Re: Question",
  "body": "The answer is 42.",
  "in_reply_to": "<[email protected]>",
  "status": "pending"
}

Email with attachment

{
  "to": ["[email protected]"],
  "subject": "Report attached",
  "body": "Please find the report attached.\n\nLet me know if you have questions.",
  "attachments": [
    {
      "filename": "monthly-report.pdf",
      "content": "JVBERi0xLjQK..."
    }
  ],
  "status": "pending"
}

Multi-recipient with CC

{
  "to": ["[email protected]"],
  "cc": ["[email protected]", "[email protected]"],
  "subject": "Weekly Update",
  "body": "Here's the weekly summary...",
  "status": "pending"
}

Threaded reply

{
  "to": ["[email protected]"],
  "subject": "Re: Project Discussion",
  "body": "Good point! Let me address each item...",
  "in_reply_to": "<[email protected]>",
  "references": "<[email protected]> <[email protected]> <[email protected]>",
  "status": "pending"
}

File naming

Save JSON files to /data/outbox/email/ with unique names:

• Timestamp: 1704379200000.json
• UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890.json
• Sequential: email-001.json

The agent typically uses timestamps.

Processing

After the agent exits:

1. Queue worker lists /data/outbox/email/
2. Reads each .json file
3. Appends session footer to body
4. Sends via Resend API
5. Moves file to sent/ or failed/

Files are processed in creation order.

After sending

sent/

{
  ...original fields...,
  "status": "sent",
  "sent_at": "2026-01-04T12:00:00Z",
  "resend_id": "re_abc123"
}

failed/

{
  ...original fields...,
  "status": "failed",
  "error": "Invalid recipient: bad@invalid",
  "failed_at": "2026-01-04T12:00:00Z"
}

Session footer

The platform automatically appends:

---
[buddy:a1b2 | ↑38 ↓5.0k R663k W37k $0.687 18.7%/200k | claude-haiku-4-5]

You don’t need to add this — it’s injected during processing.

Tips

Encoding attachments

import base64

with open('report.pdf', 'rb') as f:
    content = base64.b64encode(f.read()).decode('utf-8')

Preserving threading

Always include in_reply_to and references when replying. The platform provides these in the input message.

Multiple emails

You can write multiple files to the outbox. They’ll all be sent.