Hiver

Hiver Inbox API

The Inbox API from Hiver — 6 operation(s) for inbox.

GitHub OpenAPI

Operations 7

GET /inboxes List all the inboxes #
GET /inboxes/{inbox_id} Get an inbox by id #
GET /inboxes/{inbox_id}/users Get all users in the inbox #
GET /inboxes/{inbox_id}/users/search Search users in the inbox #
GET /inboxes/{inbox_id}/tags Get tags in the inbox #
POST /inboxes/{inbox_id}/tags Create tag in the inbox #
GET /inboxes/{inbox_id}/tags/search Search tags in the inbox #

Documentation

📖
Documentation
https://developer.hiverhq.com/hiver-api
📖
APIReference
https://developer.hiverhq.com/api-runner/hiverhq/hiver-api
📖
GettingStarted
https://help.hiverhq.com/hiver-api/hiver-api
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/hiver/refs/heads/main/authentication/hiver-authentication.yml
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/hiver/refs/heads/main/rate-limits/hiver-rate-limits.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/hiver/refs/heads/main/openapi/hiver-inbox-api-openapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/hiver/refs/heads/main/conventions/hiver-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/hiver/refs/heads/main/errors/hiver-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/hiver/refs/heads/main/data-model/hiver-data-model.yml
🔗
Lifecycle
https://raw.githubusercontent.com/api-evangelist/hiver/refs/heads/main/lifecycle/hiver-lifecycle.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/hiver-inbox-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

hiver-inbox-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: hiver-api Inbox API
  version: 1.0.0
servers:
- url: https://api2.hiverhq.com/v1
tags:
- name: Inbox
  description: ''
