API Reference

{
  "name": "research-agent",
  "domain": "agentmail.usetransactional.com"
}

{
  "data": {
    "id": "mbx_abc123",
    "address": "research-agent@agentmail.usetransactional.com",
    "name": "research-agent",
    "domain": "agentmail.usetransactional.com",
    "createdAt": "2025-01-10T12:00:00Z"
  }
}

{
  "from": "research-agent@agentmail.usetransactional.com",
  "to": ["user@example.com"],
  "cc": [],
  "bcc": [],
  "subject": "Research Complete",
  "html": "<p>Findings attached.</p>",
  "text": "Findings attached.",
  "attachments": [
    {
      "filename": "report.pdf",
      "content": "<base64>",
      "contentType": "application/pdf"
    }
  ],
  "headers": {},
  "tags": ["research"],
  "scheduledAt": null
}

{
  "data": {
    "id": "msg_xyz789",
    "status": "queued",
    "from": "research-agent@agentmail.usetransactional.com",
    "to": ["user@example.com"],
    "subject": "Research Complete"
  }
}

{
  "from": "research-agent@agentmail.usetransactional.com",
  "messages": [
    {
      "to": "alice@example.com",
      "subject": "Your Report",
      "html": "<p>Hi Alice...</p>"
    }
  ]
}

{
  "html": "<p>Updated findings.</p>",
  "text": "Updated findings.",
  "attachments": []
}

{
  "to": ["colleague@example.com"],
  "html": "<p>FYI</p>"
}

{
  "data": [
    {
      "id": "msg_abc123",
      "from": "user@example.com",
      "to": ["agent@agentmail.usetransactional.com"],
      "subject": "Re: Research",
      "textPreview": "Thanks for the update...",
      "read": false,
      "labels": ["inbox"],
      "threadId": "thd_xyz789",
      "attachmentCount": 0,
      "receivedAt": "2025-01-10T14:30:00Z"
    }
  ],
  "meta": { "total": 142, "limit": 25, "offset": 0 }
}

{
  "messageIds": ["msg_abc123", "msg_def456"]
}

{
  "messageIds": ["msg_abc123"]
}

{
  "messageIds": ["msg_abc123"]
}

{
  "name": "needs-review",
  "color": "#3B82F6"
}

{
  "labels": ["important", "follow-up"]
}

{
  "url": "https://yourapp.com/webhooks/agent-email",
  "events": ["message.received", "message.bounced"],
  "secret": "whsec_optional_custom_secret"
}

{
  "domain": "mail.yourdomain.com"
}

{
  "error": {
    "code": "MAILBOX_NOT_FOUND",
    "message": "Mailbox mbx_abc123 does not exist."
  }
}