Inboxes

Create an inbox (idempotent on requested username)

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.

post/v1/inboxes

Request

  • Base URL: https://anjal.app
  • URL: https://anjal.app/v1/inboxes
  • Auth: API key in header X-API-Key

Query parameters

strictboolean

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

usernamestring

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).

displayNamestring
domainstring

Defaults to anjal.app

workspaceIdstring uuid

(Tenant master only) target workspace. Defaults to the tenant's default workspace.

Response

Idempotent 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.

idstring uuid
emailstring

Current primary outbound address — may be a custom-domain alias.

canonicalEmailstring

Stable identity used for IMAP/SMTP auth. Never changes after creation.

usernamestring
domainstring
displayNamestring
workspaceIdstring uuid
imapPasswordstring

Only returned on creation and GET /inboxes/{id}. Stored plaintext so IMAP clients can log in.

createdAtstring date-time

Example response

{
  "email": "scout-abc123@delegated.cc",
  "canonicalEmail": "scout-abc123-10deac42@send.anjal.app",
  "addresses": [
    {
      "address": "scout-abc123@delegated.cc"
    }
  ],
  "imap": {
    "host": "imap.anjal.app",
    "port": 993
  },
  "smtp": {
    "host": "smtp.anjal.app",
    "port": 587
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.