paths:
  /inboxes:
    get:
      tags:
      - Inbox
      summary: List all the inboxes
      description: List all the inboxes
      operationId: Inbox_inbox/list-all-the-inboxes
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          example: Bearer {token}
          description: ''
          default: ''
        description: ''
        example: Bearer {token}
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: ''
                    example:
                      results:
                      - id: '101'
                        display_name: Customer Support
                        channel_type: email
                        email: info@example.com
                        inbox_type: user
                        is_authorised: false
                        source_user:
                          id: '12323'
                          email: source@example.com
                        created_at: 1709036168
                        updated_at: 1709036168
                      pagination:
                        next_page: Gygskjhgkjythjjhkgjhgsdf=
                    properties:
                      results:
                        type: array
                        description: ''
                        example:
                        - id: '101'
                          display_name: Customer Support
                          channel_type: email
                          email: info@example.com
                          inbox_type: user
                          is_authorised: false
                          source_user:
                            id: '12323'
                            email: source@example.com
                          created_at: 1709036168
                          updated_at: 1709036168
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: ''
                              example: '101'
                            display_name:
                              type: string
                              description: ''
                              example: Customer Support
                            channel_type:
                              type: string
                              description: ''
                              example: email
                            email:
                              type: string
                              description: ''
                              example: info@example.com
                            inbox_type:
                              type: string
                              description: ''
                              example: user
                            is_authorised:
                              type: boolean
                              description: ''
                              example: false
                            source_user:
                              type: object
                              description: ''
                              example:
                                id: '12323'
                                email: source@example.com
                              properties:
                                id:
                                  type: string
                                  description: ''
                                  example: '12323'
                                email:
                                  type: string
                                  description: ''
                                  example: source@example.com
                            created_at:
                              type: number
                              description: ''
                              example: 1709036168
                            updated_at:
                              type: number
                              description: ''
                              example: 1709036168
                      pagination:
                        type: object
                        description: ''
                        example:
                          next_page: Gygskjhgkjythjjhkgjhgsdf=
                        properties:
                          next_page:
                            type: string
                            description: ''
                            example: Gygskjhgkjythjjhkgjhgsdf=
  /inboxes/{inbox_id}:
    get:
      tags:
      - Inbox
      summary: Get an inbox by id
      description: Get an Inbox by Id
      operationId: Inbox_inbox/get-an-inbox-by-id
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          type: integer
          example: ''
          description: ID of the inbox to get details
          default: ''
          format: int64
        description: ID of the inbox to get details
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          example: Bearer {token}
          description: ''
          default: ''
        description: ''
        example: Bearer {token}
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: ''
                    example:
                      id: '101'
                      display_name: Customer Support
                      channel_type: email
                      email: info@example.com
                      inbox_type: user
                      is_authorised: false
                      source_user:
                        id: '12323'
                        email: source@example.com
                      created_at: 1709036168
                      updated_at: 1709036168
                    properties:
                      id:
                        type: string
                        description: Id of the Inbox
                        example: '101'
                      display_name:
                        type: string
                        description: Name of the Inbox
                        example: Customer Support
                      channel_type:
                        type: string
                        description: Type of the channel
                        example: email
                      email:
                        type: string
                        description: Email address of the inbox
                        example: info@example.com
                        format: email
                      inbox_type:
                        type: string
                        description: Type of the authentication done for the inbox
                        example: user
                        format: string
                      is_authorised:
                        type: boolean
                        description: True if Hiver has access to user's mailbox, False otherwise. If false, the access could've been lost and need to reinstated.
                        example: false
                      source_user:
                        type: object
                        description: The user from whom the inbound emails are added.
                        example:
                          id: '12323'
                          email: source@example.com
                        properties:
                          id:
                            type: string
                            description: ''
                            example: '12323'
                          email:
                            type: string
                            description: ''
                            example: source@example.com
                      created_at:
                        type: integer
                        description: Creation timestamp
                        example: 1709036168
                      updated_at:
                        type: integer
                        description: Last update timestamp
                        example: 1709036168
  /inboxes/{inbox_id}/users:
    get:
      tags:
      - Inbox
      summary: Get all users in the inbox
      description: Get all users in the inbox
      operationId: Inbox_inbox/get-all-users-in-the-inbox
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          type: string
          example: '343'
          description: ID of inbox to get the user list for
          default: ''
        description: ID of inbox to get the user list for
        example: '343'
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          example: Bearer {token}
          description: ''
          default: ''
        description: ''
        example: Bearer {token}
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: ''
                    example:
                      results:
                      - id: '456342'
                        first_name: Phoebe
                        last_name: Buffay
                        email: p.buffay@friends.com
                        phone_number: '+19876543444'
                        is_joined: false
                      pagination:
                        next_page: Gygskjhgkjythjjhkgjhgsdf=
                    properties:
                      results:
                        type: array
                        description: ''
                        example:
                        - id: '456342'
                          first_name: Phoebe
                          last_name: Buffay
                          email: p.buffay@friends.com
                          phone_number: '+19876543444'
                          is_joined: false
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: ''
                              example: '456342'
                            first_name:
                              type: string
                              description: ''
                              example: Phoebe
                            last_name:
                              type: string
                              description: ''
                              example: Buffay
                            email:
                              type: string
                              description: ''
                              example: p.buffay@friends.com
                            phone_number:
                              type: string
                              description: ''
                              example: '+19876543444'
                            is_joined:
                              type: boolean
                              description: ''
                              example: false
                      pagination:
                        type: object
                        description: ''
                        example:
                          next_page: Gygskjhgkjythjjhkgjhgsdf=
                        properties:
                          next_page:
                            type: string
                            description: ''
                            example: Gygskjhgkjythjjhkgjhgsdf=
  /inboxes/{inbox_id}/users/search:
    get:
      tags:
      - Inbox
      summary: Search users in the inbox
      description: Search users in the inbox
      operationId: Inbox_inbox/search-users-in-the-inbox
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          type: string
          example: '343'
          description: ID of inbox to get the user list for
          default: ''
        description: ID of inbox to get the user list for
        example: '343'
      - name: email
        in: query
        required: true
        schema:
          type: string
          example: bob@example.com
          description: Email address to be searched for by exact match
          default: ''
        description: Email address to be searched for by exact match
        example: bob@example.com
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          example: Bearer {token}
          description: ''
          default: ''
        description: ''
        example: Bearer {token}
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: ''
                    example:
                      results:
                      - id: '456342'
                        first_name: Phoebe
                        last_name: Buffay
                        email: p.buffay@friends.com
                        phone_number: '+19876543444'
                        is_joined: false
                      pagination:
                        next_page: Gygskjhgkjythjjhkgjhgsdf=
                    properties:
                      results:
                        type: array
                        description: ''
                        example:
                        - id: '456342'
                          first_name: Phoebe
                          last_name: Buffay
                          email: p.buffay@friends.com
                          phone_number: '+19876543444'
                          is_joined: false
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: ''
                              example: '456342'
                            first_name:
                              type: string
                              description: ''
                              example: Phoebe
                            last_name:
                              type: string
                              description: ''
                              example: Buffay
                            email:
                              type: string
                              description: ''
                              example: p.buffay@friends.com
                            phone_number:
                              type: string
                              description: ''
                              example: '+19876543444'
                            is_joined:
                              type: boolean
                              description: ''
                              example: false
                      pagination:
                        type: object
                        description: ''
                        example:
                          next_page: Gygskjhgkjythjjhkgjhgsdf=
                        properties:
                          next_page:
                            type: string
                            description: ''
                            example: Gygskjhgkjythjjhkgjhgsdf=
  /inboxes/{inbox_id}/tags:
    get:
      tags:
      - Inbox
      summary: Get tags in the inbox
      description: Get tags in the inbox
      operationId: Inbox_inbox/get-tags-in-the-inbox
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          type: string
          example: '343'
          description: ID of inbox to get the user list for
          default: ''
        description: ID of inbox to get the user list for
        example: '343'
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          example: Bearer {token}
          description: ''
          default: ''
        description: ''
        example: Bearer {token}
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: ''
                    example:
                      results:
                      - id: '56789'
                        name: Priority
                        color_code: '#ce93d8'
                        type: user
                        created_at: 1708945347
                      pagination:
                        next_page: Gygskjhgkjythjjhkgjhgsdf=
                    properties:
                      results:
                        type: array
                        description: ''
                        example:
                        - id: '56789'
                          name: Priority
                          color_code: '#ce93d8'
                          type: user
                          created_at: 1708945347
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: ''
                              example: '56789'
                            name:
                              type: string
                              description: ''
                              example: Priority
                            color_code:
                              type: string
                              description: ''
                              example: '#ce93d8'
                            type:
                              type: string
                              description: ''
                              example: user
                            created_at:
                              type: number
                              description: ''
                              example: 1708945347
                      pagination:
                        type: object
                        description: ''
                        example:
                          next_page: Gygskjhgkjythjjhkgjhgsdf=
                        properties:
                          next_page:
                            type: string
                            description: ''
                            example: Gygskjhgkjythjjhkgjhgsdf=
    post:
      tags:
      - Inbox
      summary: Create tag in the inbox
      description: Create tag in the inbox
      operationId: Inbox_inbox/create-tags-in-the-inbox
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          type: string
          example: ''
          description: ID of inbox to create the tag in it
          default: ''
        description: ID of inbox to create the tag in it
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          example: Bearer {token}
          description: ''
          default: ''
        description: ''
        example: Bearer {token}
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: ''
                    example:
                      tag_id: 784268
                      name: Property 123
                      color_hexcode: '#64b5f6'
                      background_hexcode: '#f2f4f5'
                      smid: 284967
                      description: Sales pipeline conversations
                    properties:
                      tag_id:
                        type: number
                        description: ''
                        example: 784268
                      name:
                        type: string
                        description: ''
                        example: Property 123
                      color_hexcode:
                        type: string
                        description: ''
                        example: '#64b5f6'
                      background_hexcode:
                        type: string
                        description: ''
                        example: '#f2f4f5'
                      smid:
                        type: number
                        description: ''
                        example: 284967
                      description:
                        type: string
                        description: ''
                        example: Sales pipeline conversations
      requestBody:
        description: Request body
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ''
                  example: Property 123
                color_hexcode:
                  type: string
                  description: ''
                  example: '#64b5f6'
                description:
                  type: string
                  description: ''
                  example: Sales pipeline conversations
              required:
              - name
  /inboxes/{inbox_id}/tags/search:
    get:
      tags:
      - Inbox
      summary: Search tags in the inbox
      description: Search tags in the inbox
      operationId: Inbox_inbox/search-tags-in-the-inbox
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          type: string
          example: '343'
          description: ID of inbox to get the user list for
          default: ''
        description: ID of inbox to get the user list for
        example: '343'
      - name: name
        in: query
        required: true
        schema:
          type: string
          example: Priority
          description: Name of the tag to be searched for
          default: ''
        description: Name of the tag to be searched for
        example: Priority
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          example: Bearer {token}
          description: ''
          default: ''
        description: ''
        example: Bearer {token}
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: ''
                    example:
                      results:
                      - id: '56789'
                        name: Priority
                        color_code: '#ce93d8'
                        type: user
                        created_at: 1708945347
                      pagination:
                        next_page: Gygskjhgkjythjjhkgjhgsdf=
                    properties:
                      results:
                        type: array
                        description: ''
                        example:
                        - id: '56789'
                          name: Priority
                          color_code: '#ce93d8'
                          type: user
                          created_at: 1708945347
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: ''
                              example: '56789'
                            name:
                              type: string
                              description: ''
                              example: Priority
                            color_code:
                              type: string
                              description: ''
                              example: '#ce93d8'
                            type:
                              type: string
                              description: ''
                              example: user
                            created_at:
                              type: number
                              description: ''
                              example: 1708945347
                      pagination:
                        type: object
                        description: ''
                        example:
                          next_page: Gygskjhgkjythjjhkgjhgsdf=
                        properties:
                          next_page:
                            type: string
                            description: ''
                            example: Gygskjhgkjythjjhkgjhgsdf=
