{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "useSend API" }, "servers": [{ "url": "https://app.usesend.com/api" }], "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer" } }, "schemas": {}, "parameters": {} }, "paths": { "/v1/domains": { "get": { "responses": { "200": { "description": "Retrieve domains accessible by the API key", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the domain", "example": 1 }, "name": { "type": "string", "description": "The name of the domain", "example": "example.com" }, "teamId": { "type": "number", "description": "The ID of the team", "example": 1 }, "status": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE" ] }, "region": { "type": "string", "default": "us-east-1" }, "clickTracking": { "type": "boolean", "default": false }, "openTracking": { "type": "boolean", "default": false }, "publicKey": { "type": "string" }, "dkimStatus": { "type": "string", "nullable": true }, "spfDetails": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "dmarcAdded": { "type": "boolean", "default": false }, "isVerifying": { "type": "boolean", "default": false }, "errorMessage": { "type": "string", "nullable": true }, "subdomain": { "type": "string", "nullable": true }, "verificationError": { "type": "string", "nullable": true }, "lastCheckedTime": { "type": "string", "nullable": true }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["MX", "TXT"], "description": "DNS record type", "example": "TXT" }, "name": { "type": "string", "description": "DNS record name", "example": "mail" }, "value": { "type": "string", "description": "DNS record value", "example": "v=spf1 include:amazonses.com ~all" }, "ttl": { "type": "string", "description": "DNS record TTL", "example": "Auto" }, "priority": { "type": "string", "nullable": true, "description": "DNS record priority", "example": "10" }, "status": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE" ] }, "recommended": { "type": "boolean", "description": "Whether the record is recommended" } }, "required": ["type", "name", "value", "ttl", "status"] } } }, "required": [ "id", "name", "teamId", "status", "publicKey", "createdAt", "updatedAt", "dnsRecords" ] } } } } } } }, "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "region": { "type": "string" } }, "required": ["name", "region"] } } } }, "responses": { "200": { "description": "Create a new domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the domain", "example": 1 }, "name": { "type": "string", "description": "The name of the domain", "example": "example.com" }, "teamId": { "type": "number", "description": "The ID of the team", "example": 1 }, "status": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE" ] }, "region": { "type": "string", "default": "us-east-1" }, "clickTracking": { "type": "boolean", "default": false }, "openTracking": { "type": "boolean", "default": false }, "publicKey": { "type": "string" }, "dkimStatus": { "type": "string", "nullable": true }, "spfDetails": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "dmarcAdded": { "type": "boolean", "default": false }, "isVerifying": { "type": "boolean", "default": false }, "errorMessage": { "type": "string", "nullable": true }, "subdomain": { "type": "string", "nullable": true }, "verificationError": { "type": "string", "nullable": true }, "lastCheckedTime": { "type": "string", "nullable": true }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["MX", "TXT"], "description": "DNS record type", "example": "TXT" }, "name": { "type": "string", "description": "DNS record name", "example": "mail" }, "value": { "type": "string", "description": "DNS record value", "example": "v=spf1 include:amazonses.com ~all" }, "ttl": { "type": "string", "description": "DNS record TTL", "example": "Auto" }, "priority": { "type": "string", "nullable": true, "description": "DNS record priority", "example": "10" }, "status": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE" ] }, "recommended": { "type": "boolean", "description": "Whether the record is recommended" } }, "required": ["type", "name", "value", "ttl", "status"] } } }, "required": [ "id", "name", "teamId", "status", "publicKey", "createdAt", "updatedAt", "dnsRecords" ] } } } } } } }, "/v1/domains/{id}/verify": { "put": { "parameters": [ { "schema": { "type": "number", "nullable": true, "example": 1 }, "required": false, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Verify domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] } } } }, "403": { "description": "Forbidden - API key doesn't have access to this domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/domains/{id}": { "get": { "parameters": [ { "schema": { "type": "number", "nullable": true, "example": 1 }, "required": false, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Retrieve the domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the domain", "example": 1 }, "name": { "type": "string", "description": "The name of the domain", "example": "example.com" }, "teamId": { "type": "number", "description": "The ID of the team", "example": 1 }, "status": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE" ] }, "region": { "type": "string", "default": "us-east-1" }, "clickTracking": { "type": "boolean", "default": false }, "openTracking": { "type": "boolean", "default": false }, "publicKey": { "type": "string" }, "dkimStatus": { "type": "string", "nullable": true }, "spfDetails": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "dmarcAdded": { "type": "boolean", "default": false }, "isVerifying": { "type": "boolean", "default": false }, "errorMessage": { "type": "string", "nullable": true }, "subdomain": { "type": "string", "nullable": true }, "verificationError": { "type": "string", "nullable": true }, "lastCheckedTime": { "type": "string", "nullable": true }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["MX", "TXT"], "description": "DNS record type", "example": "TXT" }, "name": { "type": "string", "description": "DNS record name", "example": "mail" }, "value": { "type": "string", "description": "DNS record value", "example": "v=spf1 include:amazonses.com ~all" }, "ttl": { "type": "string", "description": "DNS record TTL", "example": "Auto" }, "priority": { "type": "string", "nullable": true, "description": "DNS record priority", "example": "10" }, "status": { "type": "string", "enum": [ "NOT_STARTED", "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE" ] }, "recommended": { "type": "boolean", "description": "Whether the record is recommended" } }, "required": ["type", "name", "value", "ttl", "status"] } } }, "required": [ "id", "name", "teamId", "status", "publicKey", "createdAt", "updatedAt", "dnsRecords" ] } } } } } }, "delete": { "parameters": [ { "schema": { "type": "number", "nullable": true, "example": 1 }, "required": false, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Domain deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": ["id", "success", "message"] } } } }, "403": { "description": "Forbidden - API key doesn't have access", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/emails/{emailId}": { "get": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "emailId", "in": "path" } ], "responses": { "200": { "description": "Retrieve the email", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "number" }, "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "replyTo": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "from": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "emailEvents": { "type": "array", "items": { "type": "object", "properties": { "emailId": { "type": "string" }, "status": { "type": "string", "enum": [ "SCHEDULED", "QUEUED", "SENT", "DELIVERY_DELAYED", "BOUNCED", "REJECTED", "RENDERING_FAILURE", "DELIVERED", "OPENED", "CLICKED", "COMPLAINED", "FAILED", "CANCELLED", "SUPPRESSED" ] }, "createdAt": { "type": "string" }, "data": { "nullable": true } }, "required": ["emailId", "status", "createdAt"] } } }, "required": [ "id", "teamId", "to", "from", "subject", "html", "text", "createdAt", "updatedAt", "emailEvents" ] } } } } } }, "patch": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "emailId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledAt": { "type": "string", "format": "date-time" } }, "required": ["scheduledAt"] } } } }, "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailId": { "type": "string" } } } } } } } } }, "/v1/emails": { "get": { "parameters": [ { "schema": { "type": "string", "default": "1", "example": "1" }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "string", "default": "50", "example": "50" }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "required": false, "name": "startDate", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2024-01-31T23:59:59Z" }, "required": false, "name": "endDate", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "123" }, "required": false, "name": "domainId", "in": "query" } ], "responses": { "200": { "description": "Retrieve a list of emails", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "replyTo": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "nullable": true } ] }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "nullable": true } ] }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "nullable": true } ] }, "from": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string", "nullable": true }, "text": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "latestStatus": { "type": "string", "nullable": true, "enum": [ "SCHEDULED", "QUEUED", "SENT", "DELIVERY_DELAYED", "BOUNCED", "REJECTED", "RENDERING_FAILURE", "DELIVERED", "OPENED", "CLICKED", "COMPLAINED", "FAILED", "CANCELLED", "SUPPRESSED" ] }, "scheduledAt": { "type": "string", "nullable": true, "format": "date-time" }, "domainId": { "type": "number", "nullable": true } }, "required": [ "id", "to", "from", "subject", "html", "text", "createdAt", "updatedAt", "latestStatus", "scheduledAt", "domainId" ] } }, "count": { "type": "number" } }, "required": ["data", "count"] } } } } } }, "post": { "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Pass the optional Idempotency-Key header to make the request safe to retry. The key can be up to 256 characters. The server stores the canonical request body and behaves as follows:\n\n- Same key + same request body → returns the original emailId with 200 OK without re-sending.\n- Same key + different request body → returns 409 Conflict with code: NOT_UNIQUE so you can detect the mismatch.\n- Same key while another request is still being processed → returns 409 Conflict; retry after a short delay or once the first request completes.\n\nEntries expire after 24 hours. Use a unique key per logical send (for example, an order or signup ID)." }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "from": { "type": "string" }, "subject": { "type": "string", "minLength": 1, "description": "Optional when templateId is provided" }, "templateId": { "type": "string", "description": "ID of a template from the dashboard" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "replyTo": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "text": { "type": "string", "nullable": true, "minLength": 1 }, "html": { "type": "string", "nullable": true, "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 }, "description": "Custom headers to included with the emails" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": ["filename", "content"] }, "maxItems": 10 }, "scheduledAt": { "type": "string", "format": "date-time" }, "inReplyToId": { "type": "string", "nullable": true } }, "required": ["to", "from"] } } } }, "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailId": { "type": "string" } } } } } } } } }, "/v1/emails/batch": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Pass the optional Idempotency-Key header to make the request safe to retry. The key can be up to 256 characters. The server stores the canonical request body and behaves as follows:\n\n- Same key + same request body → returns the original emailId with 200 OK without re-sending.\n- Same key + different request body → returns 409 Conflict with code: NOT_UNIQUE so you can detect the mismatch.\n- Same key while another request is still being processed → returns 409 Conflict; retry after a short delay or once the first request completes.\n\nEntries expire after 24 hours. Use a unique key per logical send (for example, an order or signup ID)." }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "from": { "type": "string" }, "subject": { "type": "string", "minLength": 1, "description": "Optional when templateId is provided" }, "templateId": { "type": "string", "description": "ID of a template from the dashboard" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "replyTo": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "cc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "bcc": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "text": { "type": "string", "nullable": true, "minLength": 1 }, "html": { "type": "string", "nullable": true, "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 }, "description": "Custom headers to included with the emails" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": ["filename", "content"] }, "maxItems": 10 }, "scheduledAt": { "type": "string", "format": "date-time" }, "inReplyToId": { "type": "string", "nullable": true } }, "required": ["to", "from"] }, "maxItems": 100 } } } }, "responses": { "200": { "description": "List of successfully created email IDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "emailId": { "type": "string" } }, "required": ["emailId"] } } }, "required": ["data"] } } } } } } }, "/v1/emails/{emailId}/cancel": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "emailId", "in": "path" } ], "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailId": { "type": "string" } } } } } } } } }, "/v1/contactBooks/{contactBookId}/contacts": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "subscribed": { "type": "boolean" } }, "required": ["email"] } } } }, "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" } } } } } } } }, "get": { "parameters": [ { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "emails", "in": "query" }, { "schema": { "type": "number" }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "number" }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "ids", "in": "query" } ], "responses": { "200": { "description": "Retrieve multiple contacts", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "contactBookId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "email", "properties", "contactBookId", "createdAt", "updatedAt" ] } } } } } } } }, "/v1/contactBooks/{contactBookId}/contacts/{contactId}": { "patch": { "parameters": [ { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" }, { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "subscribed": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Retrieve the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" } } } } } } } }, "get": { "parameters": [ { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" }, { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Retrieve the contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string" }, "subscribed": { "type": "boolean", "default": true }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "contactBookId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "email", "properties", "contactBookId", "createdAt", "updatedAt" ] } } } } } }, "put": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "subscribed": { "type": "boolean" } }, "required": ["email"] } } } }, "responses": { "200": { "description": "Contact upserted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" } }, "required": ["contactId"] } } } } } }, "delete": { "parameters": [ { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" }, { "schema": { "type": "string", "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Contact deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"] } } } } } } }, "/v1/contactBooks/{contactBookId}/contacts/bulk": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "subscribed": { "type": "boolean" } }, "required": ["email"] }, "maxItems": 1000 } } } }, "responses": { "200": { "description": "Bulk add contacts to a contact book", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "count": { "type": "number" } }, "required": ["message", "count"] } } } } } }, "delete": { "parameters": [ { "schema": { "type": "string", "minLength": 3, "example": "cuiwqdj74rygf74" }, "required": true, "name": "contactBookId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000 } }, "required": ["contactIds"] } } } }, "responses": { "200": { "description": "Bulk delete contacts from a contact book", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "count": { "type": "number" } }, "required": ["success", "count"] } } } } } } }, "/v1/contactBooks": { "get": { "responses": { "200": { "description": "Retrieve contact books accessible by the API key", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact book", "example": "clx1234567890" }, "name": { "type": "string", "description": "The name of the contact book", "example": "Newsletter Subscribers" }, "teamId": { "type": "number", "description": "The ID of the team", "example": 1 }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom properties for the contact book", "example": { "customField1": "value1" } }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Allowed personalization variables for contacts in this book", "example": ["registrationCode", "company"] }, "emoji": { "type": "string", "description": "The emoji associated with the contact book", "example": "📙" }, "doubleOptInEnabled": { "type": "boolean", "description": "Whether double opt-in is enabled for new contacts", "example": true }, "doubleOptInFrom": { "type": "string", "nullable": true, "description": "From address used for double opt-in emails (must use a verified domain)", "example": "Newsletter " }, "doubleOptInSubject": { "type": "string", "nullable": true, "description": "Subject line used for double opt-in confirmation email", "example": "Please confirm your subscription" }, "doubleOptInContent": { "type": "string", "nullable": true, "description": "Email editor JSON content used for double opt-in confirmation" }, "createdAt": { "type": "string", "description": "The creation timestamp" }, "updatedAt": { "type": "string", "description": "The last update timestamp" }, "_count": { "type": "object", "properties": { "contacts": { "type": "number", "description": "The number of contacts in the contact book" } }, "required": ["contacts"] } }, "required": [ "id", "name", "teamId", "properties", "variables", "emoji", "createdAt", "updatedAt" ] } } } } } } }, "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "emoji": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "doubleOptInEnabled": { "type": "boolean" }, "doubleOptInFrom": { "type": "string", "nullable": true }, "doubleOptInSubject": { "type": "string" }, "doubleOptInContent": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } } }, "required": ["name"] } } } }, "responses": { "200": { "description": "Create a new contact book", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact book", "example": "clx1234567890" }, "name": { "type": "string", "description": "The name of the contact book", "example": "Newsletter Subscribers" }, "teamId": { "type": "number", "description": "The ID of the team", "example": 1 }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom properties for the contact book", "example": { "customField1": "value1" } }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Allowed personalization variables for contacts in this book", "example": ["registrationCode", "company"] }, "emoji": { "type": "string", "description": "The emoji associated with the contact book", "example": "📙" }, "doubleOptInEnabled": { "type": "boolean", "description": "Whether double opt-in is enabled for new contacts", "example": true }, "doubleOptInFrom": { "type": "string", "nullable": true, "description": "From address used for double opt-in emails (must use a verified domain)", "example": "Newsletter " }, "doubleOptInSubject": { "type": "string", "nullable": true, "description": "Subject line used for double opt-in confirmation email", "example": "Please confirm your subscription" }, "doubleOptInContent": { "type": "string", "nullable": true, "description": "Email editor JSON content used for double opt-in confirmation" }, "createdAt": { "type": "string", "description": "The creation timestamp" }, "updatedAt": { "type": "string", "description": "The last update timestamp" }, "_count": { "type": "object", "properties": { "contacts": { "type": "number", "description": "The number of contacts in the contact book" } }, "required": ["contacts"] } }, "required": [ "id", "name", "teamId", "properties", "variables", "emoji", "createdAt", "updatedAt" ] } } } } } } }, "/v1/contactBooks/{contactBookId}": { "get": { "parameters": [ { "schema": { "type": "string", "example": "clx1234567890" }, "required": true, "name": "contactBookId", "in": "path" } ], "responses": { "200": { "description": "Retrieve the contact book", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact book", "example": "clx1234567890" }, "name": { "type": "string", "description": "The name of the contact book", "example": "Newsletter Subscribers" }, "teamId": { "type": "number", "description": "The ID of the team", "example": 1 }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom properties for the contact book", "example": { "customField1": "value1" } }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Allowed personalization variables for contacts in this book", "example": ["registrationCode", "company"] }, "emoji": { "type": "string", "description": "The emoji associated with the contact book", "example": "📙" }, "doubleOptInEnabled": { "type": "boolean", "description": "Whether double opt-in is enabled for new contacts", "example": true }, "doubleOptInFrom": { "type": "string", "nullable": true, "description": "From address used for double opt-in emails (must use a verified domain)", "example": "Newsletter " }, "doubleOptInSubject": { "type": "string", "nullable": true, "description": "Subject line used for double opt-in confirmation email", "example": "Please confirm your subscription" }, "doubleOptInContent": { "type": "string", "nullable": true, "description": "Email editor JSON content used for double opt-in confirmation" }, "createdAt": { "type": "string", "description": "The creation timestamp" }, "updatedAt": { "type": "string", "description": "The last update timestamp" }, "_count": { "type": "object", "properties": { "contacts": { "type": "number", "description": "The number of contacts in the contact book" } }, "required": ["contacts"] } }, "required": [ "id", "name", "teamId", "properties", "variables", "emoji", "createdAt", "updatedAt" ] } } } }, "403": { "description": "Forbidden - API key doesn't have access to this contact book", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Contact book not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } }, "patch": { "parameters": [ { "schema": { "type": "string", "example": "clx1234567890" }, "required": true, "name": "contactBookId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "emoji": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "type": "string" } }, "doubleOptInEnabled": { "type": "boolean" }, "doubleOptInFrom": { "type": "string", "nullable": true }, "doubleOptInSubject": { "type": "string" }, "doubleOptInContent": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Update the contact book", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the contact book", "example": "clx1234567890" }, "name": { "type": "string", "description": "The name of the contact book", "example": "Newsletter Subscribers" }, "teamId": { "type": "number", "description": "The ID of the team", "example": 1 }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom properties for the contact book", "example": { "customField1": "value1" } }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Allowed personalization variables for contacts in this book", "example": ["registrationCode", "company"] }, "emoji": { "type": "string", "description": "The emoji associated with the contact book", "example": "📙" }, "doubleOptInEnabled": { "type": "boolean", "description": "Whether double opt-in is enabled for new contacts", "example": true }, "doubleOptInFrom": { "type": "string", "nullable": true, "description": "From address used for double opt-in emails (must use a verified domain)", "example": "Newsletter " }, "doubleOptInSubject": { "type": "string", "nullable": true, "description": "Subject line used for double opt-in confirmation email", "example": "Please confirm your subscription" }, "doubleOptInContent": { "type": "string", "nullable": true, "description": "Email editor JSON content used for double opt-in confirmation" }, "createdAt": { "type": "string", "description": "The creation timestamp" }, "updatedAt": { "type": "string", "description": "The last update timestamp" }, "_count": { "type": "object", "properties": { "contacts": { "type": "number", "description": "The number of contacts in the contact book" } }, "required": ["contacts"] } }, "required": [ "id", "name", "teamId", "properties", "variables", "emoji", "createdAt", "updatedAt" ] } } } }, "403": { "description": "Forbidden - API key doesn't have access to this contact book", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Contact book not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } }, "delete": { "parameters": [ { "schema": { "type": "string", "example": "clx1234567890" }, "required": true, "name": "contactBookId", "in": "path" } ], "responses": { "200": { "description": "Contact book deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": ["id", "success", "message"] } } } }, "403": { "description": "Forbidden - API key doesn't have access", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } }, "404": { "description": "Contact book not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] } } } } } } }, "/v1/campaigns": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "from": { "type": "string", "minLength": 1 }, "subject": { "type": "string", "minLength": 1 }, "previewText": { "type": "string" }, "contactBookId": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "html": { "type": "string", "minLength": 1 }, "replyTo": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 } } ] }, "cc": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 } } ] }, "bcc": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 } } ] }, "sendNow": { "type": "boolean" }, "scheduledAt": { "type": "string", "description": "Timestamp in ISO 8601 format or natural language (e.g., 'tomorrow 9am', 'next monday 10:30')" }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "required": ["name", "from", "subject", "contactBookId"] } } } }, "responses": { "200": { "description": "Create a campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "previewText": { "type": "string", "nullable": true }, "contactBookId": { "type": "string", "nullable": true }, "html": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "status": { "type": "string" }, "scheduledAt": { "type": "string", "nullable": true, "format": "date-time" }, "batchSize": { "type": "integer" }, "batchWindowMinutes": { "type": "integer" }, "total": { "type": "integer" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "hardBounced": { "type": "integer" }, "complained": { "type": "integer" }, "replyTo": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "from", "subject", "previewText", "contactBookId", "html", "content", "status", "scheduledAt", "batchSize", "batchWindowMinutes", "total", "sent", "delivered", "opened", "clicked", "unsubscribed", "bounced", "hardBounced", "complained", "replyTo", "cc", "bcc", "createdAt", "updatedAt" ] } } } } } }, "get": { "parameters": [ { "schema": { "type": "string", "description": "Page number for pagination (default: 1)", "example": "1" }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "string", "enum": ["DRAFT", "SCHEDULED", "RUNNING", "PAUSED", "SENT"], "description": "Filter campaigns by status", "example": "DRAFT" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "Search campaigns by name or subject", "example": "newsletter" }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Get list of campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "scheduledAt": { "type": "string", "nullable": true, "format": "date-time" }, "total": { "type": "integer" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "unsubscribed": { "type": "integer" } }, "required": [ "id", "name", "from", "subject", "createdAt", "updatedAt", "status", "scheduledAt", "total", "sent", "delivered", "unsubscribed" ] } }, "totalPage": { "type": "integer" } }, "required": ["campaigns", "totalPage"] } } } } } } }, "/v1/campaigns/{campaignId}": { "get": { "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "cmp_123" }, "required": true, "name": "campaignId", "in": "path" } ], "responses": { "200": { "description": "Get campaign details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "previewText": { "type": "string", "nullable": true }, "contactBookId": { "type": "string", "nullable": true }, "html": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "status": { "type": "string" }, "scheduledAt": { "type": "string", "nullable": true, "format": "date-time" }, "batchSize": { "type": "integer" }, "batchWindowMinutes": { "type": "integer" }, "total": { "type": "integer" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "hardBounced": { "type": "integer" }, "complained": { "type": "integer" }, "replyTo": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "from", "subject", "previewText", "contactBookId", "html", "content", "status", "scheduledAt", "batchSize", "batchWindowMinutes", "total", "sent", "delivered", "opened", "clicked", "unsubscribed", "bounced", "hardBounced", "complained", "replyTo", "cc", "bcc", "createdAt", "updatedAt" ] } } } } } }, "delete": { "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "cmp_123" }, "required": true, "name": "campaignId", "in": "path" } ], "responses": { "200": { "description": "Delete campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "previewText": { "type": "string", "nullable": true }, "contactBookId": { "type": "string", "nullable": true }, "html": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "status": { "type": "string" }, "scheduledAt": { "type": "string", "nullable": true, "format": "date-time" }, "batchSize": { "type": "integer" }, "batchWindowMinutes": { "type": "integer" }, "total": { "type": "integer" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "bounced": { "type": "integer" }, "hardBounced": { "type": "integer" }, "complained": { "type": "integer" }, "replyTo": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "from", "subject", "previewText", "contactBookId", "html", "content", "status", "scheduledAt", "batchSize", "batchWindowMinutes", "total", "sent", "delivered", "opened", "clicked", "unsubscribed", "bounced", "hardBounced", "complained", "replyTo", "cc", "bcc", "createdAt", "updatedAt" ] } } } } } } }, "/v1/campaigns/{campaignId}/schedule": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "cmp_123" }, "required": true, "name": "campaignId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledAt": { "type": "string", "description": "Timestamp in ISO 8601 format or natural language (e.g., 'tomorrow 9am', 'next monday 10:30')" }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100000 } } } } } }, "responses": { "200": { "description": "Schedule a campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"] } } } } } } }, "/v1/campaigns/{campaignId}/pause": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "cmp_123" }, "required": true, "name": "campaignId", "in": "path" } ], "responses": { "200": { "description": "Pause a campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"] } } } } } } }, "/v1/campaigns/{campaignId}/resume": { "post": { "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "cmp_123" }, "required": true, "name": "campaignId", "in": "path" } ], "responses": { "200": { "description": "Resume a campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"] } } } } } } }, "/v1/analytics/email-time-series": { "get": { "parameters": [ { "schema": { "type": "string", "enum": ["7", "30"], "description": "Number of days to retrieve data for (default: 30)", "example": "30" }, "required": false, "name": "days", "in": "query" }, { "schema": { "type": "string", "description": "Filter by domain ID" }, "required": false, "name": "domainId", "in": "query" } ], "responses": { "200": { "description": "Retrieve email time series data", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" } }, "required": [ "date", "sent", "delivered", "opened", "clicked", "bounced", "complained" ] } }, "totalCounts": { "type": "object", "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" } }, "required": [ "sent", "delivered", "opened", "clicked", "bounced", "complained" ] } }, "required": ["result", "totalCounts"] } } } } } } }, "/v1/analytics/reputation-metrics": { "get": { "parameters": [ { "schema": { "type": "string", "description": "Filter by domain ID" }, "required": false, "name": "domainId", "in": "query" } ], "responses": { "200": { "description": "Retrieve reputation metrics data", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivered": { "type": "integer" }, "hardBounced": { "type": "integer" }, "complained": { "type": "integer" }, "bounceRate": { "type": "number" }, "complaintRate": { "type": "number" } }, "required": [ "delivered", "hardBounced", "complained", "bounceRate", "complaintRate" ] } } } } } } } } }