{
  "openapi": "3.1.0",
  "info": {
    "title": "Oblic API",
    "description": "The Oblic API that API keys call: send email, SMS and WhatsApp messages and see what became of each, record your contacts' events, such as their orders, and manage email, SMS and WhatsApp templates, sender identities, contact lists, webhooks and sub-accounts. Send a key as `Authorization: Bearer <key>`. Keys are created under Settings → API Integration, each with its scopes, and an operation names the scopes and key roles it needs in `x-oblic-scopes` and `x-oblic-key-roles`. An answer with a body is the envelope `{\"status\": \"success\", \"data\": …, \"errors\": null}`, or `\"status\": \"error\"` with its errors, each a code (`cd`) and a message; a delete that answers 204 has none.",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://api.oblic.app"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Events",
      "description": "Record what your contacts do in your own systems, such as their orders"
    },
    {
      "name": "Messages",
      "description": "Send email, SMS and WhatsApp through Oblic and track delivery"
    },
    {
      "name": "Reports",
      "description": "What became of the messages sent through Oblic"
    },
    {
      "name": "Keys",
      "description": "The calling key, and a check that a key reaches the API"
    },
    {
      "name": "Accounts",
      "description": "Sub-accounts, one Oblic organization per tenant"
    },
    {
      "name": "Email Templates",
      "description": "An account's email templates"
    },
    {
      "name": "Identities",
      "description": "Sender domains and addresses"
    },
    {
      "name": "SMS",
      "description": "DLT headers and templates, and SMS limits"
    },
    {
      "name": "Webhooks",
      "description": "Delivery-report webhook endpoints"
    },
    {
      "name": "WhatsApp",
      "description": "An account's WhatsApp number and templates"
    },
    {
      "name": "Contact List",
      "description": "APIs for managing external contact lists"
    }
  ],
  "paths": {
    "/external/v1/webhooks/{webhookId}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "A webhook endpoint",
        "description": "Needs an Owner or Admin key with `webhooks:manage`.",
        "operationId": "getWebhook",
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "webhooks:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      },
      "put": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Change an endpoint's URL or event types",
        "description": "Needs an Owner or Admin key with `webhooks:manage`.",
        "operationId": "updateWebhook",
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalWebhookRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "webhooks:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Stop deliveries to an endpoint",
        "description": "Needs an Owner or Admin key with `webhooks:manage`.",
        "operationId": "deleteWebhook",
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "webhooks:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/templates/{id}": {
      "get": {
        "tags": [
          "Email Templates"
        ],
        "summary": "An email template, with its HTML and the variables it takes",
        "description": "Needs a key with `email:send` or `templates:manage`.",
        "operationId": "getEmailTemplate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "email:send",
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      },
      "put": {
        "tags": [
          "Email Templates"
        ],
        "summary": "Replace an email template made from HTML",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "replaceEmailTemplate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEmailTemplateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      },
      "delete": {
        "tags": [
          "Email Templates"
        ],
        "summary": "Delete an email template",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "deleteEmailTemplate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/sms/templates/{id}": {
      "put": {
        "tags": [
          "SMS"
        ],
        "summary": "Change a DLT template",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "updateSmsTemplate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SmsTemplateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      },
      "delete": {
        "tags": [
          "SMS"
        ],
        "summary": "Delete a DLT template",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "deleteSmsTemplate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/sms/templates/{id}/sharing": {
      "put": {
        "tags": [
          "SMS"
        ],
        "summary": "Let none, all, or the named sub-accounts send a template",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "shareSmsTemplate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SmsTemplateSharingRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/sms/senders/{senderId}": {
      "put": {
        "tags": [
          "SMS"
        ],
        "summary": "Add a DLT header, or change whether it is the default",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "saveSmsSender",
        "parameters": [
          {
            "name": "senderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "[A-Za-z]{6}|\\d{6}"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SmsSenderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      },
      "delete": {
        "tags": [
          "SMS"
        ],
        "summary": "Delete a DLT header",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "deleteSmsSender",
        "parameters": [
          {
            "name": "senderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/whatsapp/templates": {
      "get": {
        "tags": [
          "WhatsApp"
        ],
        "summary": "The account's WhatsApp templates, with Meta's review of each",
        "description": "Needs a key with `whatsapp:send` or `templates:manage`.",
        "operationId": "listWhatsAppTemplates",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "whatsapp:send",
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      },
      "post": {
        "tags": [
          "WhatsApp"
        ],
        "summary": "Submit a WhatsApp template to Meta for review",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "createWhatsAppTemplate",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalWhatsAppTemplateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Submitted: the template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/whatsapp/connection": {
      "get": {
        "tags": [
          "WhatsApp"
        ],
        "summary": "The account's connected WhatsApp number",
        "description": "Needs a key with `whatsapp:send` or `templates:manage`.",
        "operationId": "getWhatsAppConnection",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "whatsapp:send",
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      },
      "post": {
        "tags": [
          "WhatsApp"
        ],
        "summary": "Connect the account's WhatsApp Business number, or replace it",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "connectWhatsApp",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WhatsAppConnectionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      },
      "delete": {
        "tags": [
          "WhatsApp"
        ],
        "summary": "Disconnect the account's WhatsApp number",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "disconnectWhatsApp",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "204": {
            "description": "Disconnected"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "The organization's webhook endpoints",
        "description": "Needs an Owner or Admin key with `webhooks:manage`.",
        "operationId": "listWebhooks",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "webhooks:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Register a webhook endpoint, or find the one for the same URL",
        "description": "Needs an Owner or Admin key with `webhooks:manage`.",
        "operationId": "createWebhook",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalWebhookRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "webhooks:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/webhooks/deliveries/{deliveryId}/replay": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Queue a failed delivery again",
        "description": "Needs an Owner or Admin key with `webhooks:manage`.",
        "operationId": "replayDelivery",
        "parameters": [
          {
            "name": "deliveryId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "202": {
            "description": "Queued again: the delivery, now pending",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "webhooks:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/templates": {
      "get": {
        "tags": [
          "Email Templates"
        ],
        "summary": "The account's email templates, newest first",
        "description": "Needs a key with `email:send` or `templates:manage`.",
        "operationId": "listEmailTemplates",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "[0-9]{1,12}~[A-Za-z0-9]{18}"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25,
              "maximum": 100,
              "minimum": 1
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "email:send",
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      },
      "post": {
        "tags": [
          "Email Templates"
        ],
        "summary": "Make an email template from HTML",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "createEmailTemplate",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEmailTemplateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Made: the template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/sms/templates": {
      "get": {
        "tags": [
          "SMS"
        ],
        "summary": "The account's DLT templates",
        "description": "Needs a key with `sms:send` or `templates:manage`.",
        "operationId": "listSmsTemplates",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "sms:send",
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      },
      "post": {
        "tags": [
          "SMS"
        ],
        "summary": "Add a DLT template",
        "description": "Needs an Owner or Admin key with `templates:manage`.",
        "operationId": "createSmsTemplate",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SmsTemplateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Added: the template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/messages/whatsapp": {
      "post": {
        "tags": [
          "Messages"
        ],
        "summary": "Send an approved WhatsApp template, or a reply within 24 hours",
        "description": "Needs a key with `whatsapp:send`.",
        "operationId": "sendWhatsApp",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalWhatsAppRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Queued: the message's id and status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "whatsapp:send"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/messages/sms": {
      "post": {
        "tags": [
          "Messages"
        ],
        "summary": "Send an SMS that matches one of the account's DLT templates",
        "description": "Needs a key with `sms:send`.",
        "operationId": "sendSms",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalSmsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Queued: the message's id and status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "sms:send"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/messages/email": {
      "post": {
        "tags": [
          "Messages"
        ],
        "summary": "Send an email from a verified sender, of its own HTML or by a template",
        "description": "Needs a key with `email:send`.",
        "operationId": "sendEmail",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEmailRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Queued: the message's id and status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "email:send"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/identities": {
      "get": {
        "tags": [
          "Identities"
        ],
        "summary": "The sender domains and addresses, and whether each is verified",
        "description": "Needs a key with `email:send` or `identities:manage`.",
        "operationId": "listIdentities",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "email:send",
          "identities:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      },
      "post": {
        "tags": [
          "Identities"
        ],
        "summary": "Add a sender domain or address, to be verified",
        "description": "Needs a key with `identities:manage`.",
        "operationId": "createIdentity",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalIdentityRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "identities:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/events": {
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "Record up to 100 of your contacts' events, such as orders and abandoned carts",
        "description": "Needs a key with `events:write`.",
        "operationId": "recordEvents",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalEventsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Kept: how many were stored, were duplicates and are not matched yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "events:write"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/accounts": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "summary": "The organization's sub-accounts",
        "description": "Needs an Owner or Admin key with `accounts:manage`.",
        "operationId": "listSubAccounts",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "accounts:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      },
      "post": {
        "tags": [
          "Accounts"
        ],
        "summary": "Create a sub-account, or find it by its externalId, with an API key of its own",
        "description": "Needs an Owner or Admin key with `accounts:manage`.",
        "operationId": "createSubAccount",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalAccountRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "accounts:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/contact-list/v1/{contactListId}/add": {
      "post": {
        "tags": [
          "Contact List"
        ],
        "summary": "Add contacts to a contact list",
        "description": "Needs a key with `contacts:manage`.",
        "operationId": "addContactsToList",
        "parameters": [
          {
            "name": "contactListId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "startJourneys",
            "in": "query",
            "description": "Whether the contacts that join the list start the journeys a join starts: off unless asked",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ExternalContactListAddRequest"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "contacts:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/contact-list/v1/add": {
      "post": {
        "tags": [
          "Contact List"
        ],
        "summary": "Make a contact list",
        "description": "Needs a key with `contacts:manage`.",
        "operationId": "createContactList",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactListRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "contacts:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/whatsapp/recipients/{number}": {
      "get": {
        "tags": [
          "WhatsApp"
        ],
        "summary": "What the account may send a number now",
        "description": "Needs a key with `whatsapp:send` or `templates:manage`.",
        "operationId": "getWhatsAppRecipient",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "whatsapp:send",
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/webhooks/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "The deliveries that failed, most recently failed first",
        "description": "Needs an Owner or Admin key with `webhooks:manage`.",
        "operationId": "listFailedDeliveries",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "failed",
              "pattern": "failed"
            }
          },
          {
            "name": "webhookId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 40,
              "minLength": 0
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "[0-9]{1,18}~[0-9]{1,19}"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25,
              "maximum": 100,
              "minimum": 1
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "webhooks:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/v1/sms/senders": {
      "get": {
        "tags": [
          "SMS"
        ],
        "summary": "The account's DLT headers",
        "description": "Needs a key with `sms:send` or `templates:manage`.",
        "operationId": "listSmsSenders",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "sms:send",
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/sms/account": {
      "get": {
        "tags": [
          "SMS"
        ],
        "summary": "The account's SMS limits, and what it has sent this month",
        "description": "Needs a key with `sms:send` or `templates:manage`.",
        "operationId": "getSmsAccount",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "sms:send",
          "templates:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/reports/summary": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "What became of the messages sent in a period, by channel and status",
        "description": "Needs a key with `messages:read`.",
        "operationId": "getReportSummary",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "messages:read"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/messages": {
      "get": {
        "tags": [
          "Messages"
        ],
        "summary": "The messages sent through the API, newest first",
        "description": "Needs a key with `messages:read`.",
        "operationId": "listMessages",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "[0-9]{1,15}~[A-Za-z0-9]{18}"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25,
              "maximum": 100,
              "minimum": 1
            }
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "email|sms|whatsapp"
              }
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "queued|sent|delivered|read|bounced|skipped|failed"
              }
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "messages:read"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/messages/{messageId}": {
      "get": {
        "tags": [
          "Messages"
        ],
        "summary": "A message sent through the API, and what became of it",
        "description": "Needs a key with `messages:read`.",
        "operationId": "getMessage",
        "parameters": [
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "messages:read"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/key": {
      "get": {
        "tags": [
          "Keys"
        ],
        "summary": "The calling key: its name, role and scopes, and what it can do now",
        "description": "Needs any key.",
        "operationId": "getKey",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/info": {
      "get": {
        "tags": [
          "Keys"
        ],
        "summary": "The organization the key acts for",
        "description": "Needs any key.",
        "operationId": "getInfo",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/health": {
      "get": {
        "tags": [
          "Keys"
        ],
        "summary": "Checks that a key reaches the API",
        "description": "Needs an Owner or Admin key, with any scopes.",
        "operationId": "getHealth",
        "parameters": [
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    },
    "/external/contact-list/v1/{nextIndex}/{limit}": {
      "get": {
        "tags": [
          "Contact List"
        ],
        "summary": "The account's contact lists, a page at a time",
        "description": "Needs a key with `contacts:manage`.",
        "operationId": "listContactLists",
        "parameters": [
          {
            "name": "nextIndex",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "contacts:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/identities/{identityId}": {
      "delete": {
        "tags": [
          "Identities"
        ],
        "summary": "Delete a sender identity",
        "description": "Needs a key with `identities:manage`.",
        "operationId": "deleteIdentity",
        "parameters": [
          {
            "name": "identityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "identities:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN",
          "USER"
        ]
      }
    },
    "/external/v1/accounts/{accountId}": {
      "delete": {
        "tags": [
          "Accounts"
        ],
        "summary": "Deactivate a sub-account and revoke its keys",
        "description": "Needs an Owner or Admin key with `accounts:manage`.",
        "operationId": "deactivateSubAccount",
        "parameters": [
          {
            "name": "accountId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/OnBehalfOf"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Out"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-oblic-scopes": [
          "accounts:manage"
        ],
        "x-oblic-key-roles": [
          "OWNER",
          "ADMIN"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ExternalWebhookRequest": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 2048,
            "minLength": 0
          },
          "eventTypes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "minItems": 0
          }
        },
        "required": [
          "url"
        ]
      },
      "Out": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "data": {},
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/errors"
            }
          }
        }
      },
      "errors": {
        "type": "object",
        "properties": {
          "cd": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ExternalEmailTemplateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "subject": {
            "type": "string",
            "maxLength": 1023,
            "minLength": 0
          },
          "html": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "html",
          "name"
        ]
      },
      "SmsTemplateRequest": {
        "type": "object",
        "properties": {
          "templateId": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\d{1,32}"
          },
          "senderId": {
            "type": "string",
            "minLength": 1,
            "pattern": "[A-Za-z]{6}|\\d{6}"
          },
          "name": {
            "type": "string",
            "maxLength": 80,
            "minLength": 0
          },
          "body": {
            "type": "string",
            "maxLength": 2000,
            "minLength": 0
          },
          "variableKeys": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "pattern": "[A-Za-z0-9_]{1,30}"
            },
            "maxItems": 30,
            "minItems": 0
          },
          "type": {
            "type": "string",
            "minLength": 1,
            "pattern": "transactional|service_implicit|service_explicit|promotional"
          },
          "unicode": {
            "type": "boolean"
          },
          "active": {
            "type": "boolean"
          }
        },
        "required": [
          "body",
          "name",
          "senderId",
          "templateId",
          "type"
        ]
      },
      "SmsTemplateSharingRequest": {
        "type": "object",
        "properties": {
          "scope": {
            "type": "string",
            "minLength": 1,
            "pattern": "none|all|selected"
          },
          "accounts": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 255,
              "minLength": 0
            },
            "maxItems": 1000,
            "minItems": 0
          }
        },
        "required": [
          "scope"
        ]
      },
      "SmsSenderRequest": {
        "type": "object",
        "properties": {
          "isDefault": {
            "type": "boolean"
          }
        }
      },
      "ButtonsItem": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "example": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ComponentsItem": {
        "type": "object",
        "properties": {
          "buttons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ButtonsItem"
            }
          },
          "type": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "example": {
            "$ref": "#/components/schemas/Example"
          },
          "format": {
            "type": "string"
          }
        }
      },
      "Example": {
        "type": "object",
        "properties": {
          "body_text": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "header_text": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "header_handle": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ExternalWhatsAppTemplateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "pattern": "[a-z0-9_]{1,200}"
          },
          "language": {
            "type": "string",
            "pattern": "[a-z]{2}(_[A-Z]{2})?"
          },
          "category": {
            "type": "string",
            "minLength": 1,
            "pattern": "MARKETING|UTILITY|AUTHENTICATION"
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComponentsItem"
            },
            "minItems": 1
          }
        },
        "required": [
          "category",
          "components",
          "name"
        ]
      },
      "WhatsAppConnectionRequest": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1
          },
          "phoneNumberId": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\d{1,30}"
          },
          "wabaId": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\d{1,30}"
          },
          "businessId": {
            "type": "string",
            "pattern": "\\d{1,30}"
          },
          "pin": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\d{6}"
          }
        },
        "required": [
          "code",
          "phoneNumberId",
          "pin",
          "wabaId"
        ]
      },
      "ExternalWhatsAppRequest": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "minLength": 1
          },
          "template": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 1024,
              "minLength": 0
            },
            "maxItems": 30,
            "minItems": 0
          },
          "headerVariables": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 1024,
              "minLength": 0
            },
            "maxItems": 5,
            "minItems": 0
          },
          "headerMediaUrl": {
            "type": "string",
            "maxLength": 2048,
            "minLength": 0
          },
          "text": {
            "type": "string",
            "maxLength": 4096,
            "minLength": 0
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "to"
        ]
      },
      "ExternalSmsRequest": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "maxLength": 20,
            "minLength": 0
          },
          "text": {
            "type": "string",
            "maxLength": 2000,
            "minLength": 0
          },
          "templateId": {
            "type": "string",
            "pattern": "\\d{1,32}"
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 30,
            "minItems": 0
          },
          "senderId": {
            "type": "string",
            "maxLength": 11,
            "minLength": 0
          },
          "purpose": {
            "type": "string",
            "pattern": "otp|transactional|promotional"
          },
          "unicode": {
            "type": "boolean"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "to"
        ]
      },
      "Attachment": {
        "type": "object",
        "properties": {
          "fileName": {
            "type": "string",
            "maxLength": 255,
            "minLength": 0,
            "pattern": "[^/\\\\\"\\r\\n]*"
          },
          "content": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "content",
          "fileName"
        ]
      },
      "ExternalEmailRequest": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "format": "email",
            "maxLength": 255,
            "minLength": 0
          },
          "fromName": {
            "type": "string",
            "maxLength": 255,
            "minLength": 0,
            "pattern": "[^<>\"\\r\\n]*"
          },
          "to": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email",
              "minLength": 1
            },
            "maxItems": 50,
            "minItems": 0
          },
          "cc": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email",
              "minLength": 1
            },
            "maxItems": 50,
            "minItems": 0
          },
          "bcc": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email",
              "minLength": 1
            },
            "maxItems": 50,
            "minItems": 0
          },
          "replyTo": {
            "type": "string",
            "format": "email"
          },
          "subject": {
            "type": "string",
            "maxLength": 1023,
            "minLength": 0
          },
          "html": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Attachment"
            },
            "maxItems": 10,
            "minItems": 0
          },
          "templateId": {
            "type": "string",
            "pattern": "[A-Za-z0-9]{18}"
          },
          "variables": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "ExternalIdentityRequest": {
        "type": "object",
        "properties": {
          "identityType": {
            "type": "string",
            "minLength": 1,
            "pattern": "Domain|Email"
          },
          "identity": {
            "type": "string",
            "maxLength": 255,
            "minLength": 0,
            "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}|[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 255,
            "minLength": 0
          },
          "displayName": {
            "type": "string",
            "maxLength": 255,
            "minLength": 0,
            "pattern": "[^<>\"\\r\\n]*"
          },
          "replyTo": {
            "type": "string",
            "format": "email",
            "maxLength": 255,
            "minLength": 0
          }
        },
        "required": [
          "displayName",
          "identity",
          "identityType"
        ]
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 128,
            "minLength": 0,
            "pattern": "\\S+"
          },
          "type": {
            "type": "string",
            "enum": [
              "order.placed",
              "order.paid",
              "order.fulfilled",
              "order.cancelled",
              "order.refunded",
              "checkout.started",
              "cart.abandoned",
              "product.viewed",
              "customer.created"
            ],
            "minLength": 1
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 255,
            "minLength": 0
          },
          "phone": {
            "type": "string",
            "pattern": "\\+?[0-9][0-9 ()-]{5,30}"
          },
          "value": {
            "type": "number"
          },
          "currency": {
            "type": "string",
            "pattern": "[A-Z]{3}"
          },
          "properties": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "id",
          "occurredAt",
          "type"
        ]
      },
      "ExternalEventsRequest": {
        "type": "object",
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            },
            "maxItems": 100,
            "minItems": 1
          }
        },
        "required": [
          "events"
        ]
      },
      "ExternalAccountRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 511,
            "minLength": 0
          },
          "externalId": {
            "type": "string",
            "maxLength": 100,
            "minLength": 0,
            "pattern": "[A-Za-z0-9_.:-]+"
          },
          "issueKey": {
            "type": "boolean"
          }
        },
        "required": [
          "externalId",
          "name"
        ]
      },
      "ExternalContactListAddRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "pattern": "^[a-zA-Z0-9 ',\\-]+$"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "phone": {
            "type": "string",
            "pattern": "^$|^[0-9]{10,}$"
          },
          "whatsApp": {
            "type": "string",
            "pattern": "^$|^[0-9]{10,15}$"
          },
          "source": {
            "type": "string"
          },
          "atLeastOneIdentifierPresent": {
            "type": "boolean"
          }
        },
        "required": [
          "name"
        ]
      },
      "ContactListRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactVo"
            }
          }
        },
        "required": [
          "name"
        ]
      },
      "ContactVo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "pattern": "^[a-zA-Z0-9\\s,.'\\-#/]+$"
          },
          "organizationId": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdBy": {
            "type": "string"
          },
          "updatedBy": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "phone": {
            "type": "string",
            "pattern": "^$|^\\d{1,3}[-\\s]?\\(?\\d+\\)?[-\\s]?\\d{4,}$"
          },
          "whatsApp": {
            "type": "string",
            "pattern": "^$|^\\d{1,3}[-\\s]?\\(?\\d+\\)?[-\\s]?\\d{4,}$"
          },
          "telegram": {
            "type": "string"
          },
          "emailPermission": {
            "type": "boolean"
          },
          "birthday": {
            "type": "string"
          },
          "customFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomField"
            }
          }
        },
        "required": [
          "name"
        ]
      },
      "CustomField": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1
          },
          "dataType": {
            "type": "string",
            "minLength": 1
          },
          "value": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "dataType",
          "label",
          "value"
        ]
      }
    },
    "responses": {
      "Error": {
        "description": "Refused: `status` is `error`, and `errors` says why, each with a code (`cd`) and a message. A refusal before the route runs, for the key, its address, its scopes or the sub-account it names, leaves `data` out.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Out"
            }
          }
        }
      }
    },
    "parameters": {
      "OnBehalfOf": {
        "name": "X-Oblic-On-Behalf-Of",
        "in": "header",
        "description": "A sub-account's `externalId`: the request runs as that sub-account, as though made with its own key. 404 `ACCOUNT_NOT_FOUND` when the key's organization has no active sub-account of that id.",
        "required": false,
        "schema": {
          "type": "string"
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "description": "An API key, created under Settings → API Integration and shown once. A key from an address the organization's IP allowlist does not hold is refused.",
        "scheme": "bearer",
        "bearerFormat": "API key"
      }
    }
  }
}
