Listrak Message API

openapi: 3.2.0
info:
  version: v1
  title: Listrak Email REST Message API
  description: '# Introduction

    Welcome to the Listrak Email REST API!'
  x-logo:
    url: /Email/Resources/Images/Logo.png
servers:
- url: https://api.listrak.com/email
tags:
- name: Message
  description: The Message resource provides a way to send and retrieve messages for a list.
paths:
  /v1/List/{listId}/Message:
    get:
      tags:
      - Message
      summary: Get all Messages
      description: Returns a collection of messages for the specified list.
      operationId: Message_GetMessageCollection
      parameters:
      - name: listId
        in: path
        description: Identifier used to locate the list.
        required: true
        schema:
          type: integer
          format: int32
      - name: cursor
        in: query
        description: Value indicating the page of data that's being retrieved. The default value is `Start`.
        required: false
        schema:
          type: string
      - name: count
        in: query
        description: Number of data members to be displayed per page. The default value is `1000` and the maximum value is `5000`.
        required: false
        schema:
          type: string
      - name: startDate
        in: query
        description: The start of the date range used for filtering.
        required: false
        schema:
          type: string
      - name: endDate
        in: query
        description: The end of the date range used for filtering.
        required: false
        schema:
          type: string
      - name: includeTestMessages
        in: query
        description: Whether test messages should be included in the collection. The default value is `false`.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionPaged_Message'
              example:
                status: 200
                nextPageCursor: null
                data:
                - messageId: 0
                  sendDate: null
                  messageStatus: null
                  campaignId: 0
                  externalCampaignId: null
                  subject: null
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 400
                error: ERROR_INVALID_PARAMETER
                message: An invalid value was supplied for {Parameter}.
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 404
                error: ERROR_UNABLE_TO_LOCATE_RESOURCE
                message: Unable to locate a resource associated with the listId supplied.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 401
                error: ERROR_UNAUTHORIZED
                message: Authorization was denied for this request.
      security:
      - OAuth 2:
        - List
        - Message
      x-code-samples:
      - lang: C#
        source: 'var client = new HttpClient();


          client.BaseAddress = new Uri("https://api.listrak.com/email/");

          client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);


          var response = await client.GetAsync("v1/List/{listId}/Message");

          '
      - lang: PHP
        source: "$client = new \\GuzzleHttp\\Client([\n\t'base_uri' => 'https://api.listrak.com/email/'\n]);\n\n$res = $client->request('GET', 'v1/List/{listId}/Message',  [\n\t'headers' => ['Authorization' => 'Bearer ' . $accessToken]\n]);\n"
    post:
      tags:
      - Message
      summary: Send a Message
      description: Sends a new message on the specified list.
      operationId: Message_PostMessageResource
      parameters:
      - name: listId
        in: path
        description: Identifier used to locate the list.
        required: true
        schema:
          type: integer
          format: int32
      - name: sendDate
        in: query
        description: The send date for the message.
        required: false
        schema:
          type: string
          format: date-time
      - name: sendTestMessage
        in: query
        description: Whether a test message should be sent. The default value is `false`.
        required: false
        schema:
          type: boolean
      - name: sendReviewMessage
        in: query
        description: Whether a review message should be sent. The default value is `false`.
        required: false
        schema:
          type: boolean
      - name: testEmailAddress
        in: query
        description: Test email address that will be used to preview the scheduled message.
        required: false
        schema:
          type: string
      responses:
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 400
                error: ERROR_INVALID_PARAMETER
                message: An invalid value was supplied for {Parameter}.
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreated'
              example:
                status: 201
                resourceId: '{ResourceId}'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 401
                error: ERROR_UNAUTHORIZED
                message: Authorization was denied for this request.
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 404
                error: ERROR_UNABLE_TO_LOCATE_RESOURCE
                message: Unable to locate a resource associated with the listId supplied.
      security:
      - OAuth 2:
        - List
        - Message
      x-code-samples:
      - lang: C#
        source: "var client = new HttpClient();\n\nclient.BaseAddress = new Uri(\"https://api.listrak.com/email/\");\nclient.DefaultRequestHeaders.Add(\"Authorization\", \"Bearer \" + token);\n\nvar response = await client.PostAsJsonAsync(\"v1/List/{listId}/Message?sendDate={sendDate}&sendTestMessage={sendTestMessage}&sendReviewMessage={sendReviewMessage}&testEmailAddress={testEmailAddress}\", new\n{\n   Filter = null,\n   BodyHtml = null,\n   BodyText = null,\n   CodePage = 0,\n   EnablePassalong = false,\n   EnableTracking = false,\n   FromEmail = null,\n   FromName = null,\n   GoogleAnalyticsCampaignName = null,\n   GoogleAnalyticsCampaignContent = null,\n   ReplyEmail = null,\n   ToName = null,\n   EnableUniversalEmailKeySetting = false,\n   CampaignId = 0,\n   ExternalCampaignId = null,\n   Subject = null\n});\n"
      - lang: PHP
        source: "$client = new \\GuzzleHttp\\Client([\n\t'base_uri' => 'https://api.listrak.com/email/'\n]);\n\n$res = $client->request('POST', 'v1/List/{listId}/Message',  [\n\t'headers' => ['Authorization' => 'Bearer ' . $accessToken],\n\t'json' => $jsonBody\n]);\n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageExtendedFilter'
        description: Representation of the message to be sent.
        required: true
  /v1/List/{listId}/Message/{messageId}:
    get:
      tags:
      - Message
      summary: Get a Message
      description: Returns the specified message.
      operationId: Message_GetMessageResource
      parameters:
      - name: listId
        in: path
        description: Identifier used to locate the list.
        required: true
        schema:
          type: integer
          format: int32
      - name: messageId
        in: path
        description: Identifier used to locate the message.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource_MessageExtendedSegmentsApplied'
              example:
                status: 200
                data:
                  messageId: 0
                  sendDate: null
                  messageStatus: null
                  enableUniversalEmailKeySetting: false
                  campaignId: 0
                  bodyHtml: null
                  bodyText: null
                  codePage: 0
                  enablePassalong: false
                  enableTracking: false
                  externalCampaignId: null
                  fromEmail: null
                  fromName: null
                  googleAnalyticsCampaignName: null
                  googleAnalyticsCampaignContent: null
                  replyEmail: null
                  savedAudienceId: 0
                  segmentsApplied: null
                  subject: null
                  toName: null
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 400
                error: ERROR_INVALID_PARAMETER
                message: An invalid value was supplied for {Parameter}.
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 404
                error: ERROR_UNABLE_TO_LOCATE_RESOURCE
                message: Unable to locate a resource associated with the listId and messageId supplied.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 401
                error: ERROR_UNAUTHORIZED
                message: Authorization was denied for this request.
      security:
      - OAuth 2:
        - List
        - Message
      x-code-samples:
      - lang: C#
        source: 'var client = new HttpClient();


          client.BaseAddress = new Uri("https://api.listrak.com/email/");

          client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);


          var response = await client.GetAsync("v1/List/{listId}/Message/{messageId}");

          '
      - lang: PHP
        source: "$client = new \\GuzzleHttp\\Client([\n\t'base_uri' => 'https://api.listrak.com/email/'\n]);\n\n$res = $client->request('GET', 'v1/List/{listId}/Message/{messageId}',  [\n\t'headers' => ['Authorization' => 'Bearer ' . $accessToken]\n]);\n"
