Mavrck Conversations API

openapi: 3.2.0
info:
  version: 1.0.0
  description: Identify your most influential customers and activate them to drive more conversions on social.
  title: MAVRCK.IO Conversations API
servers:
- url: http://app.splashscore.com/v1
- url: https://app.splashscore.com/v1
security:
- apiKey: []
tags:
- name: Conversations
paths:
  /conversations/general-folders:
    get:
      tags:
      - Conversations
      operationId: getGeneralFolders
      x-handler: conversations/conversation_folders/conversation_folders_controller.js
      x-access:
      - administrator
      summary: Get the General Folders Unread Counts.
      parameters:
      - name: keys
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Static General Folders with unread count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralFolders'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Conversation not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /conversations/dynamic-campaign-folders:
    get:
      tags:
      - Conversations
      operationId: getCampaignFolders
      x-handler: conversations/conversation_folders/conversation_folders_controller.js
      x-access:
      - administrator
      summary: Get the General Folders Unread Counts.
      parameters:
      - name: keys
        in: query
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: Collection of conversations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CampaignFolder'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Conversation not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /messages/{id}:
    get:
      tags:
      - Conversations
      operationId: getMessage
      x-handler: conversations/message_controller.js
      x-access:
      - administrator
      summary: Retrieve a message by id.
      parameters:
      - name: id
        in: path
        description: The Id of the message to retrieve.
        required: true
        schema:
          type: string
      - name: includes
        in: query
        description: A comma-separated list of message dimensions to return. If not specified, then return standard dimensions.
        schema:
          type: string
      responses:
        '200':
          description: Retrieved the message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /draft:
    post:
      tags:
      - Conversations
      operationId: createDraft
      x-handler: conversations/drafts/draft_controller.js
      x-access:
      - administrator
      summary: Send a new message.
      parameters:
      - name: replyToMessageId
        in: query
        required: false
        schema:
          type: integer
      - $ref: '#/components/parameters/OutboundMessage'
      responses:
        '200':
          description: Draft created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversationId:
                    type: integer
                  message:
                    $ref: '#/components/schemas/Message'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Message not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /draft/{messageId}:
    put:
      tags:
      - Conversations
      operationId: updateDraft
      x-handler: conversations/drafts/draft_controller.js
      x-access:
      - administrator
      summary: Update the draft.
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/OutboundMessage'
      responses:
        '200':
          description: Draft updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/Message'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Message not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Conversations
      operationId: throwOutDraft
      x-handler: conversations/drafts/draft_controller.js
      x-access:
      - administrator
      summary: Throw out the draft.
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Draft thrown out successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/Message'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Message not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sendMessage/{messageId}:
    put:
      tags:
      - Conversations
      operationId: sendMessage
      x-handler: conversations/message_send_outbound_controller.js
      x-access:
      - administrator
      summary: Send a message.
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Message sent successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/Message'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Message not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /messages/{messageId}/reply:
    post:
      tags:
      - Conversations
      operationId: replyToMessage
      x-handler: conversations/message_reply_controller.js
      x-access:
      - administrator
      summary: Reply to a message.
      parameters:
      - name: messageId
        in: path
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/OutboundMessage'
      responses:
        '200':
          description: Message sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Message not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /conversations:
    get:
      tags:
      - Conversations
      operationId: getConversations
      x-handler: conversations/conversation_controller.js
      x-access:
      - administrator
      summary: Retrieve conversations.
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/orderDirection'
      - name: search
        in: query
        description: Search for incentive title or influencer first name, last name, or email, using a trailing wildcard.
        schema:
          type: string
      - name: orderProperty
        in: query
        schema:
          type: string
          enum:
          - mostRecentMessageCreatedAt
      - name: isArchived
        in: query
        schema:
          type: boolean
      - name: markedAsUnread
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Collection of conversations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/ConversationResponseMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /find-all-conversations:
    get:
      tags:
      - Conversations
      operationId: findAllConversations
      x-handler: conversations/conversation_controller.js
      x-access:
      - administrator
      summary: Retrieve conversations.
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/orderDirection'
      - name: search
        in: query
        description: Search for incentive title or influencer first name, last name, or email, using a trailing wildcard.
        schema:
          type: string
      - name: orderProperty
        in: query
        schema:
          type: string
          enum:
          - mostRecentMessageCreatedAt
      - name: isArchived
        in: query
        schema:
          type: boolean
      - name: markedAsUnread
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Collection of conversations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/ConversationResponseMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /count-conversations:
    get:
      tags:
      - Conversations
      operationId: countConversations
      x-handler: conversations/conversation_controller.js
      x-access:
      - administrator
      summary: Retrieve conversations.
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/orderDirection'
      - name: search
        in: query
        description: Search for incentive title or influencer first name, last name, or email, using a trailing wildcard.
        schema:
          type: string
      - name: orderProperty
        in: query
        schema:
          type: string
          enum:
          - mostRecentMessageCreatedAt
      - name: isArchived
        in: query
        schema:
          type: boolean
      - name: markedAsUnread
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Collection of conversations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/ConversationResponseMetadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /conversations/{id}:
    get:
      tags:
      - Conversations
      operationId: getConversation
      x-handler: conversations/conversation_controller.js
      x-access:
      - administrator
      summary: Retrieve a conversation by id.
      parameters:
      - name: id
        in: path
        description: The Id of the conversation to retrieve.
        required: true
        schema:
          type: string
      - name: includes
        in: query
        description: A comma-separated list of conversation dimensions to return. If not specified, then return standard dimensions.
        schema:
          type: string
      responses:
        '200':
          description: Collection of conversations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Invalid parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Conversation not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/conversations/bulk-action/read:
    post:
      operationId: bulkMarkConversationsAsRead
      responses:
        '201':
          description: updated
        '422':
          description: Validation Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      tags:
      - Conversations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationBulkActionRequestBody'
        required: true
  /v1/conversations/bulk-action/unread:
    post:
      operationId: bulkMarkConversationsAsUnread
      responses:
        '201':
          description: updated
        '422':
          description: Validation Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      tags:
      - Conversations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationBulkActionRequestBody'
        required: true
  /v1/conversations/bulk-action/archive:
    post:
      operationId: bulkArchiveConversations
      responses:
        '201':
          description: updated
        '422':
          description: Validation Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      tags:
      - Conversations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationBulkActionRequestBody'
        required: true
  /v1/conversations/bulk-action/unarchive:
    post:
      operationId: bulkUnarchiveConversations
      responses:
        '201':
          description: updated
        '422':
          description: Validation Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      tags:
      - Conversations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationBulkActionRequestBody'
        required: true
  /v1/inline-images:
    post:
      operationId: uploadInlineImage
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadInlineImageResult'
        '400':
          description: Invalid Parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '403':
          description: Access forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '500':
          description: Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      tags:
      - Conversations
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required:
              - file
  /v1/messages/{messageId}/events:
    get:
      operationId: getMessageEvents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryByMessageResult'
        '400':
          description: Missing Parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: The resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      tags:
      - Conversations
      parameters:
      - in: path
        name: messageId
        required: true
        schema:
          type: number
          format: double
      - in: query
        name: limit
        required: false
        schema:
          type: number
          format: double
      - in: query
        name: offset
        required: false
        schema:
          type: number
          format: double
      - in: query
        name: orderDirection
        required: false
        schema:
          type: string
          enum:
          - DESC
          - ASC
      - in: query
        name: orderProperty
        required: false
        schema:
          type: string
          enum:
          - occurredAt
      - in: query
        name: event
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
components:
  schemas:
    Error:
      type: object
      properties:
        type:
          type: string
          description: A key representing the type of error that has occurred.
        error:
          type: string
          description: A static description of the type of error.
        params:
          type: array
          description: For errors invovling parameters, this is an array containing the invalid parameters.
          items:
            type: string
        keys:
          type: array
          items:
            type:
            - string
            - object
        artifactLinks:
          $ref: '#/components/schemas/LinksDeprecated'
        parent:
          type: object
          properties:
            type:
              type: string
              description: A key representing the type of error generated by a request to an external API.
            error:
              type: string
              description: A static description of the parent error.
    UploadInlineImageResult:
      properties:
        link:
          type: string
      required:
      - link
      type: object
      additionalProperties: false
    GeneralFolders:
      type: object
      properties:
        inbox:
          type: integer
        generalInquiries:
          type: integer
        draft:
          type: integer
        sent:
          type: integer
        archived:
          type: integer
    WorkflowStatusRequirementDeprecated:
      type: object
      properties:
        satisfied:
          type: boolean
        incentiveId:
          type: number
        name:
          type: string
    MessageRecipient:
      type: object
      properties:
        displayName:
          type:
          - string
          - 'null'
        email:
          type: string
        emailId:
          type: integer
        role:
          type: string
          enum:
          - from
          - to
          - cc
    NotFoundError:
      properties:
        message:
          type: string
          enum:
          - Resource Not Found
        details:
          properties: {}
          additionalProperties:
            additionalProperties: true
          type: object
      required:
      - message
      - details
      type: object
      additionalProperties: false
    ConversationBulkActionRequestBody:
      properties:
        conversationIds:
          items:
            type: number
            format: double
          type: array
        search:
          type: string
      type: object
      additionalProperties: false
    Attachment:
      type: object
      properties:
        originalName:
          type: string
        encoding:
          type: string
        buffer:
          type: string
        mimeType:
          type: string
        disposition:
          type: string
        size:
          type: integer
        uri:
          type: string
        contentId:
          type: string
    Message:
      type: object
      properties:
        id:
          type: integer
        subject:
          type: string
        messageIdHeader:
          type: string
        conversationId:
          type: string
        scheduledFor:
          type: string
          format: date-time
        scheduledMessage:
          type: object
          properties:
            id:
              type: integer
            createdAt:
              type: string
              format: date-time
            messageId:
              type: integer
            accountId:
              type: integer
            communityId:
              type: string
            sendAt:
              type: string
              format: date-time
            status:
              type: string
            updatedAt:
              type: string
              format: date-time
        inReplyToHeader:
          type: string
        status:
          type: string
        html:
          type: string
        parsedReply:
          type: string
        isInbound:
          type: boolean
        hasBeenOpened:
          type: boolean
        hasBeenDelivered:
          type: boolean
        hasBeenBounced:
          type: boolean
        createdAt:
          type: string
          format: date-time
        sentAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time
        sentBy:
          $ref: '#/components/schemas/AdministratorDeprecated'
        modifiedBy:
          $ref: '#/components/schemas/AdministratorDeprecated'
        createdBy:
          $ref: '#/components/schemas/AdministratorDeprecated'
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/MessageRecipient'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        templates:
          type: array
          items:
            $ref: '#/components/schemas/ConversationTemplateDeprecated'
        draftReply:
          type: object
          properties:
            id:
              type: integer
            subject:
              type: string
            messageIdHeader:
              type: string
            conversationId:
              type: string
            scheduledFor:
              type: string
              format: date-time
            scheduledMessage:
              type: object
              properties:
                id:
                  type: integer
                createdAt:
                  type: string
                  format: date-time
                messageId:
                  type: integer
                accountId:
                  type: integer
                communityId:
                  type: string


# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mavrck/refs/heads/main/openapi/mavrck-conversations-api-openapi.yml