swagger: '2.0'
info:
  version: '2019.03'
  title: Dyspatch API
  description: |
    # Introduction

    The Dyspatch API is based on the REST paradigm, and features resource based URLs with standard HTTP response
    codes to indicate errors. We use standard HTTP authentication and request verbs, and all responses are JSON formatted.
    See our [Implementation Guide](https://docs.dyspatch.io/integrations/implementing_dyspatch/) for more details on
    how to implement Dyspatch.

    ## API Client Libraries

    Dyspatch provides API Clients for popular languages and web frameworks. 

    - [Java](https://github.com/getdyspatch/dyspatch-java)
    - [Javascript](https://github.com/getdyspatch/dyspatch-javascript)
    - [Python](https://github.com/getdyspatch/dyspatch-python)
    - [C#](https://github.com/getdyspatch/dyspatch-dotnet)
    - [Go](https://github.com/getdyspatch/dyspatch-golang)
    - [Ruby](https://github.com/getdyspatch/dyspatch-ruby)

  contact:
    name: Dyspatch Support
    url: 'https://docs.dyspatch.io'
    email: 'support@dyspatch.io'
  termsOfService: https://www.dyspatch.io/legal/terms-of-service/
schemes:
  - https
host: api.dyspatch.io
basePath: /
securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
    description: |
      Set Bearer followed by your API key as the Authorization header in your API requests.

      ```shell
      Authorization: Bearer EXAMPLEAPIKEYXXXXXXXX12345678
      ```

      Below is an example curl request with an API key in the Authorization header.

      ```shell
      curl --request GET \
      --url https://api.dyspatch.io/templates \
      --header 'Authorization: Bearer EXAMPLEAPIKEYXXXXXXXX12345678' \
      --header 'Accept: application/vnd.dyspatch.2019.03+json'
      ```

paths:
  /templates:
    get:
      security:
        - Bearer: []
      summary: List Templates
      description: Gets a list of Template Metadata objects for all templates. Up to 25 results returned before results are paginated.
      tags:
        - Templates
      produces:
        - application/vnd.dyspatch.2019.03+json
      parameters:
        - $ref: '#/parameters/cursor'
        - $ref: '#/parameters/version'
      responses:
        200:
          description: A list of templates
          headers:
            X-RateLimit-Remaining:
              type: integer
              description: The number of requests left for the time window.
          schema:
            $ref: '#/definitions/TemplatesRead'
        400:
          $ref: '#/responses/InvalidRequest'
        401:
          $ref: '#/responses/Unauthenticated'
        403:
          $ref: '#/responses/Unauthorized'
        429:
          $ref: '#/responses/RateLimited'
        500:
          $ref: '#/responses/InternalError'
        default:
          $ref: '#/responses/InternalError'
  /templates/{templateId}:
    get:
      security:
        - Bearer: []
      summary: Get Template by ID
      description: Gets a template object with the matching ID. Templates without a published draft will result in an error.
      tags:
        - Templates
      produces:
        - application/vnd.dyspatch.2019.03+json
      parameters:
        - $ref: '#/parameters/templateId'
        - $ref: '#/parameters/targetLanguage'
        - $ref: '#/parameters/version'
      responses:
        200:
          description: A template object with the requested ID. Templates without a published draft will result in an error.
          headers:
            X-RateLimit-Remaining:
              type: integer
              description: The number of requests left for the current time window
          schema:
            $ref: '#/definitions/TemplateRead'
        400:
          $ref: '#/responses/InvalidRequest'
        401:
          $ref: '#/responses/Unauthenticated'
        403:
          $ref: '#/responses/Unauthorized'
        404:
          $ref: '#/responses/NotFound'
        429:
          $ref: '#/responses/RateLimited'
        500:
          $ref: '#/responses/InternalError'
        default:
          $ref: '#/responses/InternalError'
  /localizations/{localizationId}:
    get:
      security:
        - Bearer: []
      summary: Get Localization Object by ID
      description: Returns a specific localization object with a matching ID
      tags:
        - Localizations
      produces:
        - application/vnd.dyspatch.2019.03+json
      parameters:
        - $ref: '#/parameters/localizationId'
        - $ref: '#/parameters/targetLanguage'
        - $ref: '#/parameters/version'
      responses:
        200:
          description: A localization object with the requested ID
          headers:
            X-RateLimit-Remaining:
              type: integer
              description: The number of requests left for the current time window
          schema:
            $ref: '#/definitions/LocalizationRead'
        400:
          $ref: '#/responses/InvalidRequest'
        401:
          $ref: '#/responses/Unauthenticated'
        403:
          $ref: '#/responses/Unauthorized'
        404:
          $ref: '#/responses/NotFound'
        429:
          $ref: '#/responses/RateLimited'
        500:
          $ref: '#/responses/InternalError'
        default:
          $ref: '#/responses/InternalError'

definitions:
  cursor:
    type: object
    description: Information about paginated results
    properties:
      next:
        type: string
        description: A cursor to fetch the next page of results
      hasMore:
        type: boolean
        description: Whether there is a next page of results
  templateId:
    type: string
    description: An opaque, unique identifier for a template
    example: tem_g3L7Cw6Hp5wU
  templateName:
    type: string
    description: The name of a template
  templateDescription:
    type: string
    description: A description of the template
  templateUrl:
    type: string
    example: '/templates/tem_g3L7Cw6Hp5wUaf395LehwK'
    description: The API url for a specific template
  localizationId:
    type: string
    description: An opaque, unique identifier for a localization
    example: loc_g3L7Cw6Hp5wUaf395LehwK
  localizationUrl:
    type: string
    example: '/localizations/loc_g3L7Cw6Hp5wUaf395LehwK'
    description: The API url for a specific localization
  localizationName:
    type: string
    example: 'English (US)'
    description: The user-specified name of a localization
  languageId:
    type: string
    description: |
      A language identifier comprised of a language and a country identifier. 
      See [supported languages](https://docs.dyspatch.io/localization/supported_languages/).
    example: en-US
  createdAt:
    type: string
    format: date-time
    description: The time of initial creation
  updatedAt:
    type: string
    format: date-time
    description: The time of last update
  TemplateMetaRead:
    type: object
    properties:
      id:
        $ref: '#/definitions/templateId'
      name:
        $ref: '#/definitions/templateName'
      description:
        $ref: '#/definitions/templateDescription'
      url:
        $ref: '#/definitions/templateUrl'
      localizations:
        type: array
        items:
          $ref: '#/definitions/LocalizationMetaRead'
        description: A list of the template's available localization objects
      createdAt:
        $ref: '#/definitions/createdAt'
      updatedAt:
        $ref: '#/definitions/updatedAt'
  TemplatesRead:
    type: object
    properties:
      cursor:
        $ref: '#/definitions/cursor'
      data:
        type: array
        items:
          $ref: '#/definitions/TemplateMetaRead'
        description: A list of template metadata objects
  TemplateRead:
    type: object
    properties:
      id:
        $ref: '#/definitions/templateId'
      name:
        $ref: '#/definitions/templateName'
      description:
        $ref: '#/definitions/templateDescription'
      url:
        $ref: '#/definitions/templateUrl'
      compiled:
        $ref: '#/definitions/CompiledRead'
      createdAt:
        $ref: '#/definitions/createdAt'
      updatedAt:
        $ref: '#/definitions/updatedAt'
      localizations:
        type: array
        items:
          $ref: '#/definitions/LocalizationMetaRead'
        description: A list of the Template's available localizations
  LocalizationMetaRead:
    type: object
    properties:
      id:
        $ref: '#/definitions/localizationId'
      language:
        $ref: '#/definitions/languageId'
      name:
        $ref: '#/definitions/localizationName'
      url:
        $ref: '#/definitions/localizationUrl'
  LocalizationRead:
    type: object
    properties:
      id:
        $ref: '#/definitions/localizationId'
      language:
        $ref: '#/definitions/languageId'
      url:
        $ref: '#/definitions/localizationUrl'
      template:
        $ref: '#/definitions/templateId'
      compiled:
        $ref: '#/definitions/CompiledRead'
      createdAt:
        $ref: '#/definitions/createdAt'
      updatedAt:
        $ref: '#/definitions/updatedAt'
      name:
        $ref: '#/definitions/localizationName'
  APIError:
    type: object
    properties:
      code:
        type: string
        enum:
          - server_error
          - invalid_parameter
          - invalid_body
          - invalid_request
          - unauthorized
          - unauthenticated
          - not_found
          - rate_limited
        description: >
          Error code:
            * server_error - Internal server error.
            * invalid_parameter - Validation error, parameter will contain invalid field and message will contain the reason.
            * invalid_body - Body could not be parsed, message will contain the reason.
            * invalid_request - Validation error, the protocol used to make the request was not https.
            * unauthorized - Credentials were found but permissions were not sufficient.
            * unauthenticated - Credentials were not found or were not valid.
            * not_found - The requested resource was not found.
            * rate_limited - The request was refused because a rate limit was exceeded. There is an account wide rate limit of 3600 requests per-minute, although that is subject to change. The current remaining rate limit can be viewed by checking the X-Ratelimit-Remaining header.
      message:
        type: string
        description: Human readable error message
      parameter:
        type: string
        description: The invalid parameter, if 'code' is invalid_parameter
  CompiledRead:
    type: object
    properties:
      sender:
        type: string
        example: 'Example <example@dyspatch.io>'
        description: 'Sender address'
      replyTo:
        type: string
        example: 'Example <example@dyspatch.io>'
        description: 'Reply-To address'
      subject:
        type: string
        format: byte
        example: 'PGh0bWw+PC9odG1sPgo='
        description: 'Base64 encoded template subject line'
      html:
        type: string
        format: byte
        example: 'PGh0bWw+PC9odG1sPgo='
        description: 'Base64 encoded template HTML body'
      text:
        type: string
        format: byte
        example: 'PGh0bWw+PC9odG1sPgo='
        description: 'Base64 encoded template text body'

responses:
  #5xx
  InternalError:
    description: Server error
    headers:
      X-RateLimit-Remaining:
        type: integer
        description: The number of requests left for the time window.
    schema:
      $ref: '#/definitions/APIError'
  #400
  InvalidRequest:
    description: Invalid request
    headers:
      X-RateLimit-Remaining:
        type: integer
        description: The number of requests left for the time window.
    schema:
      $ref: '#/definitions/APIError'
  #429
  RateLimited:
    description: Rate limit exceeded
    headers:
      X-RateLimit-Remaining:
        type: integer
        description: The number of requests left for the time window.
    schema:
      $ref: '#/definitions/APIError'
  #401
  Unauthenticated:
    description: Unauthenticated
    headers:
      X-RateLimit-Remaining:
        type: integer
        description: The number of requests left for the time window.
    schema:
      $ref: '#/definitions/APIError'
  #403
  Unauthorized:
    description: Unauthorized
    headers:
      X-RateLimit-Remaining:
        type: integer
        description: The number of requests left for the time window.
    schema:
      $ref: '#/definitions/APIError'
  #404
  NotFound:
    description: Resource not found
    headers:
      X-RateLimit-Remaining:
        type: integer
        description: The number of requests left for the time window.
    schema:
      $ref: '#/definitions/APIError'

parameters:
  version:
    in: header
    name: Accept
    type: string
    required: true
    description: A version of the API that should be used for the request. For example, to use version "2019.03", set the value to "application/vnd.dyspatch.2019.03+json"
  cursor:
    name: cursor
    in: query
    description: A cursor value used to retrieve a specific page from a paginated result set.
    required: false
    type: string
  templateId:
    name: templateId
    in: path
    description: A template ID
    required: true
    type: string
  targetLanguage:
    name: targetLanguage
    in: query
    description: The type of templating language to compile as. Should only be used for visual templates.
    required: true
    type: string
    enum: ['html', 'handlebars', 'ampscript', 'freemarker', 'cheetah', 'jinja']
  localizationId:
    name: localizationId
    in: path
    description: A localization ID
    type: string
    required: true

tags:
  - name: Templates
    description: |
      Templates are the email templates found in your Dyspatch account. Only the published Template Draft is returned.
      A typical integration will start with using the Templates list endpoint to iterate through and sync Templates.

  - name: Localizations
    description: |
      Localization objects are the same as Template objects except they contain localized content.
      If your account is using localizations then use this instead of the compiled Template object.
