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

# Create or update an identity mailbox

> Create or update an IMAP mailbox for a specific identity so mailbox setup can be automated over API. Programmatic setup currently supports IMAP credentials only.

    > **Required scope:** `ALL`
    >
    > **Rate limit:** 30 requests per minute



## OpenAPI

````yaml https://openapi.enginy.ai/definitions.json post /v1/identities/{identityId}/mailboxes
openapi: 3.1.0
info:
  title: Enginy API
  version: 1.0.0
  description: Public API for Enginy platform
servers:
  - url: https://openapi.enginy.ai
    description: Configured server
security: []
tags:
  - name: AI Variables
    description: >-
      Manage AI variables and discover the entity fields you can reference in
      prompts and entity requests.
  - name: Inbox
    description: >-
      Inbox endpoints for listing contact threads, reading thread messages,
      managing tags, and sending manual replies.
  - name: Workflows
    description: >-
      Build, validate, publish, run, and inspect advanced (graph) workflows,
      plus the block/condition catalog needed to author a workflow plan.
paths:
  /v1/identities/{identityId}/mailboxes:
    post:
      tags:
        - Identities
      summary: Create or update an identity mailbox
      description: >-
        Create or update an IMAP mailbox for a specific identity so mailbox
        setup can be automated over API. Programmatic setup currently supports
        IMAP credentials only.

            > **Required scope:** `ALL`
            >
            > **Rate limit:** 30 requests per minute
      parameters:
        - schema:
            type: string
            description: The identity ID that will own the mailbox.
          required: true
          description: The identity ID that will own the mailbox.
          name: identityId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Mailbox email address
                provider:
                  type: string
                  enum:
                    - imap
                  description: >-
                    Mailbox provider. Programmatic setup currently supports IMAP
                    mailboxes only.
                credentials:
                  type: object
                  properties:
                    password:
                      type: string
                      minLength: 1
                      description: Mailbox password or app password
                    imapHost:
                      type: string
                      minLength: 1
                      description: IMAP hostname
                    imapPort:
                      type: integer
                      minimum: 1
                      maximum: 65535
                      description: IMAP port
                    smtpHost:
                      type: string
                      minLength: 1
                      description: SMTP hostname
                    smtpPort:
                      type: integer
                      minimum: 1
                      maximum: 65535
                      description: SMTP port
                  required:
                    - password
                    - imapHost
                    - imapPort
                    - smtpHost
                    - smtpPort
                makePrimary:
                  type: boolean
                  default: false
                  description: >-
                    When true, also updates the identity primary email to this
                    mailbox address.
              required:
                - email
                - provider
                - credentials
      responses:
        '200':
          description: Mailbox updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: number
                        description: Unique identifier for the mailbox
                      identityId:
                        type: number
                        description: Identity ID that owns the mailbox
                      email:
                        type: string
                        description: Mailbox email address
                      provider:
                        type: string
                        enum:
                          - google
                          - microsoft
                          - imap
                          - unknown
                        description: >-
                          Mailbox provider inferred from the configured
                          credentials
                      isPrimary:
                        type: boolean
                        description: >-
                          Whether this mailbox matches the identity primary
                          email field
                      emailCredentialsExpired:
                        type: boolean
                        description: Whether the stored mailbox credentials are expired
                      healthStatus:
                        type: string
                        enum:
                          - healthy
                          - credentials_expired
                          - missing_credentials
                        description: High-level mailbox credential health
                      warmup:
                        type: object
                        properties:
                          enabled:
                            type: boolean
                            description: Whether warmup is configured for this mailbox
                          mailboxId:
                            type:
                              - number
                              - 'null'
                            description: Warmup mailbox identifier when configured
                        required:
                          - enabled
                          - mailboxId
                    required:
                      - id
                      - identityId
                      - email
                      - provider
                      - isPrimary
                      - emailCredentialsExpired
                      - healthStatus
                      - warmup
                required:
                  - status
                  - message
                  - data
        '201':
          description: Mailbox created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: number
                        description: Unique identifier for the mailbox
                      identityId:
                        type: number
                        description: Identity ID that owns the mailbox
                      email:
                        type: string
                        description: Mailbox email address
                      provider:
                        type: string
                        enum:
                          - google
                          - microsoft
                          - imap
                          - unknown
                        description: >-
                          Mailbox provider inferred from the configured
                          credentials
                      isPrimary:
                        type: boolean
                        description: >-
                          Whether this mailbox matches the identity primary
                          email field
                      emailCredentialsExpired:
                        type: boolean
                        description: Whether the stored mailbox credentials are expired
                      healthStatus:
                        type: string
                        enum:
                          - healthy
                          - credentials_expired
                          - missing_credentials
                        description: High-level mailbox credential health
                      warmup:
                        type: object
                        properties:
                          enabled:
                            type: boolean
                            description: Whether warmup is configured for this mailbox
                          mailboxId:
                            type:
                              - number
                              - 'null'
                            description: Warmup mailbox identifier when configured
                        required:
                          - enabled
                          - mailboxId
                    required:
                      - id
                      - identityId
                      - email
                      - provider
                      - isPrimary
                      - emailCredentialsExpired
                      - healthStatus
                      - warmup
                required:
                  - status
                  - message
                  - data
        '404':
          description: Identity not found
        '409':
          description: Mailbox already belongs to another active identity
        '422':
          description: >-
            Mailbox credentials are invalid or the identity exceeded mailbox
            limits
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````