{ "openapi": "3.0.0", "info": { "title": "Notify API", "description": "API documentation for Notify email services", "version": "1.0.0", "contact": { "name": "Notify Support", "url": "https://notify.cx/support" } }, "servers": [ { "url": "https://notify.cx", "description": "Live Public API" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string" }, "success": { "type": "boolean", "default": false } } }, "SendEmailRequest": { "type": "object", "required": [ "subject", "to", "from" ], "description": "Provide exactly one body field among html, message, or text (priority if multiple: message → html → text). Prefer html in new integrations.", "properties": { "subject": { "type": "string", "description": "Email subject line", "example": "Welcome to our service" }, "to": { "type": "string", "format": "email", "description": "Recipient email address", "example": "user@example.com" }, "html": { "type": "string", "description": "HTML or plain-text body (preferred alias). Mapped to message server-side.", "example": "

Thanks for signing up.

" }, "message": { "type": "string", "description": "Canonical body field — plain text or HTML (max 100000 characters)", "example": "Thank you for signing up to our service. We are excited to have you on board!" }, "text": { "type": "string", "description": "Plain-text (or HTML) body alias. Mapped to message server-side." }, "from": { "type": "string", "description": "Required sender. Bare email or Name . Verified apex covers subdomains. Use sent-with@mail.notify.cx for the Notify platform sender.", "example": "Circuit " } }, "example": { "to": "user@example.com", "subject": "Welcome to our service", "html": "

Thank you for signing up to our service. We are excited to have you on board!

", "from": "Circuit " } }, "SendEmailResponse": { "type": "object", "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } } }, "CreateWebhookRequest": { "type": "object", "required": [ "webhookUrl", "subscribedEvents", "domainId" ], "properties": { "webhookUrl": { "type": "string", "format": "uri", "description": "URL to send webhook events to", "example": "https://your-app.com/api/email-webhooks" }, "subscribedEvents": { "type": "array", "items": { "type": "string", "enum": [ "Delivery", "DeliveryDelay", "Bounce", "Complaint", "Click", "Open", "Send" ] }, "description": "Events to subscribe to", "example": [ "Delivery", "Bounce", "Open" ] }, "domainId": { "type": "string", "format": "uuid", "description": "Verified sending domain UUID. Events fire for this domain and its subdomains." } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "webhookUrl": { "type": "string", "format": "uri" }, "subscribedEvents": { "type": "array", "items": { "type": "string" } }, "domainId": { "type": "string", "format": "uuid" }, "domain": { "type": "string", "description": "Verified domain name" }, "createdAt": { "type": "string", "format": "date-time" } } }, "CreateWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Webhook" } } }, "TestWebhookRequest": { "type": "object", "required": [ "webhookUrl", "eventType" ], "properties": { "webhookUrl": { "type": "string", "format": "uri", "description": "URL to send test webhook event to", "example": "https://your-app.com/api/email-webhooks" }, "eventType": { "type": "string", "enum": [ "Delivery", "DeliveryDelay", "Bounce", "Complaint", "Click", "Open", "Send" ], "description": "Type of event to test", "example": "Delivery" } } }, "TestWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/email/send": { "post": { "summary": "Send an email immediately", "description": "Sends an email immediately to the specified recipient. Canonical public send endpoint.", "operationId": "sendEmail", "tags": [ "Email" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } } }, "responses": { "200": { "description": "Email sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - API key is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/webhooks": { "get": { "summary": "List webhook subscriptions", "description": "Lists all webhook subscriptions for the authenticated user. Each item includes domainId and domain.", "operationId": "listWebhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook list" }, "401": { "description": "Unauthorized" } } }, "post": { "summary": "Create a webhook subscription", "description": "Creates a domain-scoped webhook. domainId must be a verified sending domain; events cover that domain and subdomains.", "operationId": "createWebhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - limit reached for current plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/webhooks/{id}": { "delete": { "summary": "Delete a webhook subscription", "description": "Deletes an existing webhook subscription", "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the webhook to delete" } ], "responses": { "200": { "description": "Webhook deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - webhook belongs to another user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/webhooks/test": { "post": { "summary": "Test a webhook", "description": "Sends a test event to a webhook URL", "operationId": "testWebhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookRequest" } } } }, "responses": { "200": { "description": "Test webhook sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookResponse" } } } }, "400": { "description": "Bad request or webhook endpoint returned an error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request timeout - webhook endpoint did not respond in time", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }