> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taimly.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Создать ящик

> Создаёт ящик. Тело запроса необязательно: без него адрес и домен выбираются случайно.

- `domain` не указан — домен выбирается случайно из [списка доменов](/api-reference/mail/list-domains) отдельно для каждого ящика.
- `name` не указан — генерируется адрес вида `anna.smith42`.

Письма принимаются только на созданные ящики, на остальные адреса домена — отклоняются.



## OpenAPI

````yaml /openapi.json post /api/mail/mailboxes
openapi: 3.1.0
info:
  title: Taimly API
  version: 1.3.0
  description: >-
    API Taimly: проверка доставляемости email (Spam Check) и временные почты для
    приёма писем.
servers:
  - url: https://taimly.net
    description: Production
security:
  - BearerAuth: []
paths:
  /api/mail/mailboxes:
    post:
      tags:
        - Временные почты
      summary: Создать ящик
      description: >-
        Создаёт ящик. Тело запроса необязательно: без него адрес и домен
        выбираются случайно.


        - `domain` не указан — домен выбирается случайно из [списка
        доменов](/api-reference/mail/list-domains) отдельно для каждого ящика.

        - `name` не указан — генерируется адрес вида `anna.smith42`.


        Письма принимаются только на созданные ящики, на остальные адреса домена
        — отклоняются.
      operationId: createMailbox
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailboxRequest'
            example:
              name: anna.smith
              domain: example.com
      responses:
        '201':
          description: Ящик создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailbox'
              example:
                id: 3fa1c2d4e5b60718
                address: anna.smith42@example.com
                domain: example.com
                created_at: '2026-10-26T12:00:00Z'
                pinned: false
                messages: 0
                unread: 0
                last_message_at: null
        '400':
          description: Ошибка в запросе
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unknown_domain:
                  summary: Домен недоступен
                  value:
                    detail: 'Unknown domain. Available: example.com, example.net'
                bad_name:
                  summary: Недопустимое имя
                  value:
                    detail: >-
                      Invalid name: 1-64 chars, a-z 0-9 . _ -, must start and
                      end with a letter or digit
                reserved:
                  summary: Зарезервированное имя
                  value:
                    detail: This name is reserved
                not_json:
                  summary: Тело не JSON
                  value:
                    detail: Body must be JSON
        '401':
          description: Невалидный или отсутствующий API-ключ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Invalid or missing API key
        '409':
          description: Адрес уже занят
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Address already taken
        '503':
          description: Нет доступных доменов
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: No domains available
components:
  schemas:
    CreateMailboxRequest:
      type: object
      properties:
        name:
          type: string
          description: >-
            Имя до `@`: 1–64 символа `a-z 0-9 . _ -`, начинается и заканчивается
            буквой или цифрой. Приводится к нижнему регистру. Нельзя:
            `postmaster`, `abuse`, `hostmaster`, `webmaster`, `mailer-daemon`,
            `root`. Не указано — генерируется случайно.
          example: anna.smith
        domain:
          type: string
          description: >-
            Домен из [списка доменов](/api-reference/mail/list-domains). Не
            указан — выбирается случайно.
          example: example.com
    Mailbox:
      type: object
      properties:
        id:
          type: string
          description: Идентификатор ящика
        address:
          type: string
          format: email
          description: Адрес ящика
        domain:
          type: string
          description: Домен ящика
        created_at:
          type: string
          format: date-time
          description: Когда создан (UTC)
        pinned:
          type: boolean
          description: Показывается ли в списке на сайте
        messages:
          type: integer
          description: Всего писем
        unread:
          type: integer
          description: Непрочитанных писем
        last_message_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Когда пришло последнее письмо (UTC)
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Описание ошибки
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API-ключ. Передаётся в заголовке `Authorization: Bearer <ваш_ключ>`.
        Ключ выдаётся администратором Taimly.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.