Email Users

Create email user

Create a new email user (mailbox) on a domain you already own.

This is asynchronous. The mailbox is created on the mail server by a background worker, so a successful call returns 200 with a job receipt (data.job_id, data.status: "pending") — not the created mailbox. Poll GET /v1/jobs/{job_id} until status is completed, then fetch the mailbox with GET /v1/email-users?filter[domain]={domain} (or GET /v1/email-users/{user_id}) to read its password and SMTP/IMAP connection details.

domain is the domain name (talent.example.com), not the domain id. See CreateEmailUserRequest.

Validation (unknown domain, duplicate address, plan limits, per-domain caps, password length) happens synchronously and returns 400 before anything is enqueued — so a 200 means the request was accepted, and the job can still fail later for mail-server reasons.

See Asynchronous endpoints in the introduction for how to reconcile a timed-out request without creating duplicate mailboxes.

post/v1/email-users

Request

  • Base URL: https://api.winnr.app
  • URL: https://api.winnr.app/v1/email-users
  • Auth: HTTP bearer

Request body

usernamestring required

Local part of the email address (before the @).

domainstring required

The domain name, exactly as it appears in name on the domain resource — e.g. talent.example.com. This is not the domain id.

Passing a domain id here fails with 400 validation_error / Domain {value} not found in this account, even when that id is a real domain on the account.

Rule of thumb: domain ids are used only in the path of /v1/domains/{domain_id}/... routes. Request bodies that refer to a domain — including this one and BulkCreateRequest — take the domain name.

namestring

Display name used in the From header. Derived from username if omitted.

passwordstring

Optional mailbox password; a strong one is generated when omitted. Minimum 8 characters. Read the generated password back from GET /v1/email-users/{user_id} once the job completes.

Example request

{
  "username": "jordan",
  "domain": "talent.example.com",
  "name": "Jordan Reed"
}

Response

Mailbox creation accepted and queued. The body is a job receipt, not the mailbox.

Example response

{
  "data": {
    "job_id": "job_e80f588c889b4091",
    "email": "jordan@talent.example.com",
    "username": "jordan",
    "domain": "talent.example.com",
    "name": "Jordan Reed",
    "message": "Email user jordan@talent.example.com creation queued"
  }
}

Changes

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