swagger: "2.0"
schemes:
  - https
host: api.inboxroute.com
basePath: /api
info:
  contact:
    email: support@mailsquad.com
    url: https://mailsquad.com
  description: MailSquad offers an affordable and super easy way to create, send and track delightful emails.
  title: Mailsquad
  version: "0.9"
  x-apisguru-categories:
    - email
    - marketing
  x-logo:
    url: https://pbs.twimg.com/profile_images/528918177711796225/5tzW9XKS.png
  x-origin:
    - format: swagger
      url: https://api.inboxroute.com/api/api-docs
      version: "2.0"
  x-providerName: inboxroute.com
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  mqApiKey:
    in: header
    name: Authorization
    type: apiKey
security:
  - mqApiKey: []
responses:
  "401":
    description: Invalid api key or key does not have access to this ressource
    schema:
      items:
        properties:
          classification:
            description: Type of error (AccesDenied)
            type: string
          message:
            description: Human readable description of the error
            type: string
      type: array
  "404":
    description: The requested resource was not found
    schema:
      items:
        properties:
          classification:
            description: Type of error (Object not found)
            type: string
          message:
            description: Human readable description of the error
            type: string
      type: array
  "422":
    description: The request parameters were invalid
    schema:
      items:
        properties:
          classification:
            description: Type of error (ValidationError)
            type: string
          message:
            description: Human readable description of the error
            type: string
      type: array
paths:
  /contacts:
    get:
      description: Get a paged result of contacts from a list
      parameters:
        - description: Unique 16 characters ID of the contact list to get contacts of
          in: query
          name: listid
          type: string
        - description: Skip that many records
          in: query
          name: offset
          type: integer
        - description: Maximum number of items in page
          in: query
          name: limit
          type: integer
        - description: Property to sort by. Append '-' for descending order.
          in: query
          name: sort
          type: string
      responses:
        "200":
          description: Page object
          schema:
            $ref: "#/definitions/ContactPage"
        "401":
          $ref: "#/responses/401"
        "404":
          $ref: "#/responses/404"
        "422":
          $ref: "#/responses/422"
      security:
        - mqApiKey: []
      tags:
        - contacts
  /contacts/lists:
    get:
      description: Get a paged result of contact lists.
      parameters:
        - description: Skip that many records
          in: query
          name: offset
          type: integer
        - description: Maximum number of items in page
          in: query
          name: limit
          type: integer
        - description: Property to sort by. Append '-' for descending order.
          in: query
          name: sort
          type: string
      responses:
        "200":
          description: Page object
          schema:
            $ref: "#/definitions/ContactListPage"
        "401":
          $ref: "#/responses/401"
        "404":
          $ref: "#/responses/404"
        "422":
          $ref: "#/responses/422"
      security:
        - mqApiKey: []
      tags:
        - lists
    post:
      description: Add a new contact list
      parameters:
        - description: Contact list initial properties
          in: body
          name: contactlist
          schema:
            $ref: "#/definitions/ContactListUpdate"
      responses:
        "200":
          description: Page object
          schema:
            $ref: "#/definitions/NewId"
        "401":
          $ref: "#/responses/401"
        "422":
          $ref: "#/responses/422"
      security:
        - mqApiKey: []
      tags:
        - lists
  "/contacts/lists/{listid}":
    delete:
      description: Delete an existing contact list
      parameters:
        - description: Unique 16 characters ID of the contact list
          in: path
          name: listid
          required: true
          type: string
      responses:
        "200":
          description: Empty response
        "401":
          $ref: "#/responses/401"
        "404":
          $ref: "#/responses/404"
      security:
        - mqApiKey: []
      tags:
        - lists
    put:
      description: Update an existing contact list
      parameters:
        - description: Unique 16 characters ID of the contact list
          in: path
          name: listid
          required: true
          type: string
        - description: Contact list properties to update
          in: body
          name: contactlist
          schema:
            $ref: "#/definitions/ContactListUpdate"
      responses:
        "200":
          description: Empty response
        "401":
          $ref: "#/responses/401"
        "404":
          $ref: "#/responses/404"
        "422":
          $ref: "#/responses/422"
      security:
        - mqApiKey: []
      tags:
        - lists
  "/contacts/{contactid}":
    delete:
      description: Delete an existing contact
      parameters:
        - description: Unique 16 characters ID of the contact
          in: path
          name: contactid
          required: true
          type: string
      responses:
        "200":
          description: Empty response
        "401":
          $ref: "#/responses/401"
        "404":
          $ref: "#/responses/404"
      security:
        - mqApiKey: []
      tags:
        - contacts
    put:
      description: Update an existing contact
      parameters:
        - description: Unique 16 characters ID of the contact
          in: path
          name: contactid
          required: true
          type: string
        - description: Contact properties to update
          in: body
          name: contact
          required: true
          schema:
            $ref: "#/definitions/ContactUpdate"
      responses:
        "200":
          description: Empty response
        "401":
          $ref: "#/responses/401"
        "404":
          $ref: "#/responses/404"
        "422":
          $ref: "#/responses/422"
      security:
        - mqApiKey: []
      tags:
        - contacts
  "/subscription/{listid}":
    post:
      description: |
        Subscribe an email address to a list. This api call has the same behavior as
        a regular subscribe form. However, single opt-in is allowed for system integration
        purposes.

        - If email address does not exist, a new contact will be added to the list.
        - If email address exists custom fields will be updated and status will be put
          to unconfirmed or active depending of singleoptin value.
        - If current status if Active, this operation will only update the custom fields.
        - If singleoptin is true, no email confirmation will be sent. In that case,
          you must provide the subscribe's origin ip and confirmation date-time.
      parameters:
        - description: Unique 16 characters ID of the contact list
          in: path
          name: listid
          required: true
          type: string
        - description: Subscription request
          in: body
          name: subscription
          required: true
          schema:
            $ref: "#/definitions/SubscriptionRequest"
      responses:
        "204":
          description: Empty response
        "401":
          $ref: "#/responses/401"
        "404":
          $ref: "#/responses/404"
        "422":
          $ref: "#/responses/422"
      security:
        - mqApiKey: []
      tags:
        - subscription
