Create an inbox (idempotent on requested username)

POSThttps://myagentmail.com/v1/inboxes

Requires tenant master or workspace master key.

Username allocation

If username is set and your tenant already has an inbox at username@domain, returns that inbox (HTTP 200, body contains existed: true). The call is idempotent — safe to retry.
Otherwise tries to create username@domain. If the global username is taken by another tenant, falls back to username1, username2, … through username99. The actual allocated username is in the response body.
Pass ?strict=true to disable auto-fallback. With strict mode, a global collision returns HTTP 409 with the conflicting resource info instead of suffixing.

IMAP/SMTP credentials — apiKey and imapPassword — are only returned on first creation, never on idempotent returns.

Query parameters

strict

boolean

When `true`, the request fails with `409 USERNAME_TAKEN` if the requested `username@domain` is already taken by another tenant. When omitted (default), we auto-fallback to `username1`, `username2`, etc.

Request body

Content-Type: application/json

`username` string	Lowercase alphanumeric + `.-_`. Auto-generated from the tenant name if omitted. No tenant-id suffix is appended — collisions are resolved via sequential numeric fallback (e.g. `scout`, `scout1`, `scout2`).
`displayName` string
`domain` string	Defaults to myagentmail.com
`workspaceId` string	(Tenant master only) target workspace. Defaults to the tenant's default workspace. format: uuid

Responses

200application/jsonIdempotent return — your tenant already has an inbox at the requested `username@domain`. `existed: true` is set on the body. `apiKey` and `imapPassword` are NOT re-issued.

`id` string	format: uuid
`email` string	Current primary outbound address — may be a custom-domain alias.
`canonicalEmail` string	Stable identity used for IMAP/SMTP auth. Never changes after creation.
`username` string
`domain` string
`displayName` string
`workspaceId` string	format: uuid
`addresses` object[]
`address` string
`isPrimary` boolean
`imapPassword` string	Only returned on creation and GET /inboxes/{id}. Stored plaintext so IMAP clients can log in.
`imap` object
`host` string
`port` integer
`tls` boolean
`username` string
`password` string
`smtp` object
`host` string
`port` integer
`starttls` boolean
`username` string
`password` string
`createdAt` string	format: date-time

201application/jsonNewly created. `apiKey` and `imapPassword` are returned once — store them now.

`id` string	format: uuid
`email` string	Current primary outbound address — may be a custom-domain alias.
`canonicalEmail` string	Stable identity used for IMAP/SMTP auth. Never changes after creation.
`username` string
`domain` string
`displayName` string
`workspaceId` string	format: uuid
`addresses` object[]
`address` string
`isPrimary` boolean
`imapPassword` string	Only returned on creation and GET /inboxes/{id}. Stored plaintext so IMAP clients can log in.
`imap` object
`host` string
`port` integer
`tls` boolean
`username` string
`password` string
`smtp` object
`host` string
`port` integer
`starttls` boolean
`username` string
`password` string
`createdAt` string	format: date-time

403application/jsonPlan limit reached

`error` required string
`code` string

409application/json`USERNAME_TAKEN` — only returned when `?strict=true` is set and `username@domain` is taken globally. Body includes `requestedUsername`, `attemptedUsername`, and `domain` for single-round-trip recovery. Default behavior auto-falls back without ever returning 409.

`error` required string
`code` string

Authentication

Send your API key in the X-API-Key header (or Authorization: Bearer <key>). Any prefix accepted by this endpoint — tk_, wk_, ak_, or sa_ — is documented in the key prefix table.

Request

import { MyAgentMail } from "myagentmail";

const client = new MyAgentMail({ apiKey: process.env.MYAGENTMAIL_API_KEY! });

// POST /v1/inboxes
const result = await client.request("post", "/v1/inboxes", { body: {
  "username": "string",
  "displayName": "string",
  "domain": "string",
  "workspaceId": "00000000-0000-0000-0000-000000000000"
} });

Example response · 200

{
  "id": "00000000-0000-0000-0000-000000000000",
  "email": "[email protected]",
  "canonicalEmail": "[email protected]",
  "username": "string",
  "domain": "string",
  "displayName": "string",
  "workspaceId": "00000000-0000-0000-0000-000000000000",
  "addresses": [
    {
      "address": "[email protected]",
      "isPrimary": false
    }
  ],
  "imapPassword": "string",
  "imap": {
    "host": "imap.myagentmail.com",
    "port": 993,
    "tls": false,
    "username": "string",
    "password": "string"
  },
  "smtp": {
    "host": "smtp.myagentmail.com",
    "port": 587,
    "starttls": false,
    "username": "string",
    "password": "string"
  },
  "createdAt": "2026-05-01T08:11:44.739Z"
}