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

# Update inbox members

> Add or remove team members and user groups on an inbox.

Use this endpoint to manage who has access to an inbox. You can add and remove team members by email, and assign or unassign user groups by ID, in the same request.

This endpoint changes inbox membership only. It does not create users, invite them to your team, or remove them from your team.

> [!NOTE]
>
> Get the `inbox_id` from [`GET /v1/inboxes`](https://developers.heymarket.com/api-reference/inboxes) and user group IDs from [`POST /v1/user-groups`](https://developers.heymarket.com/api-reference/user-groups).

Emails and group IDs that do not match anything in your team do not fail the request. They are returned in the `*_not_found` arrays of the response so you can correct them.


## OpenAPI

````yaml api-reference/openapi/heymarket-openapi-3.1.2.yaml POST /v1/inbox/update_members
openapi: 3.1.2
info:
  contact:
    email: help@heymarket.com
    name: API Support
    url: https://heymarket.com
  description: >
    Welcome to Heymarket’s API! Many users access Heymarket via the web app,
    mobile apps, or one of the out-of-the-box platform integrations.

    However, much of Heymarket’s functionality can also be accessed via the API.

    The flexibility and scalability of the API makes it an excellent choice for
    integrating Heymarket into existing applications.


    This documentation provides details on: available authentication methods,
    endpoints that are available and error message information.


    If you want to get right to the action, download the collection to start
    performing calls from Postman or other similar software.


    All valid HTTP request and response bodies are encoded in JSON. For security
    purposes API requests must be made over HTTPS. Calls made over plain HTTP or
    without authentication will fail.


    Base URL: https://api.heymarket.com


    # Rate Limit

    The Heymarket API has a rate limit of 500 requests per minute. Exceeding the
    rate limit will result in responses with a 429 status code.


    # Request IDs

    Each API request has an associated request identifier. You can find this
    value in the response headers, under `X-Request-Id`.

    If you need to contact us about a specific request, providing the request
    identifier will ensure the fastest possible resolution.


    # Webhooks

    You can read more about [getting started with
    webhooks](https://help.heymarket.com/hc/en-us/articles/4416494130701-Getting-Started-with-Webhooks)
    from our articles collection.


    # Additional Admin APIs
        For more information about additional Admin APIs, please contact us at <help@heymarket.com>.
  license:
    name: Heymarket
    url: https://heymarket.com/legal
  termsOfService: https://heymarket.com/tos
  title: Heymarket API
  version: '1.0'
servers:
  - url: https://api.heymarket.com
security: []
tags:
  - name: Inboxes
    description: >
      The `Inbox` object represents a read only view of the team's inbox(es) in
      Heymarket.


      Any API requests that deal with message sending or scheduling will require
      an inbox ID as a parameter.


      #### The Inbox object


      | Attributes |
      Description                                                           |

      | ---------- |
      --------------------------------------------------------------------- |

      | `id`       | Unique identifier for the
      object                                      |

      | `name`    | Name of the
      inbox                                                     |

      | `team`     | Unique identifier for your
      team                                        |

      | `members`  | Unique identifier for your team members who have access to
      the inbox |

      | `phones`   | Heymarket phone number(s) associated with the
      inbox                    |
  - name: Users
    description: >
      The `User` object represents a team user in Heymarket.


      #### The User object


      | Attributes         |
      Description                                                   |

      | ------------------ |
      ------------------------------------------------------------- |

      | `id`               | Unique identifier for the
      object                              |

      | `name`             | Name of the
      user                                              |

      | `email`            | Email address of the
      user                                     |

      | `phone`            | Phone number of the
      user                                      |

      | `role_id`          | Unique identifier of the role of the user within
      the team     |

      | `team_id`          | Unique identifier for the team the user belongs
      to            |

      | `created_at`       | Creation date of the team
      user                                |

      | `updated_at`       | Last updated date of the team
      user                            |

      | `user_created_at`  | Creation date of the base
      user                                |

      | `user_updated_at`  | Last updated date of the base
      user                            |
  - name: User Groups
    description: >
      The `User Group` object represents a named group of team users in
      Heymarket.


      Groups are created and their membership managed in the Heymarket web app.
      They are used to

      scope objects such as lists and templates, and to address several
      teammates at once.


      #### The User Group object


      | Attributes    |
      Description                                                        |

      | ------------- |
      ------------------------------------------------------------------ |

      | `id`          | Unique identifier for the
      object                                   |

      | `name`        | Name of the
      group                                                  |

      | `description` | Description of the group. Omitted when the group has
      none          |

      | `member_ids`  | Unique identifiers of the group's
      members                          |

      | `members`     | The group's members, as `User`
      objects                             |
  - name: Team
    description: >
      The `Team` object represents a read only view of the team in Heymarket.


      #### The Team object


      | Attributes |
      Description                                                           |

      | ---------- |
      --------------------------------------------------------------------- |

      | `id`       | Unique identifier for the
      object                                      |

      | `name`    | Name of the
      team                                                     |

      | `list_size` | List size limit

      | `members`  | Unique identifiers for the users who have access to the
      team as well as their role within the team|
  - name: Contacts
    description: >
      The `Contact` object is a Heymarket contact. The contacts in Heymarket are
      used for storing information such as name, phone number, and email
      address. Contacts also store custom fields which can be used for search,
      list creation, and merge tokens while sending messages.


      #### The Contact object


      | Attributes         |
      Description                                                               
      |

      | ------------------ |
      --------------------------------------------------------------------------
      |

      | `id`               | Unique identifier for the
      object                                           |

      | `display_name`     | Display name, usually a combination of first and
      last name                 |

      | `first`            | First
      name                                                                 |

      | `last`             | Last
      name                                                                  |

      | `email`            | Email
      address                                                              |

      | `phone`            | Phone
      number                                                               |

      | `custom`           | Custom fields with value if present, only lists
      contact field ID and value |

      | `team_id`          | Unique identifier for your Heymarket
      team                                  |

      | `creator_id`       | Unique identifier for the user who created the
      contact, same as the member ID returned by Get
      Inboxes                        |

      | `shared`           | Boolean value for whether the contact is shared
      with team members          |

      | `created`          | Creation
      date                                                              |

      | `updated`          | Last updated
      date                                                          |

      | `rev`              | Last revision
      number                                                       |

      | `op`               | Operation
      performed                                                        |

      | `assigned_user_id` | Contact Owner
      ID                                                           |

      | `tags`             | Array of up to 5 `tag_id`
      objects                                                         |

      | `is_opted_out`     | Is this contact opted out of
      messaging?                                    |
  - name: Conversations
    description: The `Conversation` object represents a messaging thread in Heymarket.
  - name: Lists
    description: >
      The `List` object in Heymarket is used for organizing multiple phone
      numbers. You can send a single message to a list, the contacts will never
      see each other and can reply privately. Lists are also used as a source of
      contacts for your campaigns.


      #### The List object


      | Attributes   | Description                                         |

      | ------------ | --------------------------------------------------- |

      | `id`         | Unique identifier for the object                    |

      | `name`       | List name                                           |

      | `local_id`   | Client provided unique identifier for the object    |

      | `targets`    | Object containing multiple `ListTarget` objects     |

      | `team_id`    | Unique identifier for your Heymarket team            |

      | `creator_id` | Unique identifier for the user who created the list |

      | `shared`     | If the list is shared with team
      members                    |

      | `created`    | Creation date                                       |

      | `updated`    | Last updated date                                   |

      | `rev`        | Last revision number                                |

      | `op`         | Operation
      performed                                        |


      The `targets` object is a light weight representation of a contact.
      `phone` is used as a key and it has name fields as optional attributes
      which will be used as a merge token during message sending if there is no
      real Heymarket contact available for this phone number.


      #### The ListTarget object


      | Attributes | Description             |

      | ---------- | ----------------------- |

      | `f`        | First name (if available) |

      | `l`        | Last name (if available)  |
  - name: Templates
    description: >
      The `Template` object in Heymarket is a pre-defined message with text and
      media. Templates can also contain merge tokens which will insert the
      appropriate custom field values when sending the message. The main body of
      the template is stored in the `content` attribute.


      #### The Template object


      | Attributes   | Description                                         |

      | ------------ | --------------------------------------------------- |

      | `id`         | Unique identifier for the object                    |

      | `name`       | Template name                                       |

      | `local_id`   | Client provided unique identifier for the object    |

      | `content`    | Object representing template content                |

      | `team_id`    | Unique identifier for your Heymarket team            |

      | `creator_id` | Unique identifier for the user who created the template,
      same as the member ID returned by Get Inboxes |

      | `shared`     | If the template is shared with team
      members                |

      | `created`    | Creation date                                       |

      | `updated`    | Last updated date                                   |

      | `rev`        | Last revision number                                |

      | `op`         | Operation
      performed                                        |


      #### The Content object


      | Attributes | Description                     |

      | ---------- | ------------------------------- |

      | `text`     | Message text                    |

      | `gallery`  | Array of `GalleryEntry` objects |
  - name: Messages
    description: >
      The `Messages` API is a powerful Heymarket feature. With it you can send
      messages to individual contacts or a list of contacts.

      It has all the features of Heymarket's native clients, including sending
      messages from a template, sending media, and inserting merge tokens.
  - name: Schedule
    description: >-
      With the `Scheduling` API you can schedule a message to be sent to an
      individual contact or to a list.
  - name: Surveys
    description: >-
      Ask your customers a set of standardized questions to quickly understand
      their experience with your company.
  - name: Tags
    description: |
      The `Tag` object in Heymarket.
      #### The Tag object
      | Attributes   | Description                                         |
      | ------------ | --------------------------------------------------- |
      | `id`         | Unique identifier for the object                    |
      | `tag`        | Tag name                                            |
      | `color`      | Color                                               |
      | `team_id`    | Unique identifier for your Heymarket team           |
      | `created`    | Creation date                                       |
      | `updated`    | Last updated date                                   |
      | `rev`        | Last revision number                                |
  - name: Links
    description: >
      The `Link` object represents a tracked short URL owned by your team.


      Link tracking must be enabled for your team to use these endpoints.
      Requests from teams without the

      link tracking feature return `403` with the message
      `link_tracking_not_available`.


      All link operations are scoped to the team identified by your API
      credentials — links belonging to

      other teams cannot be read, updated, or deleted, and lookups for them
      return `404`.


      #### The Link object


      | Attributes | Description |

      | ---------- | ----------- |

      | `id` | Unique identifier for the object |

      | `short_code` | Code segment of the short URL |

      | `short_url` | Full short URL to include in messages |

      | `original_url` | Destination URL the short link redirects to |

      | `team_id` | Unique identifier for your team |

      | `target` | Target the link is attributed to (optional) |

      | `conversation_id` | Conversation the link is attributed to (optional) |

      | `broadcast_id` | Broadcast the link is attributed to (optional) |

      | `campaign_step_id` | Campaign step the link is attributed to (optional)
      |

      | `template_id` | Template the link is attributed to (optional) |

      | `last_visited_at` | Timestamp of the most recent click (optional) |

      | `created_at` | Creation date |
  - name: Webhooks
    description: Events Heymarket sends to webhook URLs configured for a team.
paths:
  /v1/inbox/update_members:
    post:
      tags:
        - Inboxes
      summary: Update Inbox Members
      description: >
        Add users to an inbox and remove users from it, by email, and assign or
        unassign user

        groups by id. Only inbox membership changes: no user is created, invited
        to the team, or

        removed from the team, and no group or its members are changed.


        Emails are matched case-insensitively, ignoring surrounding spaces. Each
        email is handled

        on its own, so one unknown email does not fail the others:


        - An email of a current team member is added to, or removed from, the
        inbox. Adding an
          existing inbox member, or removing a team member who is not in the inbox, changes nothing.
        - An email with a pending invite to your team is added as a pending
        inbox invite and
          appears in `invited_emails`. The user joins the inbox when they accept the team invite.
          Removing such an email cancels the pending inbox invite.
        - Any other email is returned in `add_emails_not_found` or
        `remove_emails_not_found`.


        User groups are passed by id (see `/v1/user-groups`). Every member of an
        assigned group

        gets access to the inbox; that access is updated in the background
        shortly after the

        request, and follows the group's membership from then on. Unassigning a
        group removes the

        access it gave, but a user who is also a direct member of the inbox
        keeps access, and

        removing a direct member who also belongs to an assigned group leaves
        their group access

        in place. Group ids are handled like emails, each on its own: an id that
        is not a user

        group on your team is returned in `add_group_ids_not_found` or

        `remove_group_ids_not_found`, and the rest of the request is still
        applied. Adding a

        group that is already assigned, or removing a group of yours that is not
        assigned,

        changes nothing. Adding groups requires a plan with user groups;
        removing them does not.


        Send requests for the same inbox one at a time. Two requests for one
        inbox that run at

        the same moment can overwrite each other's changes.


        If members were removed but their conversations, scheduled messages and
        campaigns in the

        inbox could not be reassigned, the request still succeeds and the
        response carries an

        `errors` entry with the code `reassignment_failed`.


        The response always carries the inbox as it stands after the request.


        #### Request body attributes


        | Attributes | Description |

        | --- | --- |

        | `inbox_id` | **integer (required)** <br> The inbox to update. |

        | `add_emails` | **array of strings (optional)** <br> Emails to add to
        the inbox. At most 500 distinct emails. |

        | `remove_emails` | **array of strings (optional)** <br> Emails to
        remove from the inbox. At most 500 distinct emails. |

        | `add_group_ids` | **array of integers (optional)** <br> Ids of user
        groups to assign to the inbox. At most 200 distinct ids. |

        | `remove_group_ids` | **array of integers (optional)** <br> Ids of user
        groups to unassign from the inbox. At most 200 distinct ids. |


        At least one email or group id is required across the four lists. The
        same email cannot

        appear in both email lists, and the same id cannot appear in both group
        lists.


        #### Example request body

        ```json

            {
              "inbox_id": 1614,
              "add_emails": ["alice@example.com"],
              "remove_emails": ["bob@example.com"],
              "add_group_ids": [12],
              "remove_group_ids": [15]
            }

        ```
      operationId: updateInboxMembers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - inbox_id
              properties:
                inbox_id:
                  type: integer
                add_emails:
                  items:
                    type: string
                  type: array
                remove_emails:
                  items:
                    type: string
                  type: array
                add_group_ids:
                  items:
                    type: integer
                  type: array
                remove_group_ids:
                  items:
                    type: integer
                  type: array
              type: object
      responses:
        '200':
          description: >-
            the updated inbox, plus any emails and group ids that matched
            nothing on the team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/doc.InboxMembersUpdateResp'
        '400':
          description: >-
            bad_data, invalid_inbox_id, too_many_emails, conflicting_emails,
            invalid_group_ids, too_many_group_ids, conflicting_group_ids,
            no_changes_provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/doc.V2ErrorResp'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: >-
            plan_upgrade_required, when `add_group_ids` is sent and the team's
            plan does not include user groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/doc.V2ErrorResp'
        '404':
          description: inbox_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/doc.V2ErrorResp'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        default:
          $ref: '#/components/responses/DefaultServerError'
      security:
        - ApiSecretJwtAuth: []
        - LegacyApiKeyAuth: []
components:
  schemas:
    doc.InboxMembersUpdateResp:
      required:
        - inbox
      properties:
        inbox:
          $ref: '#/components/schemas/doc.InboxWithMembers'
        add_emails_not_found:
          description: >-
            Emails from `add_emails` that matched no team member and no pending
            team invite. Omitted when empty.
          items:
            type: string
          type: array
        remove_emails_not_found:
          description: >-
            Emails from `remove_emails` that matched no team member and no
            pending inbox invite. Omitted when empty.
          items:
            type: string
          type: array
        add_group_ids_not_found:
          description: >-
            Ids from `add_group_ids` that are not a user group on the team.
            Omitted when empty.
          items:
            type: integer
          type: array
        remove_group_ids_not_found:
          description: >-
            Ids from `remove_group_ids` that are neither assigned to the inbox
            nor a user group on the team. Omitted when empty.
          items:
            type: integer
          type: array
        errors:
          description: >-
            Problems that did not stop the membership change, such as
            `reassignment_failed`. Omitted when empty.
          items:
            $ref: '#/components/schemas/doc.V2ErrorResp'
          type: array
      type: object
    doc.V2ErrorResp:
      type: object
      required:
        - error
        - details
      properties:
        error:
          type: string
          description: Machine-readable snake_case error code. Branch on this field.
          example: invalid_filter
        details:
          type: string
          description: >-
            Human-readable explanation of the failure. Do not parse; it may
            change without notice.
          example: 'unsupported filter: name'
    doc.InboxWithMembers:
      properties:
        id:
          type: integer
        name:
          type: string
        team_id:
          type: integer
        phone:
          type: string
        phones:
          items:
            type: string
          type: array
        forward_number:
          type: string
        member_emails:
          description: Emails of the users who are direct members of the inbox.
          items:
            type: string
          type: array
        invited_emails:
          description: Emails with a pending invite to the inbox.
          items:
            type: string
          type: array
        group_ids:
          description: >-
            Ids of the user groups assigned to the inbox. Always present; empty
            when none.
          items:
            type: integer
          type: array
        members:
          description: >-
            The direct members of the inbox. Users who have access only through
            a group are not listed.
          items:
            properties:
              id:
                type: integer
              name:
                type: string
              role_id:
                type: integer
              email:
                type: string
            type: object
          type: array
        business_hours:
          type: object
        created_at:
          format: date-time
          type: string
      type: object
  responses:
    UnauthorizedError:
      description: Authentication credentials were missing or invalid.
      content:
        text/plain:
          schema:
            type: string
          examples:
            response:
              value: Unauthorized
    TooManyRequestsError:
      description: The request exceeded the API rate limit.
      content:
        text/plain:
          schema:
            type: string
          examples:
            response:
              value: too many requests
    DefaultServerError:
      description: Unexpected server error.
      content:
        text/plain:
          schema:
            type: string
          examples:
            response:
              value: error
  securitySchemes:
    ApiSecretJwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Recommended authentication for new integrations. Generate a short-lived
        JWT from your API Secret ID and API Secret Key, then pass the signed JWT
        as a bearer token in the `Authorization` header.


        API Secret credentials are available in the Heymarket app under Settings
        > Integrations > API. The Secret Key is shown only when it is generated,
        so copy and store it securely before closing the dialog.


        Use the following JWT values:


        ```json

        {
          "alg": "HS256",
          "typ": "JWT"
        }

        ```


        ```text

        {
          "iss": "YOUR_API_SECRET_ID",
          "iat": CURRENT_UNIX_TIMESTAMP
        }

        ```


        Replace `CURRENT_UNIX_TIMESTAMP` with the current Unix timestamp in
        seconds when generating the token.


        Sign the JWT with HMAC-SHA256 using this signing secret:


        ```text

        YOUR_API_SECRET_ID||YOUR_API_SECRET_KEY

        ```


        Send the signed JWT as a bearer token:


        ```text

        Authorization: Bearer YOUR_SIGNED_JWT

        ```


        Tokens expire 5 minutes after the `iat` timestamp. Generate a new JWT
        per request, or cache it briefly for less than 5 minutes. Generate JWTs
        only from trusted server-side code; do not expose the API Secret Key in
        browser, mobile, or other client-side code.
    LegacyApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: Team API key
      description: >-
        Legacy authentication for existing integrations. Provide the Heymarket
        team API key as a bearer token in the `Authorization` header.


        ```text

        Authorization: Bearer YOUR_API_KEY

        ```


        API key authentication is planned for deprecation. New integrations
        should use API Secret JWT authentication.

````

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