---
title: "Bulk create email users"
method: POST
path: "/v1/email-users/bulk"
tags: ["Email Users"]
---

# Bulk create email users

`POST /v1/email-users/bulk`

## Request

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

Create up to 500 email users on one domain in a single call.

**Asynchronous, like `POST /v1/email-users`:** the whole batch is
enqueued as one job and the response is a job receipt
(`data.job_id`, `data.status: "pending"`, `data.users_count`), not the
created mailboxes. Poll `GET /v1/jobs/{job_id}`, then list the mailboxes
with `GET /v1/email-users?filter[domain]={domain}`.

`domain` in the body is the domain **name**, not the domain id.

## Request body

- BulkCreateRequest
  - `domain` string, required: Domain name shared by all users in this request (e.g. "example.com"). All users in a single bulk request must be on the same domain — send one request per domain if creating users across multiple.
  - `users` BulkCreateUserItem[], required
    - `username` string, required: Local part of the email address (before the @)
    - `name` string: Display name. Auto-derived from username (e.g. "john.doe" → "John Doe") if omitted.
    - `password` string: Optional password. Auto-generated if omitted.
    - `footer` string: Optional email signature footer.

## Response `200`

Batch accepted and queued. The body is a job receipt, not the
created mailboxes.

- BulkCreateResponse: Job receipt for a queued bulk mailbox creation. The mailboxes do not exist yet when this is returned.
  - `data` object
    - `job_id` string: Poll `GET /v1/jobs/{job_id}` for completion.
    - `status` 'pending': Always `pending` — the batch has been enqueued, not executed.
    - `domain` string: Domain name the mailboxes are being created on.
    - `users_count` integer: Number of mailboxes accepted for creation.
    - `message` string
    - `prewarmed_billing` object, nullable: Present only when the domain is pre-warmed; describes the $3/addr seat charge.
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `401`: Authentication required or token invalid

---

[API](https://skmtc.dev/winnr/apis/winnr-api.md) · [All operations](https://skmtc.dev/winnr/apis/winnr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/winnr/apis/winnr-api/revisions/a4f960beb1eb?raw)