definitions:
  Contact:
    properties:
      _id:
        description: Unique 16 characters ID
        type: string
      clientid:
        description: Unique 16 characters ID of the client owner
        type: string
      confirmed:
        description: Date+time subscriber confirmed his/her list opt-in
        format: date-time
        type: string
      customfields:
        description: Dictionnary of field key to value
      email:
        description: Email address
        type: string
      fullname:
        description: |
          Full name (Last name, First Name) of the subscriber
        type: string
      ip:
        description: Subscriber's IP address when he/she confirmed list opt-in
        type: string
      lang:
        description: |
          ISO 639-1 language code of the subscriber. When lang is one the supported system language, all communication
          will be in this language. 
        type: string
      listid:
        description: Unique 16 characters ID of the list owner
        type: string
      status:
        description: |
          Status (
            1- Active,
            2- Unconfirmed,
            3- Unsubscribed,
            4- Deleted,
            5- Cleaned because of hard bounce or spam complaint)
        type: integer
  ContactAdd:
    properties:
      confirmed:
        description: Date+time subscriber confirmed his/her list opt-in
        format: date-time
        type: string
      customfields:
        description: Dictionnary of field key to value
      email:
        description: Email address
        type: string
      ip:
        description: Subscriber's IP address when he/she confirmed list opt-in
        type: string
      listid:
        description: Unique 16 characters ID of the list owner
        type: string
      status:
        description: |
          Status (
            1- Active,
            2- Unconfirmed,
            3- Unsubscribed,
            4- Deleted,
            5- Cleaned because of hard bounce or spam complaint)
        type: integer
    required:
      - listid
      - email
  ContactCustomFieldSchema:
    properties:
      key:
        description: equivalent to html form input name attribute
        type: string
      label:
        description: User friendly label describing the field
        type: string
      required:
        description: Is field required
        type: boolean
      type:
        description: |
          Type (
            1- String / text free form
            2- Numeric / integer or decimal
            3- Date / ISO 8601 format (YYYY/MM/DD)
          )
        type: integer
    required:
      - label
      - key
      - type
  ContactList:
    properties:
      _id:
        description: Unique 16 characters ID
        type: string
      clientid:
        description: Unique 16 characters ID of the client owner
        type: string
      created:
        format: date-time
        type: string
      customfields:
        description: Array of ContactCustomFieldSchema
        items:
          $ref: "#/definitions/ContactCustomFieldSchema"
        type: array
      eventcustomizations:
        description: Array of ContactListEventCustomization
        items:
          $ref: "#/definitions/ContactListEventCustomization"
        type: array
      name:
        description: Name of the contact list
        type: string
  ContactListEventCustomization:
    properties:
      redirecturl:
        description: full url of the destination landing page
        type: string
      type:
        description: |
          Type (
            1- Subscribe confirmation request landing page
            2- Subscribe opt-in landing page
            3- Unsubscribe confirmation landing page
          )
        type: integer
    required:
      - type
  ContactListPage:
    properties:
      page:
        description: Array of ContactList for that page
        items:
          $ref: "#/definitions/ContactList"
        type: array
      total:
        description: Total number of items in query
        type: integer
  ContactListUpdate:
    properties:
      customfields:
        description: Array of ContactCustomFieldSchema
        items:
          $ref: "#/definitions/ContactCustomFieldSchema"
        type: array
      eventcustomizations:
        description: Array of ContactListEventCustomization
        items:
          $ref: "#/definitions/ContactListEventCustomization"
        type: array
      name:
        description: Name of the contact list
        type: string
  ContactPage:
    properties:
      page:
        description: Array of Contact for that page
        items:
          $ref: "#/definitions/Contact"
        type: array
      total:
        description: Total number of items in query
        type: integer
  ContactUpdate:
    properties:
      confirmed:
        description: Date+time subscriber confirmed his/her list opt-in
        format: date-time
        type: string
      customfields:
        description: Dictionnary of field key to value
      email:
        description: Email address
        type: string
      ip:
        description: Subscriber's IP address when he/she confirmed list opt-in
        type: string
      status:
        description: |
          Status (
            1- Active,
            2- Unconfirmed,
            3- Unsubscribed,
            4- Deleted,
            5- Cleaned because of hard bounce or spam complaint)
        type: integer
  NewId:
    properties:
      _id:
        description: The created ressource id
        type: string
  SubscriptionRequest:
    properties:
      confirmed:
        description: Date-time when subscriber opted-in. Required if singleoptin is true.
        format: date-time
        type: string
      email:
        description: Email address of the subscriber
        type: string
      fullname:
        description: |
          Full name (Last name, First Name) of the subscriber
        type: string
      ip:
        description: Origin Ip of the subscriber when he/she opted-in. Required if singleoptin is true.
        type: string
      lang:
        description: |
          ISO 639-1 language code of the subscriber. When lang is one the supported system language, all communication
          will be in this language.
        type: string
      singleoptin:
        description: |
          If true, no email will be sent asking user subscription confirmation. In that case, you must provide
          the confirmation date (confirmed) and origin ip (ip) manually.
        type: boolean
    required:
      - email
