Email

Send and receive email from your agent's own @agentworkspace.dev address.

Overview

Each agent can have its own email address (e.g. my-agent@agentworkspace.dev). Enable email from the dashboard settings tab, choose a handle, and your agent can immediately send and receive email via the API. Up to 2 email-enabled agents per account.

Endpoints

List threads

GET /api/v1/email

Returns a paginated list of email threads for this agent's inbox.

Query params: limit (default 50, max 100), offset (default 0), labels (filter by label, e.g. "sent" or "received")

Response:

{
  "threads": [
    {
      "thread_id": "th_abc123",
      "subject": "Hello",
      "preview": "Hey, just wanted to...",
      "updated_at": "2026-03-14T12:00:00Z",
      "message_count": 3
    }
  ]
}

Get thread

GET /api/v1/email/:threadId

Returns a single thread with all its messages.

Response:

{
  "thread": {
    "thread_id": "th_abc123",
    "subject": "Hello",
    "messages": [
      {
        "message_id": "msg_xyz",
        "from": { "address": "sender@example.com" },
        "to": ["agent@agentworkspace.dev"],
        "subject": "Hello",
        "text": "Message body",
        "created_at": "2026-03-14T12:00:00Z"
      }
    ]
  }
}

Send email

POST /api/v1/email

Send a new email from your agent's address.

Body:

{
  "to": ["recipient@example.com"],
  "subject": "Hello from my agent",
  "text": "Plain text body",
  "html": "<p>Optional HTML body</p>",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"]
}

Required: to (array of emails), subject.

Reply to thread

POST /api/v1/email/:threadId/reply

Reply to the last message in a thread.

Body:

{
  "text": "Reply body",
  "html": "<p>Optional HTML</p>",
  "to": ["override-recipient@example.com"]
}

Mark thread as read

POST /api/v1/email/:threadId/read

Marks all unread messages in the thread as read. No request body needed.

Response:

{
  "marked": 2
}

Field Constraints

• to / cc / bcc: arrays of valid email addresses
• subject: 1–500 characters
• text / html: up to 100,000 characters

Notes

• Email must be enabled from the dashboard before these endpoints work (returns 403 otherwise).
• Agent uses the same API key for email as for calendar and docs — no separate credentials needed.
• Email data is stored by AgentMail, not in AgentWorkspace. Each user's data is isolated in its own pod.