Listrak Message API

openapi: 3.2.0
info:
  title: Listrak Message API
  version: v1
  x-logo:
    url: /Email/Resources/Images/Logo.png
  description: 'Operations tagged Message across 2 of this provider''s published API definitions: listrak-email-openapi.json, listrak-email-openapi.yml. Each path carries the servers of the definition it was published in.'
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.\n\n## Filters\n\nFilters can be used to select contacts based on their profile data. They may be supplied when sending a message via the `Filter` field.\n\nFilters may be combined and nested in nearly limitless combinations. A filter is considered valid if it either defines profile data to filter on, or if it defines one or more inner filters. It is not valid to do neither or both. If a filter is defining inner filters, its `Filters` field should be set to an array of one or more filters. Otherwise, it should specify a `CompareType`, a `SegmentationFieldGroup`, a `SegmentationField`, and if applicable, one or more `Values` to apply to filtering logic.\n\nWhen defining multiple filters in a set, the second and subsequent filters must define how they should be joined to the preceding filter. This is specified using the `JoinType` field. Valid values are `And`, `AndNot`, `Or`, and `OrNot`. It is not necessary to specify a `JoinType` for the first (or only) filter in a set, because there is no other filter to join with.\n\nFiltering logic is determined by the `CompareType` field. Below is a table of supported values, a brief description of each, and the number of values required for operation:\n\n| CompareType | Description | Number of values required |\n|-|-|-|\n| `Between` | The field is between the range of the two specified values (inclusive). | 2 |\n| `NotBetween` | The field is not between the range of the two specified values (inclusive). | 2 |\n| `Contains` | The field contains the specified value. | 1 |\n| `NotContains` | The field does not contain the specified value. | 1 |\n| `Equals` | The field equals the specified value (case insensitive). | 1 |\n| `NotEquals` | The field does not equal the specified value (case insensitive). | 1 |\n| `GreaterThan` | The field is greater the specified value. | 1 |\n| `GreaterThanOrEqualTo` | The field is greater than or equal to the specified value. | 1 |\n| `LessThan` | The field is less than the specified value. | 1 |\n| `LessThanOrEqualTo` | The field is less than or equal to the specified value. | 1 |\n| `InCommaList` | The field is one of the specified values in a comma-separated list. | 1 |\n| `NotInCommaList` | The field is not one of the specified values in a comma-separated list. | 1 |\n| `Checked` | The checkbox field is checked. | 0 |\n| `NotChecked` | The checkbox field is not checked. | 0 |\n| `RadioOn` | The radio button is selected. | 0 |\n| `RadioOff` | The radio button is not selected. | 0 |\n| `IsEmpty` | The field is null or empty. | 0 |\n| `IsNotEmpty` | The field is not null or empty. | 0 |\n\nCommon use cases are documented below. The examples assume the following profile configuration:\n\n| Profile field group | Profile field | Value type |\n|-|-|-|\n| Favorites | Color | _Text_ |\n| Favorites | Number | _Numeric_ |\n| Favorites | Movie | _Text_ |\n\nTo select contacts whose favorite color is green:\n\n```\n\"filter\": {\n  \"segmentationFieldGroup\": \"Favorites\",\n  \"segmentationField\": \"Color\",\n  \"compareType\": \"Equals\",\n  \"values\": [\n    {\n      \"value\": \"Green\"\n    }\n  ]\n}\n```\n\nTo select contacts whose favorite color is green _and_ whose favorite number is between 10 and 20:\n\n```\n\"filter\": {\n  filters: [\n    {\n      \"compareType\": \"Equals\",\n      \"segmentationFieldGroup\": \"Favorites\",\n      \"segmentationField\": \"Color\",\n      \"values\": [\n        {\n          \"value\": \"Green\"\n        }\n      ]\n    },\n    {\n      \"compareType\": \"Between\",\n      \"joinType\": \"And\",\n      \"segmentationFieldGroup\": \"Favorites\",\n      \"segmentationField\": \"Number\",\n      \"values\": [\n        {\n          \"value\": \"10\"\n        },\n        {\n          \"value\": \"20\"\n        }\n      ]\n    }\n  ]\n}\n```\n\nTo select contacts whose favorite color is red _or_ whose favorite number is 13:\n\n```\n\"filter\": {\n  filters: [\n    {\n      \"compareType\": \"Equals\",\n      \"segmentationFieldGroup\": \"Favorites\",\n      \"segmentationField\": \"Color\",\n      \"values\": [\n        {\n          \"value\": \"Red\"\n        }\n      ]\n    },\n    {\n      \"compareType\": \"Equals\",\n      \"joinType\": \"Or\",\n      \"segmentationFieldGroup\": \"Favorites\",\n      \"segmentationField\": \"Number\",\n      \"values\": [\n        {\n          \"value\": \"13\"\n        }\n      ]\n    }\n  ]\n}\n```\n\nTo select contacts whose favorite color is green, and additionally either has a favorite number of 13, or otherwise has a favorite movie containing the term `adventures`:\n\n```\n\"filter\": {\n  filters: [\n    {\n      \"compareType\": \"Equals\",\n      \"segmentationFieldGroup\": \"Favorites\",\n      \"segmentationField\": \"Color\",\n      \"values\": [\n        {\n          \"value\": \"Green\"\n        }\n      ]\n    },\n    {\n      \"joinType\": \"And\"\n      \"filters\": [\n        {\n          \"compareType\": \"Equals\",\n          \"segmentationFieldGroup\": \"Favorites\",\n          \"segmentationField\": \"Number\",\n          \"values\": [\n            {\n              \"value\": \"13\"\n            }\n          ]\n        },\n        {\n          \"compareType\": \"Contains\",\n          \"joinType\": \"Or\"\n          \"segmentationFieldGroup\": \"Favorites\",\n          \"segmentationField\": \"Movie\",\n          \"values\": [\n            {\n              \"value\": \"adventures\"\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\nTo select contacts whose favorite color is either black, white, or gold:\n\n```\n\"filter\": {\n  filters: [\n    {\n      \"compareType\": \"InCommaList\",\n      \"segmentationFieldGroup\": \"Favorites\",\n      \"segmentationField\": \"Color\",\n      \"values\": [\n        {\n          \"value\": \"Black,White,Gold\"\n        }\n      ]\n    }\n  ]\n}\n```\n\nTo select contacts who do not have a favorite color:\n\n```\n\"filter\": {\n  filters: [\n    {\n      \"compareType\": \"Empty\",\n      \"segmentationFieldGroup\": \"Favorites\",\n      \"segmentationField\": \"Color\"\n    }\n  ]\n}\n```\n"
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
    servers:
    - url: https://api.listrak.com/email
  /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"
    servers:
    - url: https://api.listrak.com/email
components:
  schemas:
    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
    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
    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
    ResourceCreated:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        resourceId:
          description: An identifier used to locate a resource.
          type: string
    Resource_MessageExtendedSegmentsApplied:
      type: object
      properties:
        status:
          format: int32
          description: HTTP status code.
          type: integer
        data:
          $ref: '#/components/schemas/MessageExtendedSegmentsApplied'
          description: Return data.
    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.
    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'
    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
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.listrak.com/OAuth2/Token
          scopes:
            Contact: Contact access
            Event: Event access
            List: List access
            Message: Message access
            Report: Report access
            Segmentation: Segmentation access
x-refined-from:
- listrak-email-openapi.json
- listrak-email-openapi.yml
x-amazon-apigateway-security-policy: TLS_1_0
x-tagGroups:
- name: API Reference
  tags:
  - Events
  - EventConfigurations