components:
  schemas:
    MessageExtendedSegmentsApplied:
      required:
      - externalCampaignId
      - fromEmail
      - fromName
      - subject
      type: object
      properties:
        messageId:
          format: int32
          description: Identifier used to locate the message.
          type: integer
          readOnly: true
        sendDate:
          format: date-time
          description: Send date of the message.
          type: string
          readOnly: true
        messageStatus:
          description: Status displaying whether the message is sent or scheduled.
          type: string
          readOnly: true
        enableUniversalEmailKeySetting:
          description: Whether to include UniversalEmailKey in URL query string.
          type: boolean
        campaignId:
          format: int32
          description: Identifier of the campaign associated with the message.
          type: integer
        bodyHtml:
          description: HTML body that will be sent in the message.
          type: string
        bodyText:
          description: Text body that will be sent in the message.
          type: string
        codePage:
          format: int32
          description: Type of CodePage used in the message.
          type: integer
        enablePassalong:
          description: Whether passalong is enabled.
          type: boolean
        enableTracking:
          description: Whether tracking is enabled.
          type: boolean
        externalCampaignId:
          description: Customer-provided identifier of the campaign associated with the message.
          type: string
        fromEmail:
          description: The _from email address_ that will be used for the message.
          type: string
        fromName:
          description: The _from name_ that will be used for the message.
          type: string
        googleAnalyticsCampaignName:
          description: The Google Analytics campaign name to be used for message tracking.
          type: string
        googleAnalyticsCampaignContent:
          description: The Google Analytics campaign content to be used for message tracking.
          type: string
        replyEmail:
          description: The _reply email address_ that will be used for the message.
          type: string
        savedAudienceId:
          format: int32
          description: Identifier of the SavedAudience to use for recipient filtering.
          type: integer
        segmentsApplied:
          $ref: '#/components/schemas/SegmentsApplied'
          description: Segments applied to the message.
        subject:
          description: Subject of the message.
          type: string
        toName:
          description: The _to name_ that will be used for the message.
          type: string
    CollectionPaged_Message:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        nextPageCursor:
          description: URI of the next page of data.
          type: string
        data:
          description: Collection of data that exists on this paged view.
          type: array
          items:
            $ref: '#/components/schemas/Message'
    Resource_MessageExtendedSegmentsApplied:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        data:
          $ref: '#/components/schemas/MessageExtendedSegmentsApplied'
          description: Return data.
    Message:
      description: A Message resource.
      required:
      - externalCampaignId
      - subject
      type: object
      properties:
        messageId:
          format: int32
          description: Identifier used to locate the message.
          type: integer
          readOnly: true
        sendDate:
          format: date-time
          description: Send date of the message.
          type: string
          readOnly: true
        messageStatus:
          description: Status displaying whether the message is sent or scheduled.
          type: string
          readOnly: true
        campaignId:
          format: int32
          description: Identifier of the campaign associated with the message.
          type: integer
        externalCampaignId:
          description: Customer-provided identifier of the campaign associated with the message.
          type: string
        subject:
          description: Subject of the message.
          type: string
    FilterValue:
      type: object
      properties:
        value:
          description: Value to be used for filtering.
          type: string
    Filter:
      type: object
      properties:
        segmentationFieldGroup:
          description: The name of the profile field group to use for filtering.
          type: string
        segmentationField:
          description: The name of the profile field to use for filtering.
          type: string
        joinType:
          description: The mechanism by which this filter should be joined to the immediately preceding filter. Optional if it is the first filter (ignored if provided anyway).
          enum:
          - And
          - AndNot
          - Or
          - OrNot
          type: string
        compareType:
          description: The type of comparison to use filtering values with.
          enum:
          - Contains
          - NotContains
          - Equals
          - NotEquals
          - GreaterThan
          - GreaterThanOrEqualTo
          - LessThan
          - LessThanOrEqualTo
          - Between
          - NotBetween
          - Checked
          - NotChecked
          - RadioOn
          - RadioOff
          - InCommaList
          - NotInCommaList
          - IsEmpty
          - IsNotEmpty
          type: string
        values:
          description: Values to be used for filtering.
          type: array
          items:
            $ref: '#/components/schemas/FilterValue'
        filters:
          description: 'One or more sub-filters to apply. Cannot be specified in conjunction with the `CompareType` or `Values` fields: filters must define their own filtering behavior, or must define inner filters.'
          type: array
          items:
            $ref: '#/components/schemas/Filter'
    MessageExtendedFilter:
      required:
      - externalCampaignId
      - fromEmail
      - fromName
      - subject
      type: object
      properties:
        messageId:
          format: int32
          description: Identifier used to locate the message.
          type: integer
          readOnly: true
        sendDate:
          format: date-time
          description: Send date of the message.
          type: string
          readOnly: true
        messageStatus:
          description: Status displaying whether the message is sent or scheduled.
          type: string
          readOnly: true
        enableUniversalEmailKeySetting:
          description: Whether to include UniversalEmailKey in URL query string.
          type: boolean
        campaignId:
          format: int32
          description: Identifier of the campaign associated with the message.
          type: integer
        bodyHtml:
          description: HTML body that will be sent in the message.
          type: string
        bodyText:
          description: Text body that will be sent in the message.
          type: string
        codePage:
          format: int32
          description: Type of CodePage used in the message.
          type: integer
        enablePassalong:
          description: Whether passalong is enabled.
          type: boolean
        enableTracking:
          description: Whether tracking is enabled.
          type: boolean
        externalCampaignId:
          description: Customer-provided identifier of the campaign associated with the message.
          type: string
        fromEmail:
          description: The _from email address_ that will be used for the message.
          type: string
        fromName:
          description: The _from name_ that will be used for the message.
          type: string
        googleAnalyticsCampaignName:
          description: The Google Analytics campaign name to be used for message tracking.
          type: string
        googleAnalyticsCampaignContent:
          description: The Google Analytics campaign content to be used for message tracking.
          type: string
        replyEmail:
          description: The _reply email address_ that will be used for the message.
          type: string
        savedAudienceId:
          format: int32
          description: Identifier of the SavedAudience to use for recipient filtering.
          type: integer
        subject:
          description: Subject of the message.
          type: string
        toName:
          description: The _to name_ that will be used for the message.
          type: string
        filter:
          $ref: '#/components/schemas/Filter'
          description: Filter to be used for recipient filtering.
    Error:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        error:
          description: Error code indicating what error has occured.
          type: string
        message:
          description: Message describing the status and the error that occurred.
          type: string
    SegmentsApplied:
      description: Segments applied to the message.
      type: object
      properties:
        includedSegments:
          description: List of segments included in the recipient audience.
          type: array
          items:
            type: string
        excludedSegments:
          description: List of segments excluded from the recipient audience.
          type: array
          items:
            type: string
    ResourceCreated:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        resourceId:
          description: An identifier used to locate a resource.
          type: string
x-tagGroups:
- name: API Reference
  tags:
  - Campaign
  - Contact
  - ContactSegmentationField
  - Content
  - ContentFolder
  - Conversation
  - ConversationMessage
  - ConversationMessageActivity
  - ConversationMessageLink
  - ConversationMessageLinkClicker
  - ConversationMessageSummary
  - ConversationSummary
  - Event
  - EventGroup
  - Folder
  - IpPool
  - List
  - ListImport
  - ListImportContact
  - ListImportStatus
  - ListImportSummary
  - Message
  - MessageActivity
  - MessageLink
  - MessageLinkClicker
  - MessageStatus
  - MessageSummary
  - SavedAudience
  - SavedMessage
  - SegmentationField
  - SegmentationFieldGroup
  - SplitTest
  - TransactionalMessage
  - TransactionalMessageActivity
  - TransactionalMessageResend