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

# Create a recipient



## OpenAPI

````yaml /inbound/api-reference/openapi.yaml put /users
openapi: 3.0.3
info:
  title: Inbound API
  description: |
    Manage domains for MailChannels Inbound.

    ### Rate Limits
    This API is limited to 100 queries per second, per customer.
    Queries that exceed this rate may be rejected with the
    `503 Service Temporarily Unavailable` HTTP response.
  version: 1.3.0
servers:
  - url: https://api.mailchannels.net/inbound/v1
security:
  - APIKeyHeader: []
tags:
  - name: Domains
  - name: Lists
  - name: Recipients
  - name: Login links
  - name: Reporting
  - name: Account
paths:
  /users:
    put:
      tags:
        - Recipients
      summary: Create a recipient
      parameters:
        - name: email_address
          in: query
          required: true
          description: The email address of the user to add
          schema:
            type: string
        - name: admin
          in: query
          required: true
          description: Flag to indicate if the user is a domain admin or a regular user
          schema:
            type: boolean
        - name: filter
          in: query
          required: false
          description: >
            Whether or not to filter mail for this recipient.  There are three
            valid values.


            * true - Filtering policy will be applied to messages intended for
            this recipient.
                     If this would exceed the protected-addresses limit, return an error.
            * false - Filtering policy will not be applied to messages intended
            for this recipient.

            * compute (default) - Filtering policy will be applied to messages
            intended for this recipient.
                                  If this would exceed the protected-addresses limit, filtering policy will
                                  not be applied, and no error will be returned.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
              - compute
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                list_entries:
                  description: safelist and blocklist entries to be added
                  type: object
                  properties:
                    blocklist:
                      type: array
                      items:
                        type: string
                    safelist:
                      type: array
                      items:
                        type: string
      responses:
        '200':
          description: >
            Returned in the case where the recipient already exists and in that
            case no changes

            will be made to the safe/block list entries.
        '201':
          description: |
            The recipient was created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipient:
                    $ref: '#/components/schemas/Recipient'
                  list_entries:
                    type: array
                    items:
                      $ref: '#/components/schemas/ListItem'
        '400':
          description: Returned when the email_address is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >
            Retuned when customer/API-key does not have the required privileges
            to make this request.

            Also returned when an account is created with filter = true and
            there is no room in the

            protected-addresses limit to filter mail for more recipients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Recipient:
      properties:
        email_address:
          type: string
          description: the email address of the user
        roles:
          type: array
          items:
            type: string
          description: array of roles the given user has
        filter:
          type: boolean
          description: >
            determines if policy should be applied to messages intended for this
            recipient
          nullable: true
      required:
        - email_address
        - roles
    ListItem:
      properties:
        item:
          type: string
          description: >-
            The value of this entry.  The meaning of this value depends on the
            item_type.
        item_type:
          type: string
          description: The item type.
        action:
          type: string
          description: Which list this entry is on, e.g. safelist or blocklist.
    ErrorResponse:
      required:
        - errors
      properties:
        code:
          type: integer
        message:
          type: string
        errors:
          type: array
          items:
            type: string
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````