{
    "openapi": "3.1.0",
    "info": {
        "title": "Email Delivery Platform API \u2014 v2 (Multi-Channel)",
        "version": "v2",
        "description": "WhatsApp, Push and OTP sending, campaigns and templates. Email stays on /api/v1 \u2014 see that spec for the original contract."
    },
    "servers": [
        {
            "url": "http://127.0.0.1:8226/api/v2"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Tenant or master API key \u2014 same key as /api/v1."
            }
        },
        "parameters": {
            "SubAccount": {
                "name": "X-Sub-Account",
                "in": "header",
                "required": false,
                "schema": {
                    "type": "string"
                },
                "description": "Reseller: act as a specific merchant."
            },
            "IdempotencyKey": {
                "name": "Idempotency-Key",
                "in": "header",
                "required": false,
                "schema": {
                    "type": "string"
                },
                "description": "Retry-safe key \u2014 a retry with the same key replays the original response instead of re-sending. Required (not optional) on the OTP send endpoint."
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/messages/whatsapp/send": {
            "post": {
                "summary": "Send a single WhatsApp message (approved template required)",
                "tags": [
                    "WhatsApp"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    },
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "to": {
                                        "type": "string",
                                        "description": "E.164 phone number."
                                    },
                                    "template_deployment_id": {
                                        "type": "integer"
                                    },
                                    "variables": {
                                        "type": "object"
                                    },
                                    "customer_id": {
                                        "type": "string"
                                    },
                                    "external_id": {
                                        "type": "string",
                                        "description": "Idempotent per-message id \u2014 echoed on webhooks."
                                    },
                                    "metadata": {
                                        "type": "object"
                                    }
                                },
                                "required": [
                                    "to",
                                    "template_deployment_id"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Sent"
                    },
                    "402": {
                        "description": "Blocked \u2014 insufficient balance"
                    }
                }
            }
        },
        "/messages/whatsapp/batch": {
            "post": {
                "summary": "Send WhatsApp to multiple recipients",
                "tags": [
                    "WhatsApp"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Accepted"
                    }
                }
            }
        },
        "/messages/whatsapp/{id}/status": {
            "get": {
                "summary": "WhatsApp message delivery status",
                "tags": [
                    "WhatsApp"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/messages/whatsapp/{id}/retry": {
            "post": {
                "summary": "Retry a failed WhatsApp message",
                "tags": [
                    "WhatsApp"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/whatsapp/otp/send": {
            "post": {
                "summary": "Send a WhatsApp OTP",
                "description": "Idempotency-Key is MANDATORY here (422 without it) \u2014 a blind retry without one could deliver the same code twice.",
                "tags": [
                    "WhatsApp"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    },
                    {
                        "$ref": "#/components/parameters/IdempotencyKey",
                        "required": true
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "phone": {
                                        "type": "string"
                                    },
                                    "template_deployment_id": {
                                        "type": "integer"
                                    },
                                    "template_variables": {
                                        "type": "object"
                                    },
                                    "expires_in_seconds": {
                                        "type": "integer",
                                        "description": "30-3600, default per template."
                                    }
                                },
                                "required": [
                                    "phone",
                                    "template_deployment_id"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Sent"
                    },
                    "422": {
                        "description": "Missing Idempotency-Key header"
                    }
                }
            }
        },
        "/whatsapp/templates": {
            "get": {
                "summary": "List WhatsApp templates",
                "tags": [
                    "WhatsApp Templates"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "post": {
                "summary": "Create a WhatsApp template draft",
                "tags": [
                    "WhatsApp Templates"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "category": {
                                        "type": "string",
                                        "enum": [
                                            "marketing",
                                            "utility",
                                            "transactional",
                                            "authentication"
                                        ]
                                    },
                                    "language": {
                                        "type": "string"
                                    },
                                    "components": {
                                        "type": "object"
                                    }
                                },
                                "required": [
                                    "name",
                                    "category",
                                    "language"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            }
        },
        "/whatsapp/templates/{id}/publish": {
            "post": {
                "summary": "Submit a template to Meta for review",
                "tags": [
                    "WhatsApp Templates"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/whatsapp/templates/{id}/deploy": {
            "post": {
                "summary": "Deploy an approved template to a connection",
                "tags": [
                    "WhatsApp Templates"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/campaigns/whatsapp": {
            "get": {
                "summary": "List WhatsApp campaigns",
                "tags": [
                    "WhatsApp Campaigns"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "post": {
                "summary": "Create a WhatsApp campaign",
                "tags": [
                    "WhatsApp Campaigns"
                ],
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            }
        },
        "/campaigns/whatsapp/{id}/recipients/batch": {
            "post": {
                "summary": "Append recipients to a campaign (ingest, before seal)",
                "tags": [
                    "WhatsApp Campaigns"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/campaigns/whatsapp/{id}/seal": {
            "post": {
                "summary": "Seal a campaign's recipient list (no more appends after this)",
                "tags": [
                    "WhatsApp Campaigns"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/campaigns/whatsapp/{id}/send": {
            "post": {
                "summary": "Send a sealed WhatsApp campaign",
                "tags": [
                    "WhatsApp Campaigns"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Sending or partial"
                    },
                    "402": {
                        "description": "Blocked \u2014 insufficient balance"
                    }
                }
            }
        },
        "/campaigns/whatsapp/{id}/report": {
            "get": {
                "summary": "WhatsApp campaign delivery report, incl. failure-category breakdown",
                "tags": [
                    "WhatsApp Campaigns"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/activity/whatsapp": {
            "get": {
                "summary": "Per-message WhatsApp activity feed",
                "tags": [
                    "WhatsApp"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/activity/whatsapp/summary": {
            "get": {
                "summary": "WhatsApp activity summary (rates, category breakdown)",
                "tags": [
                    "WhatsApp"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/push/send": {
            "post": {
                "summary": "Send a single transactional push notification",
                "description": "Targets a person by email OR phone (whichever you have) \u2014 delivered to every browser they're subscribed from.",
                "tags": [
                    "Push"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    },
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "One of email/phone required."
                                    },
                                    "phone": {
                                        "type": "string"
                                    },
                                    "title": {
                                        "type": "string"
                                    },
                                    "body": {
                                        "type": "string"
                                    },
                                    "click_url": {
                                        "type": "string",
                                        "format": "uri"
                                    },
                                    "icon_url": {
                                        "type": "string",
                                        "format": "uri"
                                    },
                                    "image_url": {
                                        "type": "string",
                                        "format": "uri"
                                    },
                                    "ttl_seconds": {
                                        "type": "integer",
                                        "description": "60-86400."
                                    },
                                    "external_id": {
                                        "type": "string"
                                    },
                                    "customer_id": {
                                        "type": "string"
                                    },
                                    "metadata": {
                                        "type": "object"
                                    }
                                },
                                "required": [
                                    "title",
                                    "body"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Per-subscription results \u2014 check each result's reason for billing/delivery failures, this endpoint does not use HTTP status for that."
                    },
                    "404": {
                        "description": "No customer matches that email/phone"
                    },
                    "410": {
                        "description": "Push disabled for this account"
                    }
                }
            }
        },
        "/push/campaigns": {
            "get": {
                "summary": "List push campaigns",
                "tags": [
                    "Push Campaigns"
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "post": {
                "summary": "Create a push campaign",
                "tags": [
                    "Push Campaigns"
                ],
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            }
        },
        "/push/campaigns/{id}/send": {
            "post": {
                "summary": "Send a push campaign",
                "tags": [
                    "Push Campaigns"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Sending or partial"
                    }
                }
            }
        },
        "/push/campaigns/{id}/report": {
            "get": {
                "summary": "Push campaign delivery report",
                "tags": [
                    "Push Campaigns"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/push/templates": {
            "get": {
                "summary": "List push templates",
                "tags": [
                    "Push Templates"
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "post": {
                "summary": "Create a push template",
                "tags": [
                    "Push Templates"
                ],
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            }
        },
        "/push/analytics": {
            "get": {
                "summary": "Push funnel analytics (views, clicks, conversions)",
                "tags": [
                    "Push"
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/activity/push": {
            "get": {
                "summary": "Per-notification push activity feed",
                "tags": [
                    "Push"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/activity/push/summary": {
            "get": {
                "summary": "Push activity summary",
                "tags": [
                    "Push"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubAccount"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    }
}