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]>",
  "status": "pending"
}

Field reference

to (required)

Array of recipient email addresses.

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

subject (required)

Email subject line. String.

"subject": "Re: Your question about the project"

body (required)

Plain text email body. Supports newlines with \n.

"body": "Hello,\n\nThis is the first paragraph.\n\nThis is the second.\n\nBest,\nYour Agent"

status (required)

Must be "pending" for the outbox watcher to pick it up.

"status": "pending"

After processing:

• Sent emails: "status": "sent"
• Failed emails: "status": "failed" with "error" field

cc (optional)

Array of CC recipients.

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

bcc (optional)

Array of BCC recipients.

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

in_reply_to (optional)

Message-ID of the email being replied to. Enables threading.

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

references (optional)

Space-separated list of Message-IDs in the thread chain.

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

Examples

Simple email

{
  "to": ["[email protected]"],
  "subject": "Quick update",
  "body": "Just wanted to let you know the task is complete.",
  "status": "pending"
}

Reply with threading

{
  "to": ["[email protected]"],
  "subject": "Re: Project status",
  "body": "The project is on track. Here's the summary:\n\n- Task 1: Complete\n- Task 2: In progress\n- Task 3: Starting tomorrow",
  "in_reply_to": "<[email protected]>",
  "status": "pending"
}

Multiple recipients with CC

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

File naming

Any .json filename works. Recommended pattern:

{timestamp}-{description}.json

Examples:

• 1703808000-reply.json
• 1703808001-status-update.json
• response-to-john.json

Processing order

Files are processed in alphabetical order. Use timestamp prefixes for predictable ordering.

Error handling

Failed emails are moved to /data/outbox/failed/ with an error field:

{
  "to": ["invalid@"],
  "subject": "Test",
  "body": "Test body",
  "status": "failed",
  "error": "Invalid recipient email address"
}

Limits

• Recipients: Max 50 per email
• Subject: Max 998 characters
• Body: Max 10MB (plain text)
• Rate: ~100 emails/hour per agent