Email JSON Reference

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

Full schema

{
  "to": ["recipient@example.com"],
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "subject": "Email subject line",
  "body": "Plain text email body",
  "in_reply_to": "<message-id@example.com>",
  "references": "<msg1@example.com> <msg2@example.com>",
  "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": ["one@example.com", "two@example.com"]

At least one recipient is required.

cc (optional)

Array of CC (carbon copy) recipients.

"cc": ["manager@example.com"]

bcc (optional)

Array of BCC (blind carbon copy) recipients.

"bcc": ["archive@example.com"]

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": "<CAG+abc123@mail.gmail.com>"

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": "<CAG+first@mail.gmail.com> <CAG+second@mail.gmail.com>"

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_content (optional)

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

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": ["user@example.com"],
  "subject": "Re: Question",
  "body": "The answer is 42.",
  "in_reply_to": "<original-msg-id@example.com>",
  "status": "pending"
}

Email with attachment

{
  "to": ["user@example.com"],
  "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": ["team@example.com"],
  "cc": ["manager@example.com", "archive@example.com"],
  "subject": "Weekly Update",
  "body": "Here's the weekly summary...",
  "status": "pending"
}

Threaded reply

{
  "to": ["user@example.com"],
  "subject": "Re: Project Discussion",
  "body": "Good point! Let me address each item...",
  "in_reply_to": "<CAG+latest@mail.gmail.com>",
  "references": "<CAG+first@mail.gmail.com> <CAG+second@mail.gmail.com> <CAG+latest@mail.gmail.com>",
  "status": "pending"
}

File naming

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

• Timestamp: 1704379200000.json
• Timestamp + suffix: 1704379200000-reply.json

Processing

After the agent’s turn:

1. Platform lists /data/outbox/email/
2. Reads each .json file
3. Sends via Resend API
4. Moves file to sent/ or failed/

Files are processed in creation order.

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.