Email Communication

Your agent communicates primarily through email. This guide explains how the email system works.

Email address

Every agent gets an email address based on your tier:

• Free tier: {name}-{hash}@tinyfat.com (e.g., [email protected])
• Tiny tier ($5/mo): Custom alias like [email protected]

This is a real email address. You can send to it from any email client. Your agent’s replies come from the same address.

The email flow

You → [email protected]
         ↓
   Resend webhook → TinyFat platform
         ↓
   Validate sender (allowed_senders)
         ↓
   Enqueue job to sandbox-queue
         ↓
   Agent runs one turn
         ↓
   Agent writes to /data/outbox/email/
         ↓
   Platform sends email via Resend
         ↓
You ← [email protected]

Response time

• First message: 10-30 seconds (container cold start + agent thinking)
• Subsequent: 5-20 seconds (depends on task complexity)

The agent runs one “turn” per email — it processes your message, uses tools if needed, and responds.

Allowed senders

Only whitelisted email addresses can trigger your agent. This prevents:

• Spam triggering expensive API calls
• Unauthorized access to your agent

Managing allowed senders

In the dashboard under Settings → Allowed Senders:

• Exact match: [email protected] — only this address
• Domain wildcard: @company.com — anyone at that domain

Your email is automatically added when you create the agent.

Caution

Be careful with domain wildcards. Adding @gmail.com would allow any Gmail user to email your agent.

Email commands

Send commands in the subject line or at the start of the email body:

Command	Effect
/clear	Start a fresh session
/resume	List recent sessions
/resume abc1	Resume specific session by hash
/compact	Compress context to save tokens
/model	Show current model
/model haiku	Switch to Haiku (fastest, ~$0.001/msg)
/model sonnet	Switch to Sonnet (balanced, ~$0.015/msg)
/model opus	Switch to Opus (most capable, ~$0.075/msg)

Example: Switching models

To: [email protected]
Subject: /model sonnet
Body: (empty or anything)

Response:

✓ Switched to **sonnet** (Sonnet (balanced))

This will apply to your next message.

Email threading

Responses maintain proper threading:

• In-Reply-To header links to your original message
• References header includes the full thread chain
• Gmail, Outlook, Apple Mail all group replies correctly

Note

If threading breaks, check that your email client is using standard headers. Some corporate email systems modify headers in ways that break threading.

Session footer

Every response includes a footer showing session info:

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

Part	Meaning
buddy:a1b2	Agent name and session hash
↑38	Input tokens (your message)
↓5.0k	Output tokens (response)
R663k	Cache read tokens
W37k	Cache write tokens
$0.687	Cost for this turn
18.7%/200k	Context usage (% of limit)
claude-haiku-4-5	Model used

Use the session hash with /resume a1b2 to continue that specific conversation.

Attachments

You can send attachments to your agent:

• Images: Agent can view and analyze (PNG, JPG, GIF, WebP)
• Documents: Agent can read text content (PDF, TXT, MD)
• Files: Agent can process data (JSON, CSV, etc.)

Attachments are stored temporarily during the turn and available in the agent’s workspace.

Tip

For large files, consider uploading to a URL and sending the link instead.

Outgoing email features

Your agent can send emails with:

• Multiple recipients: To, CC fields
• Threading: Proper reply headers
• Attachments: Files from the workspace

See Email JSON Reference for the full format.

Delivery issues

Email not received

1. Check spam/junk folder
2. Verify allowed senders includes your address
3. Check dashboard for job status/errors

Agent didn’t respond

1. Check if sender is whitelisted
2. Look for errors in dashboard
3. Verify API key is configured

Response went to spam

Add [email protected] to your contacts or mark as “not spam”.

Next steps

• Email JSON Reference — Full outbox format
• Troubleshooting — Common issues
• Dashboard — Managing your agent