x-theneo-metadata:
  menu:
  - name: Inbox
    description: "An Inbox is an entity that has conversations & users. Most common form of an Inbox is a shared mailbox ([https://hiverhq.com/shared-inbox](https://hiverhq.com/shared-inbox)) which manages emails. The APIs only manage the shared mailbox. We plan to add other type of inboxes in the APIs soon. It can have tags to help manage the conversations better.\n\nFollowing is an example of an Inbox object\n\n<CodeBlock attributes='{\"isFitToPage\":true,\"style\":{},\"lang\":\"json\",\"label\":\"Plain text\"}'>\n  <CodeLine>    {</CodeLine>\n  <CodeLine>      \"id\": \"101\",</CodeLine>\n  <CodeLine>      \"display_name\": \"Customer Support\",</CodeLine>\n  <CodeLine>      \"channel_type\": \"email\",</CodeLine>\n  <CodeLine>      \"email\": \"info@hiver.com\",</CodeLine>\n  <CodeLine>      \"inbox_type\": \"user\",</CodeLine>\n  <CodeLine>      \"is_authorised\": false,</CodeLine>\n  <CodeLine>      \"source_user\": {</CodeLine>\n  <CodeLine>        \"id\": \"765676\",</CodeLine>\n  <CodeLine>        \"email\": \"info@hiver.com\"</CodeLine>\n  <CodeLine>      },</CodeLine>\n  <CodeLine>      \"created_at\": 176878888,</CodeLine>\n  <CodeLine>      \"updated_at\": 176878888</CodeLine>\n  <CodeLine>    }</CodeLine>\n</CodeBlock>\n\nFollowing is an example of an Inbox User object\n\n<CodeBlock attributes='{\"isFitToPage\":true,\"style\":{},\"lang\":\"json\",\"label\":\"Plain text\"}'>\n  <CodeLine>    {</CodeLine>\n  <CodeLine>      \"id\": \"456\",</CodeLine>\n  <CodeLine>      \"first_name\": \"Phoebe\",</CodeLine>\n  <CodeLine>      \"last_name\": \"Buffay\",</CodeLine>\n  <CodeLine>      \"email\": \"p.buffay@friends.com\",</CodeLine>\n  <CodeLine>      \"phone_number\": \"+19876543444\",</CodeLine>\n  <CodeLine>      \"is_joined\": false</CodeLine>\n  <CodeLine>    }</CodeLine>\n</CodeBlock>\n\nFollowing is an example of an Inbox Tag object\n\n<CodeBlock attributes='{\"isFitToPage\":true,\"style\":{},\"lang\":\"json\",\"label\":\"Plain text\"}'>\n  <CodeLine>    {</CodeLine>\n  <CodeLine>      \"id\": \"56789\",</CodeLine>\n  <CodeLine>      \"name\": \"Priority\",</CodeLine>\n  <CodeLine>      \"color_code\": \"#ce93d8\",</CodeLine>\n  <CodeLine>      \"type\": \"user\",</CodeLine>\n  <CodeLine>      \"created_at\": 1708945347</CodeLine>\n  <CodeLine>    }</CodeLine>\n</CodeBlock>"
    subSections:
    - name: List all the inboxes
      operationId: Inbox_inbox/list-all-the-inboxes
      description: List all the inboxes
    - name: Get an inbox by id
      operationId: Inbox_inbox/get-an-inbox-by-id
      description: Get an Inbox by Id
    - name: Get all users in the inbox
      operationId: Inbox_inbox/get-all-users-in-the-inbox
      description: Get all users in the inbox
    - name: Search users in the inbox
      operationId: Inbox_inbox/search-users-in-the-inbox
      description: Search users in the inbox
    - name: Get tags in the inbox
      operationId: Inbox_inbox/get-tags-in-the-inbox
      description: Get tags in the inbox
    - name: Search tags in the inbox
      operationId: Inbox_inbox/search-tags-in-the-inbox
      description: Search tags in the inbox
    - name: Create tag in the inbox
      operationId: Inbox_inbox/create-tags-in-the-inbox
      description: Create tag in the inbox
  - name: Conversations
    description: "A conversation can be part of one or more inboxes. It can be assigned to a member of the inbox, have a status and tags associated with it.\n\nFollowing is an example of a Conversation object\n\n<CodeBlock attributes='{\"isFitToPage\":true,\"style\":{},\"lang\":\"json\",\"label\":\"JSON\"}'>\n  <CodeLine>    {</CodeLine>\n  <CodeLine>      \"id\": \"234232\",</CodeLine>\n  <CodeLine>      \"assignee\": {</CodeLine>\n  <CodeLine>        \"assignee_type\": \"user\",</CodeLine>\n  <CodeLine>        \"assignee_id\": \"1028399\"</CodeLine>\n  <CodeLine>      },</CodeLine>\n  <CodeLine>      \"status\": \"open\",</CodeLine>\n  <CodeLine>      \"tag_ids\": [</CodeLine>\n  <CodeLine>        \"1234322\", \"343434\"</CodeLine>\n  <CodeLine>      ]</CodeLine>\n  <CodeLine>    }</CodeLine>\n</CodeBlock>"
    subSections:
    - name: Get conversations in the inbox
      operationId: Conversations_conversations/get-conversations-in-the-inbox
      description: 'Get conversations in the inbox


        **Note:** The Gmail Thread IDs returned in the response are scoped to the **user authenticated with the shared mailbox email address (the source user)**. These IDs can be used directly in other Hiver APIs that require Gmail identifiers.'
    - name: Get a conversation in the inbox
      operationId: Conversations_conversations/get-a-conversation-in-the-inbox
      description: "Get a conversation in the inbox\n\n**Note:**\n\n*   The `conversation_id` field accepts either **Hiver conversation ID** or **Gmail thread ID**.\n    \n*   The Gmail Thread ID and Message IDs returned in the response are scoped to the **user authenticated with the shared mailbox email address (the source user)**. These IDs can be used directly in other Hiver APIs that require Gmail identifiers."
    - name: Update conversation in the inbox
      operationId: Conversations_conversations/update-conversation-in-the-inbox
      description: 'Update conversation in the inbox


        **Note**: The `conversation_id` field accepts either **Hiver conversation ID** or **Gmail thread ID.**'
    - name: Create shared draft for conversation
      operationId: Conversations_conversations/update-conversation-in-the-inbox-copy
      description: 'Create a Shared Draft in an inbox conversation


        **Note:** To create a Shared Draft, always use the Gmail Message ID returned for the **user authenticated with the shared mailbox email address (the source user).** Gmail IDs are user-specific and may not match across different users. If the source user''s Gmail Message ID (`**id**`) is unavailable, you can use the global SMTP Message ID found in `**payload.headers**` under the header name `**Message-ID**` (e.g. `**<abc123@mail.gmail.com>**`) as a fallback. This ID is consistent across all users for the same email.'
    - name: Create note on conversation
      operationId: Conversations_conversations/create-note-on-conversation
      description: 'Create a note on a conversation.


        **Note:** For mentions, list the teammate''s email in <span style="background-color:rgb(248, 248, 248)">`mentions`</span> and write the same bare email in <span style="background-color:rgb(248, 248, 248)">`content`</span> where the mention should appear, it will be rendered as <span style="background-color:rgb(248, 248, 248)">`@name`</span>.'