{
  "swagger": "2.0",
  "info": {
    "title": "ToucanText API",
    "description": "Send and Receive messages using the ToucanText API",
    "termsOfService": "https://www.toucantext.com/terms-of-use",
    "contact": {
      "name": "Contact",
      "url": "https://www.toucantext.com/contact/"
    },
    "license": {
      "name": "ToucanText Licence",
      "url": "https://www.toucantext.com/terms-of-use"
    },
    "version": "v1"
  },
  "host": "ttapi.toucantext.com",
  "schemes": [
    "https"
  ],
  "paths": {
    "/Message": {
      "get": {
        "tags": [
          "Message"
        ],
        "summary": "Retrieve messages and delivery reports.",
        "description": "Reads from the account's inbound queue. Set AckMessages to True to acknowledge\r\nretrieved entries; acknowledged entries may no longer be returned on subsequent calls.\r\nAuthentication uses the ToucanText account ID and API token via HTTP Basic authentication.",
        "operationId": "RetrieveMessages",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "MaxMessageCount",
            "description": "Maximum number of entries to retrieve in this call.",
            "type": "string"
          },
          {
            "in": "query",
            "name": "AckMessages",
            "description": "Acknowledge retrieved entries: \"True\" for yes or \"False\" for no. Use False for testing",
            "type": "string"
          },
          {
            "in": "query",
            "name": "DestAddr",
            "description": "(Optional) Used to restrict download to specified inbound number.",
            "type": "string"
          },
          {
            "in": "query",
            "name": "DlrsOnly",
            "description": "(Optional) Whether to retrieve only delivery reports: \"True\" for yes or \"False\" for no.",
            "type": "string"
          },
          {
            "in": "query",
            "name": "MessagesOnly",
            "description": "(Optional) Whether to retrieve only inbound messages: \"True\" for yes or \"False\" for no.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "The retrieval status and any messages or delivery reports returned by the service.",
            "schema": {
              "$ref": "#/definitions/RetrieveMessageResponse"
            }
          },
          "401": {
            "description": "Authentication is required.",
            "schema": {
              "$ref": "#/definitions/ProblemDetails"
            }
          },
          "403": {
            "description": "The authenticated caller does not have the required scope.",
            "schema": {
              "$ref": "#/definitions/ProblemDetails"
            }
          }
        }
      },
      "post": {
        "tags": [
          "Message"
        ],
        "summary": "Send a message to one or more recipients.",
        "description": "Authentication uses the ToucanText account ID and API token via HTTP Basic authentication.\r\nInspect the results array for the message status and status text returned by the sending service.",
        "operationId": "SendMessage",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "description": "The sender, recipients, message text and optional sending parameters.",
            "schema": {
              "$ref": "#/definitions/SendMessageParameters"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Message results and the account balance returned by the sending service.",
            "schema": {
              "$ref": "#/definitions/SendMessageResponse"
            }
          },
          "400": {
            "description": "The JSON request body is missing or invalid.",
            "schema": {
              "$ref": "#/definitions/ValidationProblemDetails"
            }
          },
          "401": {
            "description": "Authentication is required.",
            "schema": {
              "$ref": "#/definitions/ProblemDetails"
            }
          },
          "403": {
            "description": "The authenticated caller does not have the required scope.",
            "schema": {
              "$ref": "#/definitions/ProblemDetails"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "MessageList": {
      "type": "object",
      "properties": {
        "mbStorageId": {
          "format": "int32",
          "type": "integer"
        },
        "messageId": {
          "format": "int32",
          "type": "integer"
        },
        "accountName": {
          "type": "string"
        },
        "sourceAddr": {
          "type": "string"
        },
        "destAddr": {
          "type": "string"
        },
        "arrivalTimeUTC": {
          "format": "date-time",
          "description": "Time the entry arrived, in UTC.",
          "type": "string"
        },
        "messageContents": {
          "type": "string"
        },
        "dlr": {
          "description": "Whether this entry is a delivery report.",
          "type": "boolean"
        },
        "dlrOriginalMessageId": {
          "format": "int32",
          "description": "Original message identifier associated with a delivery report.",
          "type": "integer"
        },
        "messageParameters": {
          "description": "Additional key/value parameters associated with the entry.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/MessageParameter"
          }
        }
      }
    },
    "MessageParameter": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      }
    },
    "ProblemDetails": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "status": {
          "format": "int32",
          "type": "integer"
        },
        "detail": {
          "type": "string"
        },
        "instance": {
          "type": "string"
        }
      },
      "additionalProperties": { }
    },
    "Result": {
      "type": "object",
      "properties": {
        "status": {
          "description": "Status code returned by the sending service.",
          "type": "string"
        },
        "msgid": {
          "description": "Message identifier returned by the sending service.",
          "type": "string"
        },
        "statustext": {
          "description": "Text describing the message status.",
          "type": "string"
        }
      }
    },
    "RetrieveMessageResponse": {
      "type": "object",
      "properties": {
        "accountName": {
          "description": "Account associated with the retrieved entries.",
          "type": "string"
        },
        "statusCode": {
          "format": "int32",
          "description": "Retrieval status code reported by the service.",
          "type": "integer"
        },
        "statusMessage": {
          "description": "Text describing the retrieval status.",
          "type": "string"
        },
        "messageList": {
          "description": "Inbound messages and/or delivery reports returned by the service.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/MessageList"
          }
        }
      }
    },
    "SendMessageParameters": {
      "description": "Parameters used to send a message.",
      "type": "object",
      "properties": {
        "senderID": {
          "description": "Sender address. This can either be an 11 character pre-approved alpha sender or an inbound number",
          "type": "string"
        },
        "recipientList": {
          "description": "List of Recipients for the message \r\nEach recipient can be in the form 44xxxxnnnnnn or in the form 07xxxnnnnnn",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "messageDetail": {
          "description": "The message contents for the message",
          "type": "string"
        },
        "optionalParameters": {
          "description": "Optional sending-service parameters, supplied as an array of key/value objects.\r\nEach pair is forwarded to the sending service without renaming its key.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/StringStringKeyValuePair"
          }
        }
      }
    },
    "SendMessageResponse": {
      "type": "object",
      "properties": {
        "results": {
          "description": "Message results returned by the sending service. Check each status and status text.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Result"
          }
        },
        "balance": {
          "description": "Account balance returned by the sending service, represented as a string.",
          "type": "string"
        }
      }
    },
    "StringStringKeyValuePair": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      }
    },
    "ValidationProblemDetails": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "status": {
          "format": "int32",
          "type": "integer"
        },
        "detail": {
          "type": "string"
        },
        "instance": {
          "type": "string"
        },
        "errors": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "additionalProperties": { }
    }
  },
  "securityDefinitions": {
    "Basic": {
      "type": "basic",
      "description": "Use your ToucanText account ID as the username and API token as the password."
    }
  },
  "security": [
    {
      "Basic": [ ]
    }
  ]
}