Hello!
" } }, "html-and-text": { "summary": "HTML and plain text (recommended)", "description": "Sending both HTML and plain text ensures email renders correctly in all email clients.", "value": { "from": "sender@example.com", "from_name": "Sender Name", "to": [ "recipient@example.com" ], "subject": "Welcome to Lettr", "html": "Welcome to our service!
", "text": "Hello\n\nWelcome to our service!", "options": { "click_tracking": true, "open_tracking": true } } }, "html-only": { "summary": "HTML only", "description": "Send HTML content only. Some email clients may not render properly without a text fallback.", "value": { "from": "sender@example.com", "to": [ "recipient@example.com" ], "subject": "Welcome to Lettr", "html": "Welcome to our service!
" } }, "text-only": { "summary": "Plain text only", "description": "Send plain text content only. Ideal for simple notifications.", "value": { "from": "sender@example.com", "to": [ "recipient@example.com" ], "subject": "Order Confirmation", "text": "Your order #12345 has been confirmed.\n\nThank you for your purchase!" } }, "with-attachments": { "summary": "Email with attachments", "description": "Send an email with file attachments. Attachments must be base64 encoded.", "value": { "from": "billing@example.com", "from_name": "Billing Department", "to": [ "customer@example.com" ], "subject": "Your Invoice", "html": "Please find your invoice attached.
", "text": "Please find your invoice attached.", "attachments": [ { "name": "invoice.pdf", "type": "application/pdf", "data": "JVBERi0xLjQKJeLjz9M..." } ] } }, "with-personalization": { "summary": "Personalized email with substitution", "description": "Use substitution_data to personalize email content with dynamic variables.", "value": { "from": "hello@example.com", "from_name": "Acme Inc", "to": [ "john@example.com" ], "subject": "Welcome, {{first_name}}!", "html": "Welcome to {{company}}!
", "text": "Hello {{first_name}},\n\nWelcome to {{company}}!", "substitution_data": { "first_name": "John", "company": "Acme Inc" }, "metadata": { "user_id": "12345", "campaign": "onboarding" } } }, "with-template": { "summary": "Email using a template", "description": "Send an email using a pre-defined template. The template's HTML content and subject will be used. You can optionally override the subject.", "value": { "from": "hello@example.com", "to": [ "john@example.com" ], "template_slug": "welcome-email", "substitution_data": { "first_name": "John" } } }, "with-template-and-project": { "summary": "Email using a template from a specific project", "description": "Send an email using a template from a specific project with a specific version. Subject is taken from the template unless explicitly provided.", "value": { "from": "hello@example.com", "to": [ "john@example.com" ], "project_id": 123, "template_slug": "welcome-email", "template_version": 2, "substitution_data": { "first_name": "John" } } } } } } }, "responses": { "200": { "description": "Email queued for delivery. Free tier teams receive quota headers indicating their usage and limits.", "headers": { "X-Monthly-Limit": { "description": "Total monthly email limit for this team. Only present for free tier teams.", "schema": { "type": "integer", "example": 3000 } }, "X-Monthly-Remaining": { "description": "Remaining emails allowed this month. Only present for free tier teams.", "schema": { "type": "integer", "example": 2500 } }, "X-Monthly-Reset": { "description": "Unix timestamp when the monthly quota resets (start of next month). Only present for free tier teams.", "schema": { "type": "integer", "example": 1740787200 } }, "X-Daily-Limit": { "description": "Total daily email limit for this team. Only present for free tier teams.", "schema": { "type": "integer", "example": 100 } }, "X-Daily-Remaining": { "description": "Remaining emails allowed today. Only present for free tier teams.", "schema": { "type": "integer", "example": 75 } }, "X-Daily-Reset": { "description": "Unix timestamp when the daily quota resets (tomorrow midnight UTC). Only present for free tier teams.", "schema": { "type": "integer", "example": 1739600000 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailSuccessResponse" }, "example": { "message": "Email queued for delivery.", "data": { "request_id": "12345678901234567890", "accepted": 1, "rejected": 0 } } } } }, "400": { "description": "Failed to send email (domain errors)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_domain": { "summary": "Invalid sender domain", "value": { "message": "The sender domain could not be determined from the email address.", "error_code": "invalid_domain" } }, "unconfigured_domain": { "summary": "Unconfigured sender domain", "value": { "message": "The sender domain is not configured or approved for sending.", "error_code": "unconfigured_domain" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Template or project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "template_not_found": { "summary": "Template not found", "value": { "message": "Template with slug 'welcome-email' was not found.", "error_code": "template_not_found" } }, "project_not_found": { "summary": "Project not found", "value": { "message": "Project with ID '123' was not found or you don't have access to it.", "error_code": "template_not_found" } }, "no_default_project": { "summary": "No default project configured", "value": { "message": "No default project is configured for this team.", "error_code": "template_not_found" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "from": [ "The sender email address is required." ], "to": [ "At least one recipient email address is required." ] } } } } }, "429": { "description": "Sending quota exceeded. The response includes quota headers to help determine current usage and when the limit resets.", "headers": { "X-Monthly-Limit": { "description": "Total monthly email limit for this team.", "schema": { "type": "integer", "example": 3000 } }, "X-Monthly-Remaining": { "description": "Remaining emails allowed this month (0 when limit is hit).", "schema": { "type": "integer", "example": 0 } }, "X-Monthly-Reset": { "description": "Unix timestamp when the monthly quota resets (start of next month).", "schema": { "type": "integer", "example": 1740787200 } }, "X-Daily-Limit": { "description": "Total daily email limit for this team.", "schema": { "type": "integer", "example": 100 } }, "X-Daily-Remaining": { "description": "Remaining emails allowed today (0 when limit is hit).", "schema": { "type": "integer", "example": 0 } }, "X-Daily-Reset": { "description": "Unix timestamp when the daily quota resets (tomorrow midnight UTC).", "schema": { "type": "integer", "example": 1739600000 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "monthly_quota_exceeded": { "summary": "Monthly sending quota exceeded", "value": { "message": "Sending quota exceeded. Upgrade your plan to continue sending.", "error_code": "quota_exceeded" } }, "daily_quota_exceeded": { "summary": "Daily sending quota exceeded", "value": { "message": "Daily sending quota exceeded. Please try again tomorrow.", "error_code": "daily_quota_exceeded" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Failed to send email. Please try again later.", "error_code": "send_error" } } } }, "502": { "description": "Email transmission failed (upstream provider error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Unconfigured Sending DomainThis email was scheduled!
", "scheduled_at": "2024-01-16T10:00:00Z", "options": { "click_tracking": true, "open_tracking": true } } } } }, "responses": { "201": { "description": "Email scheduled for delivery. Free tier teams receive quota headers indicating their usage and limits.", "headers": { "X-Monthly-Limit": { "description": "Total monthly email limit for this team. Only present for free tier teams.", "schema": { "type": "integer", "example": 3000 } }, "X-Monthly-Remaining": { "description": "Remaining emails allowed this month. Only present for free tier teams.", "schema": { "type": "integer", "example": 2500 } }, "X-Monthly-Reset": { "description": "Unix timestamp when the monthly quota resets.", "schema": { "type": "integer", "example": 1740787200 } }, "X-Daily-Limit": { "description": "Total daily email limit for this team. Only present for free tier teams.", "schema": { "type": "integer", "example": 100 } }, "X-Daily-Remaining": { "description": "Remaining emails allowed today. Only present for free tier teams.", "schema": { "type": "integer", "example": 75 } }, "X-Daily-Reset": { "description": "Unix timestamp when the daily quota resets.", "schema": { "type": "integer", "example": 1739600000 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailSuccessResponse" }, "example": { "message": "Email scheduled for delivery.", "data": { "request_id": "12345678901234567890", "accepted": 1, "rejected": 0 } } } } }, "400": { "description": "Failed to schedule email (domain errors)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_domain": { "summary": "Invalid sender domain", "value": { "message": "The sender domain could not be determined from the email address.", "error_code": "invalid_domain" } }, "unconfigured_domain": { "summary": "Unconfigured sender domain", "value": { "message": "The sender domain is not configured or approved for sending.", "error_code": "unconfigured_domain" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "scheduled_at": [ "The scheduled delivery time is required." ] } } } } }, "429": { "description": "Sending quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Sending quota exceeded. Upgrade your plan to continue sending.", "error_code": "quota_exceeded" } } } }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "description": "Email transmission failed (upstream provider error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Unconfigured Sending DomainHello {{NAME}}, your order {{ORDER_ID}} is ready!
" } }, "with_project_and_folder": { "summary": "Create in specific project and folder", "value": { "name": "Invoice Email", "project_id": 5, "folder_id": 10, "html": "Invoice for {{CUSTOMER_NAME}}
" } } } } } }, "responses": { "201": { "description": "Template created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateResponse" }, "example": { "message": "Template created successfully.", "data": { "id": 123, "name": "Welcome Email", "slug": "welcome-email", "project_id": 5, "folder_id": 10, "active_version": 1, "merge_tags": [ { "key": "FIRST_NAME", "required": true } ], "created_at": "2026-01-28T12:00:00+00:00" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Project or folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "project_not_found": { "summary": "Project not found", "value": { "message": "Project with ID '123' was not found or you don't have access to it.", "error_code": "not_found" } }, "no_default_project": { "summary": "No default project configured", "value": { "message": "No default project is configured for this team.", "error_code": "not_found" } }, "folder_not_found": { "summary": "Folder not found", "value": { "message": "Folder with ID '456' was not found in the specified project.", "error_code": "not_found" } }, "no_folders": { "summary": "No folders in project", "value": { "message": "Project with ID '123' has no folders. Please create a folder first.", "error_code": "not_found" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "name_required": { "summary": "Name is required", "value": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "name": [ "The name field is required." ] } } }, "no_content": { "summary": "No content provided", "value": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "html": [ "Either html or json content is required." ] } } }, "both_content": { "summary": "Both html and json provided", "value": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "json": [ "The json and html fields are mutually exclusive. Provide only one." ] } } }, "invalid_json": { "summary": "Invalid JSON syntax", "value": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "json": [ "The provided JSON is not valid." ] } } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Failed to create template. Please try again later.", "error_code": "send_error" } } } } } } }, "/templates/{slug}": { "get": { "operationId": "getTemplate", "summary": "Get Template", "description": "Retrieve a single email template by its slug. If `project_id` is not provided, the template will be looked up in the team's default project.", "tags": [ "Templates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The template slug (URL-friendly identifier)", "schema": { "type": "string", "example": "welcome-email" } }, { "name": "project_id", "in": "query", "description": "Project ID to retrieve the template from. If not provided, uses the team's default project.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Template retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowTemplateResponse" }, "example": { "message": "Template retrieved successfully.", "data": { "id": 1, "name": "Welcome Email", "slug": "welcome-email", "project_id": 5, "folder_id": 10, "active_version": 2, "versions_count": 3, "created_at": "2025-01-15T10:00:00+00:00", "updated_at": "2025-01-20T14:30:00+00:00" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Template or project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "template_not_found": { "summary": "Template not found", "value": { "message": "Template with slug 'welcome-email' was not found.", "error_code": "not_found" } }, "project_not_found": { "summary": "Project not found", "value": { "message": "Project with ID '123' was not found or you don't have access to it.", "error_code": "not_found" } }, "no_default_project": { "summary": "No default project configured", "value": { "message": "No default project is configured for this team.", "error_code": "not_found" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "project_id": [ "The project_id parameter must be an integer." ] } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Failed to retrieve template. Please try again later.", "error_code": "send_error" } } } } } }, "delete": { "operationId": "deleteTemplate", "summary": "Delete Template", "description": "Permanently delete an email template and all its versions. If `project_id` is not provided, the template will be looked up in the team's default project.", "tags": [ "Templates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The template slug (URL-friendly identifier)", "schema": { "type": "string", "example": "welcome-email" } }, { "name": "project_id", "in": "query", "description": "Project ID to delete the template from. If not provided, uses the team's default project.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Template deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTemplateResponse" }, "example": { "message": "Template deleted successfully." } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Template or project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "template_not_found": { "summary": "Template not found", "value": { "message": "Template with slug 'welcome-email' was not found.", "error_code": "not_found" } }, "project_not_found": { "summary": "Project not found", "value": { "message": "Project with ID '123' was not found or you don't have access to it.", "error_code": "not_found" } }, "no_default_project": { "summary": "No default project configured", "value": { "message": "No default project is configured for this team.", "error_code": "not_found" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "project_id": [ "The project_id parameter must be an integer." ] } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Failed to delete template. Please try again later.", "error_code": "send_error" } } } } } }, "put": { "operationId": "updateTemplate", "summary": "Update Template", "description": "Update an existing email template's name and/or content. If content (html or json) is provided, a new active version will be created with extracted merge tags. If `project_id` is not provided, the template will be looked up in the team's default project.", "tags": [ "Templates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The template slug (URL-friendly identifier)", "schema": { "type": "string", "example": "welcome-email" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateRequest" }, "examples": { "update_name": { "summary": "Update template name only", "value": { "name": "Updated Welcome Email" } }, "update_html": { "summary": "Update with new HTML content", "value": { "html": "Hello {{NAME}}, welcome aboard!
" } }, "update_json": { "summary": "Update with new Topol JSON content", "value": { "json": "{\"tagName\":\"mj-container\",\"children\":[{\"tagName\":\"mj-text\",\"content\":\"Hello {{FIRST_NAME}}!\"}]}" } }, "update_name_and_content": { "summary": "Update name and content together", "value": { "name": "New Newsletter", "html": "Welcome {{SUBSCRIBER_NAME}}!
" } }, "update_with_project": { "summary": "Update template in specific project", "value": { "project_id": 5, "name": "Renamed Template" } } } } } }, "responses": { "200": { "description": "Template updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateResponse" }, "example": { "message": "Template updated successfully.", "data": { "id": 123, "name": "Updated Welcome Email", "slug": "welcome-email", "project_id": 5, "folder_id": 10, "active_version": 2, "merge_tags": [ { "key": "NAME", "required": true } ], "created_at": "2026-01-15T10:00:00+00:00", "updated_at": "2026-01-28T14:30:00+00:00" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Template or project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "template_not_found": { "summary": "Template not found", "value": { "message": "Template with slug 'welcome-email' was not found.", "error_code": "not_found" } }, "project_not_found": { "summary": "Project not found", "value": { "message": "Project with ID '123' was not found or you don't have access to it.", "error_code": "not_found" } }, "no_default_project": { "summary": "No default project configured", "value": { "message": "No default project is configured for this team.", "error_code": "not_found" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "both_content": { "summary": "Both html and json provided", "value": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "json": [ "The json field prohibits html from being present." ] } } }, "invalid_json": { "summary": "Invalid JSON syntax", "value": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "json": [ "The provided JSON is not valid." ] } } }, "name_too_long": { "summary": "Name exceeds max length", "value": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "name": [ "The name must not be greater than 255 characters." ] } } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Failed to update template. Please try again later.", "error_code": "send_error" } } } } } } }, "/templates/{slug}/merge-tags": { "get": { "operationId": "getTemplateMergeTags", "summary": "Get Template Merge Tags", "description": "Retrieve the merge tags (variables) for a template version. By default, returns merge tags for the active version. Use the `version` parameter to get merge tags for a specific version.", "tags": [ "Templates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The template slug (URL-friendly identifier)", "schema": { "type": "string", "example": "welcome-email" } }, { "name": "project_id", "in": "query", "description": "Project ID to retrieve the template from. If not provided, uses the team's default project.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "version", "in": "query", "description": "Template version number. If not provided, uses the active version.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Merge tags retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMergeTagsResponse" }, "example": { "message": "Merge tags retrieved successfully.", "data": { "project_id": 13, "template_slug": "welcome-email", "version": 2, "merge_tags": [ { "key": "first_name", "required": true }, { "key": "company_name", "required": false }, { "key": "order_items", "required": false, "children": [ { "key": "item_name", "type": "text" }, { "key": "item_quantity", "type": "number" }, { "key": "item_price", "type": "number" } ] } ] } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Template, version, or project not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "template_not_found": { "summary": "Template not found", "value": { "message": "Template with slug 'welcome-email' was not found.", "error_code": "not_found" } }, "project_not_found": { "summary": "Project not found", "value": { "message": "Project with ID '123' was not found or you don't have access to it.", "error_code": "not_found" } }, "no_default_project": { "summary": "No default project configured", "value": { "message": "No default project is configured for this team.", "error_code": "not_found" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "version": [ "The version parameter must be an integer." ] } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Failed to retrieve merge tags. Please try again later.", "error_code": "send_error" } } } } } } }, "/domains/{domain}/verify": { "post": { "operationId": "verifyDomain", "summary": "Verify Domain", "description": "Verify a domain's DNS records (DKIM and CNAME) with SparkPost. This triggers a verification check and returns the current status of DNS records.", "tags": [ "Domains" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain name to verify", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "Domain verification completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyDomainResponse" }, "examples": { "valid": { "summary": "All DNS records valid", "value": { "message": "Domain verification completed.", "data": { "domain": "example.com", "dkim_status": "valid", "cname_status": "valid", "dmarc_status": "valid", "spf_status": "unverified", "ownership_verified": "true", "is_primary_domain": false } } }, "unverified": { "summary": "DNS records not configured", "value": { "message": "Domain verification completed.", "data": { "domain": "example.com", "dkim_status": "invalid", "cname_status": "invalid", "dmarc_status": "missing", "spf_status": "unverified", "ownership_verified": null, "is_primary_domain": false, "dns": { "dkim_record": null, "cname_record": null, "dkim_error": "DNS DKIM query error: dns lookup failed for scph0226._domainkey.example.com: no TXT records found", "cname_error": "DNS CNAME query error: No CNAME records retrieved", "dmarc_record": null, "dmarc_error": "No DMARC record found for example.com or its parent domain.", "spf_record": null, "spf_error": null }, "dmarc": { "is_valid": false, "status": "missing", "found_at_domain": null, "record": null, "policy": null, "subdomain_policy": null, "error": "No DMARC record found for example.com or its parent domain.", "covered_by_parent_policy": false } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Domain not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Domain not found.", "error_code": "not_found" } } } }, "422": { "description": "Validation error - Invalid domain format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "message": "Validation failed.", "error_code": "validation_error", "errors": { "domain": [ "The domain must be a valid domain name (e.g., example.com)." ] } } } } }, "500": { "description": "Server error - Failed to verify domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Failed to verify domain. Please try again later.", "error_code": "send_error" } } } } } } }, "/templates/html": { "get": { "operationId": "getTemplateHtml", "summary": "Get Template HTML", "description": "Retrieve the HTML content and merge tags for a template's active version. Requires `project_id` and template `slug` as query parameters.", "tags": [ "Templates" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project_id", "in": "query", "description": "The project ID the template belongs to.", "required": true, "schema": { "type": "integer" } }, { "name": "slug", "in": "query", "description": "The template slug identifier.", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Template HTML retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTemplateHtmlResponse" }, "example": { "success": true, "data": { "html": "Welcome!
", "merge_tags": [ { "key": "name", "name": "name", "required": true }, { "key": "company", "name": "company", "required": false } ], "subject": "Welcome Email" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "Template not found or project does not belong to team", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" } } }, "example": { "success": false, "message": "Template not found." } } } } } } }, "/projects": { "get": { "operationId": "listProjects", "summary": "List Projects", "description": "Retrieve a paginated list of projects for the authenticated team.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "per_page", "in": "query", "description": "Number of results per page (1-100). Defaults to 25.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "page", "in": "query", "description": "Page number. Defaults to 1.", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Projects retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectsResponse" }, "example": { "message": "Projects retrieved successfully.", "data": { "projects": [ { "id": 1, "name": "Default Project", "emoji": null, "team_id": 123, "created_at": "2024-01-15T10:30:00+00:00", "updated_at": "2024-01-15T10:30:00+00:00" } ], "pagination": { "total": 1, "per_page": 25, "current_page": 1, "last_page": 1 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "message": "Validation failed.", "errors": { "per_page": [ "The per_page parameter must not exceed 100." ] } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key for authentication" } }, "responses": { "UnauthorizedError": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" }, "examples": { "missing_key": { "summary": "Missing API key", "value": { "message": "API key is required." } }, "invalid_key": { "summary": "Invalid API key", "value": { "message": "Invalid API key." } } } } } }, "ForbiddenError": { "description": "Forbidden - API key does not have the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Your API key does not have the required permissions for this action.", "error_code": "insufficient_scope" } } } }, "ServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "An unexpected error occurred. Please try again later.", "error_code": "send_error" } } } } }, "schemas": { "SendEmailRequest": { "type": "object", "description": "Email sending request. **Required:** `from`, `to`, and at least one of `html`, `text`, or `template_slug`. The `subject` is required unless `template_slug` is provided — when using a template, the subject defaults to the template's subject (or template name as fallback), but can be overridden. When using `template_slug`, if `project_id` is not provided, the team's default project will be used.", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "email", "maxLength": 255, "description": "Sender email address", "example": "sender@example.com" }, "from_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Sender display name", "example": "Sender Name" }, "subject": { "type": [ "string", "null" ], "maxLength": 998, "description": "Email subject line. Required when not using a template. When using `template_slug`, defaults to the template's subject (or template name as fallback). If provided alongside a template, overrides the template subject.", "example": "Welcome to Lettr" }, "to": { "type": "array", "description": "Recipient email addresses", "minItems": 1, "maxItems": 50, "items": { "type": "string", "format": "email", "maxLength": 255 }, "example": [ "recipient@example.com" ] }, "cc": { "type": "array", "description": "Carbon copy recipient email addresses", "items": { "type": "string", "format": "email", "maxLength": 255 }, "example": [ "cc@example.com" ] }, "bcc": { "type": "array", "description": "Blind carbon copy recipient email addresses", "items": { "type": "string", "format": "email", "maxLength": 255 }, "example": [ "bcc@example.com" ] }, "reply_to": { "type": [ "string", "null" ], "format": "email", "maxLength": 255, "description": "Reply-To email address", "example": "reply@example.com" }, "reply_to_name": { "type": [ "string", "null" ], "maxLength": 255, "description": "Reply-To display name", "example": "Reply Name" }, "html": { "type": [ "string", "null" ], "description": "HTML content of the email. At least one of `html` or `text` is required, but providing both is recommended for best compatibility across email clients.", "example": "Welcome!
" }, "text": { "type": [ "string", "null" ], "description": "Plain text content of the email. At least one of `html` or `text` is required, but providing both is recommended for best compatibility across email clients.", "example": "Hello\n\nWelcome!" }, "amp_html": { "type": [ "string", "null" ], "description": "AMP HTML content for supported email clients" }, "project_id": { "type": [ "integer", "null" ], "description": "Project ID containing the template. If not provided when using template_slug, the team's default project will be used.", "example": 123 }, "template_slug": { "type": [ "string", "null" ], "maxLength": 255, "description": "Template slug to use for email content. When provided, the template's HTML will be used instead of the html field.", "example": "welcome-email" }, "template_version": { "type": [ "integer", "null" ], "minimum": 1, "description": "Specific template version to use. If not provided, the active version will be used.", "example": 1 }, "tag": { "type": "string", "maxLength": 64, "description": "Tag for tracking and analytics. Automatically set from template_slug if not provided.", "example": "welcome-series-2024" }, "metadata": { "type": "object", "description": "Custom metadata attached to the email for tracking purposes", "additionalProperties": { "type": "string" }, "example": { "user_id": "12345", "campaign": "onboarding" } }, "headers": { "type": "object", "description": "Custom email headers. Up to 10 headers allowed. Standard envelope headers (From, To, Subject, etc.), SparkPost internal headers (X-MSYS-API), and List-Unsubscribe and List-Unsubscribe-Post headers are managed by the system and cannot be set manually.", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 998 }, "example": { "X-Mailer": "MyApp/1.0", "X-Custom-ID": "abc-123" } }, "substitution_data": { "type": "object", "description": "Variables for template substitution in email content", "additionalProperties": { "type": "string" }, "example": { "first_name": "John", "company": "Acme Inc" } }, "options": { "type": "object", "description": "Email delivery options", "properties": { "click_tracking": { "type": "boolean", "description": "Enable click tracking for links in the email" }, "open_tracking": { "type": "boolean", "description": "Enable open tracking via tracking pixel" }, "transactional": { "type": "boolean", "description": "Mark email as transactional (not marketing)" }, "inline_css": { "type": "boolean", "description": "Inline CSS styles in HTML content" }, "perform_substitutions": { "type": "boolean", "description": "Perform variable substitutions in content" } } }, "attachments": { "type": "array", "description": "File attachments. When provided, each attachment must include name, type, and data.", "items": { "$ref": "#/components/schemas/Attachment" } } } }, "Attachment": { "type": "object", "description": "Email attachment", "required": [ "name", "type", "data" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "Filename of the attachment", "example": "invoice.pdf" }, "type": { "type": "string", "maxLength": 255, "description": "MIME type of the attachment", "example": "application/pdf" }, "data": { "type": "string", "pattern": "^[A-Za-z0-9+/=]+$", "description": "Base64 encoded file content (no line breaks)", "example": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2U..." } } }, "SendEmailSuccessResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable success message", "example": "Email queued for delivery." }, "data": { "type": "object", "required": [ "request_id", "accepted", "rejected" ], "properties": { "request_id": { "type": "string", "description": "Unique identifier for this email transmission", "example": "12345678901234567890" }, "accepted": { "type": "integer", "minimum": 0, "description": "Number of recipients accepted for delivery", "example": 1 }, "rejected": { "type": "integer", "minimum": 0, "description": "Number of recipients rejected", "example": 0 } } } } }, "ValidationErrorResponse": { "type": "object", "required": [ "message", "error_code", "errors" ], "properties": { "message": { "type": "string", "description": "Human-readable error message", "example": "Validation failed." }, "error_code": { "type": "string", "description": "Error code (always `validation_error` for 422 responses)", "const": "validation_error", "example": "validation_error" }, "errors": { "type": "object", "description": "Field-specific validation errors", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "from": [ "The sender email address is required." ], "to": [ "At least one recipient email address is required." ] } } } }, "ErrorResponse": { "type": "object", "required": [ "message", "error_code" ], "description": "Error response for non-validation errors (400, 409, 500, 502).", "properties": { "message": { "type": "string", "description": "Human-readable error message", "example": "The sender domain could not be determined from the email address." }, "error_code": { "$ref": "#/components/schemas/ErrorCode" } } }, "UnauthorizedResponse": { "type": "object", "required": [ "message" ], "description": "Error response for authentication failures (401).", "properties": { "message": { "type": "string", "description": "Human-readable error message", "example": "API key is required." } } }, "ErrorCode": { "type": "string", "description": "Error codes returned by the API.\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `validation_error` | 422 | Request validation failed. Check the `errors` object for field-specific messages. |\n| `invalid_domain` | 400 | The sender domain could not be determined from the email address. |\n| `unconfigured_domain` | 400 | The sender domain is not configured or approved for sending. |\n| `send_error` | 400, 500 | General error during email send preparation or domain registration. |\n| `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g., sandbox key without associated user, upstream error). |\n| `transmission_failed` | 502 | Email transmission to the upstream provider failed. |\n| `resource_already_exists` | 409 | The resource (e.g., domain) already exists. |\n| `not_found` | 404 | The specified resource was not found. |\n| `template_not_found` | 404 | The specified template, project, or template version was not found. |\n| `insufficient_scope` | 403 | The API key does not have the required scope for this endpoint. |\n| `schedule_cancellation_failed` | 409, 500 | Could not cancel the scheduled transmission (already sent or upstream error). |\n| `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your plan to continue sending. |\n| `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again tomorrow. |", "enum": [ "validation_error", "invalid_domain", "unconfigured_domain", "send_error", "retrieval_error", "transmission_failed", "resource_already_exists", "not_found", "template_not_found", "insufficient_scope", "schedule_cancellation_failed", "quota_exceeded", "daily_quota_exceeded" ], "example": "invalid_domain" }, "StoreDomainRequest": { "type": "object", "description": "Request to create a new sending domain", "required": [ "domain" ], "properties": { "domain": { "type": "string", "maxLength": 255, "pattern": "^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,}$", "description": "The domain name to register (e.g., example.com)", "example": "example.com" } } }, "StoreDomainResponse": { "type": "object", "description": "Response after successfully creating a domain", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable success message", "example": "Domain created successfully." }, "data": { "$ref": "#/components/schemas/DomainView" } } }, "DomainView": { "type": "object", "description": "View of a sending domain", "required": [ "domain", "status", "status_label" ], "properties": { "domain": { "type": "string", "description": "The domain name", "example": "example.com" }, "status": { "type": "string", "enum": [ "pending", "approved", "blocked" ], "description": "Current status of the domain", "example": "pending" }, "status_label": { "type": "string", "description": "Human-readable status label", "example": "Pending Review" }, "dkim": { "type": [ "object", "null" ], "description": "DKIM configuration for the domain", "properties": { "public": { "type": "string", "description": "Public DKIM key" }, "selector": { "type": "string", "description": "DKIM selector" }, "headers": { "type": "string", "description": "Headers to sign" }, "signing_domain": { "type": "string", "description": "Domain used for DKIM signing. Normally matches the top-level `domain` field." } } } } }, "ListDomainsResponse": { "type": "object", "description": "Response containing a list of domains", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Domains retrieved successfully." }, "data": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "description": "List of domains", "items": { "$ref": "#/components/schemas/DomainListItemView" } } } } } }, "DomainListItemView": { "type": "object", "description": "View of a domain in the list response", "required": [ "domain", "status", "status_label", "can_send", "created_at", "updated_at" ], "properties": { "domain": { "type": "string", "description": "The domain name", "example": "example.com" }, "status": { "type": "string", "enum": [ "pending", "approved", "blocked" ], "description": "Current status of the domain", "example": "approved" }, "status_label": { "type": "string", "description": "Human-readable status label", "example": "Approved" }, "can_send": { "type": "boolean", "description": "Whether the domain can be used for sending emails", "example": true }, "cname_status": { "type": [ "string", "null" ], "description": "CNAME verification status", "example": "valid" }, "dkim_status": { "type": [ "string", "null" ], "description": "DKIM verification status", "example": "valid" }, "created_at": { "type": "string", "format": "date-time", "description": "When the domain was created", "example": "2024-01-15T10:30:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the domain was last updated", "example": "2024-01-16T14:45:00+00:00" } } }, "ShowDomainResponse": { "type": "object", "description": "Response containing a single domain with full details", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Domain retrieved successfully." }, "data": { "$ref": "#/components/schemas/DomainDetailView" } } }, "DomainDetailView": { "type": "object", "description": "Detailed view of a single domain", "required": [ "domain", "status", "status_label", "can_send", "created_at", "updated_at" ], "properties": { "domain": { "type": "string", "description": "The domain name", "example": "example.com" }, "status": { "type": "string", "enum": [ "pending", "approved", "blocked" ], "description": "Current status of the domain", "example": "approved" }, "status_label": { "type": "string", "description": "Human-readable status label", "example": "Approved" }, "can_send": { "type": "boolean", "description": "Whether the domain can be used for sending emails", "example": true }, "cname_status": { "type": [ "string", "null" ], "description": "CNAME verification status", "example": "valid" }, "dkim_status": { "type": [ "string", "null" ], "description": "DKIM verification status. `null` until the domain has been verified at least once via `POST /domains/{domain}/verify`.", "example": "valid" }, "dmarc_status": { "type": [ "string", "null" ], "description": "DMARC verification status. `null` until the domain has been verified at least once.", "enum": [ "valid", "invalid", "missing", "unverified", null ], "example": "valid" }, "spf_status": { "type": [ "string", "null" ], "description": "SPF verification status. `null` until the domain has been verified at least once.", "enum": [ "valid", "invalid", "missing", "unverified", null ], "example": "valid" }, "is_primary_domain": { "type": "boolean", "description": "True when this is a root/apex sending domain (not a subdomain). Primary domains require SPF instead of CNAME delegation.", "example": false }, "tracking_domain": { "type": [ "string", "null" ], "description": "Associated tracking domain for click/open tracking", "example": "tracking.example.com" }, "dns": { "type": [ "object", "null" ], "description": "DNS records for domain verification", "properties": { "dkim": { "type": "object", "description": "DKIM DNS record details", "properties": { "selector": { "type": "string", "description": "DKIM selector", "example": "scph0123" }, "public": { "type": "string", "description": "DKIM public key", "example": "MIGfMA0GCSqGSIb3DQEBA..." }, "headers": { "type": "string", "description": "Headers included in DKIM signature", "example": "from:to:subject:date" } } } } }, "dns_provider": { "type": [ "object", "null" ], "description": "Detected DNS provider for this domain, or `null` if detection hasn't run.", "required": [ "provider", "provider_label", "nameservers", "error" ], "properties": { "provider": { "type": "string", "description": "Machine-readable DNS provider identifier.", "example": "cloudflare" }, "provider_label": { "type": "string", "description": "Human-readable DNS provider name.", "example": "Cloudflare" }, "nameservers": { "type": "array", "description": "Nameservers detected for the domain.", "items": { "type": "string" }, "example": [ "ns1.example.com", "ns2.example.com" ] }, "error": { "type": [ "string", "null" ], "description": "Error message if DNS provider detection failed.", "example": null } } }, "created_at": { "type": "string", "format": "date-time", "description": "When the domain was created", "example": "2024-01-15T10:30:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the domain was last updated", "example": "2024-01-16T14:45:00+00:00" } } }, "VerifyDomainResponse": { "type": "object", "description": "Response containing domain verification results", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Domain verification completed." }, "data": { "$ref": "#/components/schemas/DomainVerificationView" } } }, "DomainVerificationView": { "type": "object", "description": "Domain verification status and DNS details", "required": [ "domain", "dkim_status", "cname_status", "dmarc_status", "spf_status", "is_primary_domain" ], "properties": { "domain": { "type": "string", "description": "The domain name", "example": "example.com" }, "dkim_status": { "type": "string", "description": "DKIM verification status", "enum": [ "valid", "unverified", "invalid" ], "example": "valid" }, "cname_status": { "type": "string", "description": "CNAME verification status. `not_applicable` is returned for primary (apex) sending domains, which require SPF instead of CNAME delegation.", "enum": [ "valid", "unverified", "invalid", "not_applicable" ], "example": "valid" }, "dmarc_status": { "type": "string", "description": "DMARC verification status.", "enum": [ "valid", "invalid", "missing", "unverified" ], "example": "valid" }, "spf_status": { "type": "string", "description": "SPF verification status.", "enum": [ "valid", "invalid", "missing", "unverified" ], "example": "valid" }, "is_primary_domain": { "type": "boolean", "description": "True when this is a root/apex sending domain (not a subdomain). Primary domains require SPF instead of CNAME delegation.", "example": false }, "ownership_verified": { "type": [ "string", "null" ], "description": "Whether domain ownership has been verified", "example": "true" }, "dns": { "$ref": "#/components/schemas/DomainDnsVerificationView" }, "dmarc": { "$ref": "#/components/schemas/DmarcValidationResult" }, "spf": { "$ref": "#/components/schemas/SpfValidationResult" } } }, "DomainDnsVerificationView": { "type": "object", "description": "DNS verification error details", "properties": { "dkim_record": { "type": [ "string", "null" ], "description": "Found DKIM record value", "example": null }, "cname_record": { "type": [ "string", "null" ], "description": "Found CNAME record value", "example": null }, "dkim_error": { "type": [ "string", "null" ], "description": "DKIM verification error message", "example": "DKIM record not found" }, "cname_error": { "type": [ "string", "null" ], "description": "CNAME verification error message", "example": "CNAME record not found" }, "dmarc_record": { "type": [ "string", "null" ], "description": "Found DMARC record value.", "example": null }, "dmarc_error": { "type": [ "string", "null" ], "description": "DMARC verification error message.", "example": "No DMARC record found for example.com or its parent domain." }, "spf_record": { "type": [ "string", "null" ], "description": "Found SPF record value.", "example": null }, "spf_error": { "type": [ "string", "null" ], "description": "SPF verification error message.", "example": null } } }, "DmarcValidationResult": { "type": "object", "description": "DMARC validation result details.", "required": [ "is_valid", "status", "found_at_domain", "record", "policy", "subdomain_policy", "error", "covered_by_parent_policy" ], "properties": { "is_valid": { "type": "boolean", "description": "Whether a valid DMARC record was found.", "example": false }, "status": { "type": "string", "description": "DMARC validation status.", "enum": [ "valid", "invalid", "missing", "unverified" ], "example": "missing" }, "found_at_domain": { "type": [ "string", "null" ], "description": "Domain where the DMARC record was located (may be a parent domain for subdomains).", "example": null }, "record": { "type": [ "string", "null" ], "description": "Raw DMARC record value.", "example": null }, "policy": { "type": [ "string", "null" ], "description": "DMARC policy tag (`p=`).", "enum": [ "none", "quarantine", "reject", null ], "example": null }, "subdomain_policy": { "type": [ "string", "null" ], "description": "DMARC subdomain policy tag (`sp=`), if present.", "enum": [ "none", "quarantine", "reject", null ], "example": null }, "error": { "type": [ "string", "null" ], "description": "Validation error message, if any.", "example": "No DMARC record found for example.com or its parent domain." }, "covered_by_parent_policy": { "type": "boolean", "description": "Whether this domain is covered by the parent domain's subdomain policy.", "example": false } } }, "SpfValidationResult": { "type": "object", "description": "SPF validation result details.", "required": [ "is_valid", "status", "record", "error", "includes_sparkpost" ], "properties": { "is_valid": { "type": "boolean", "description": "Whether a valid SPF record was found that authorises SparkPost.", "example": false }, "status": { "type": "string", "description": "SPF validation status.", "enum": [ "valid", "invalid", "missing", "unverified" ], "example": "unverified" }, "record": { "type": [ "string", "null" ], "description": "Raw SPF record value.", "example": null }, "error": { "type": [ "string", "null" ], "description": "Validation error message, if any.", "example": null }, "includes_sparkpost": { "type": "boolean", "description": "Whether the SPF record authorises `_spf.sparkpostmail.com`.", "example": false } } }, "UpdateWebhookRequest": { "type": "object", "description": "Request body for updating a webhook. Only provided fields will be updated.", "properties": { "name": { "type": "string", "description": "Name of the webhook", "maxLength": 255, "example": "Updated Webhook Name" }, "url": { "type": "string", "format": "uri", "description": "URL where webhook events will be sent", "maxLength": 2048, "example": "https://example.com/webhook" }, "target": { "type": "string", "format": "uri", "description": "Deprecated alias for `url`. Accepted for backwards compatibility.", "deprecated": true, "maxLength": 2048, "example": "https://example.com/webhook" }, "auth_type": { "type": "string", "description": "Authentication type for the webhook", "enum": [ "none", "basic", "oauth2" ], "example": "none" }, "auth_username": { "type": "string", "description": "Username for basic authentication", "maxLength": 255 }, "auth_password": { "type": "string", "description": "Password for basic authentication", "maxLength": 255 }, "oauth_token_url": { "type": "string", "format": "uri", "description": "OAuth2 token URL", "maxLength": 2048 }, "oauth_client_id": { "type": "string", "description": "OAuth2 client ID", "maxLength": 255 }, "oauth_client_secret": { "type": "string", "description": "OAuth2 client secret", "maxLength": 255 }, "events": { "type": "array", "description": "Event types that trigger the webhook. Fully-prefixed names such as `message.delivery` are canonical; short names (`delivery`) and the legacy `engagament.*` prefix are accepted for backwards compatibility and are normalised to the fully-prefixed form.", "minItems": 1, "items": { "type": "string", "enum": [ "message.injection", "message.delivery", "message.bounce", "message.delay", "message.out_of_band", "message.spam_complaint", "message.policy_rejection", "engagement.click", "engagement.open", "engagement.initial_open", "engagement.amp_click", "engagement.amp_open", "engagement.amp_initial_open", "generation.generation_failure", "generation.generation_rejection", "unsubscribe.list_unsubscribe", "unsubscribe.link_unsubscribe", "relay.relay_injection", "relay.relay_rejection", "relay.relay_delivery", "relay.relay_tempfail", "relay.relay_permfail" ] }, "example": [ "message.delivery", "message.bounce" ] }, "active": { "type": "boolean", "description": "Whether the webhook is enabled", "example": true } } }, "ListWebhooksResponse": { "type": "object", "description": "Response containing a list of webhooks", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Webhooks retrieved successfully." }, "data": { "type": "object", "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "description": "List of webhooks", "items": { "$ref": "#/components/schemas/WebhookView" } } } } } }, "ShowWebhookResponse": { "type": "object", "description": "Response containing a single webhook", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Webhook retrieved successfully." }, "data": { "$ref": "#/components/schemas/WebhookView" } } }, "StoreWebhookRequest": { "type": "object", "description": "Request body for creating a webhook", "required": [ "name", "url", "auth_type", "events_mode" ], "properties": { "name": { "type": "string", "description": "Name of the webhook", "maxLength": 255, "example": "Order Notifications" }, "url": { "type": "string", "format": "uri", "description": "URL where webhook events will be sent", "maxLength": 2048, "example": "https://example.com/webhook" }, "auth_type": { "type": "string", "enum": [ "none", "basic", "oauth2" ], "description": "Authentication type for the webhook", "example": "basic" }, "auth_username": { "type": "string", "description": "Username for basic authentication (required when auth_type is 'basic')", "maxLength": 255, "example": "user" }, "auth_password": { "type": "string", "description": "Password for basic authentication (required when auth_type is 'basic')", "maxLength": 255, "example": "secret" }, "oauth_client_id": { "type": "string", "description": "OAuth2 client ID (required when auth_type is 'oauth2')", "maxLength": 255 }, "oauth_client_secret": { "type": "string", "description": "OAuth2 client secret (required when auth_type is 'oauth2')", "maxLength": 255 }, "oauth_token_url": { "type": "string", "format": "uri", "description": "OAuth2 token URL (required when auth_type is 'oauth2')", "maxLength": 2048 }, "events_mode": { "type": "string", "enum": [ "all", "selected" ], "description": "Whether to receive all events or only selected ones", "example": "selected" }, "events": { "type": "array", "description": "List of event types to receive (required when events_mode is 'selected'). Fully-prefixed names such as `message.delivery` are canonical; short names (`delivery`) and the legacy `engagament.*` prefix are accepted for backwards compatibility and are normalised to the fully-prefixed form.", "items": { "type": "string", "enum": [ "message.injection", "message.delivery", "message.bounce", "message.delay", "message.out_of_band", "message.spam_complaint", "message.policy_rejection", "engagement.click", "engagement.open", "engagement.initial_open", "engagement.amp_click", "engagement.amp_open", "engagement.amp_initial_open", "generation.generation_failure", "generation.generation_rejection", "unsubscribe.list_unsubscribe", "unsubscribe.link_unsubscribe", "relay.relay_injection", "relay.relay_rejection", "relay.relay_delivery", "relay.relay_tempfail", "relay.relay_permfail" ] }, "example": [ "message.delivery", "message.bounce" ] } } }, "StoreWebhookResponse": { "type": "object", "description": "Response after creating a webhook", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Webhook created successfully." }, "data": { "$ref": "#/components/schemas/WebhookView" } } }, "ListTemplatesResponse": { "type": "object", "description": "Response containing a paginated list of templates", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Templates retrieved successfully." }, "data": { "type": "object", "required": [ "templates", "pagination" ], "properties": { "templates": { "type": "array", "description": "List of templates", "items": { "$ref": "#/components/schemas/TemplateView" } }, "pagination": { "$ref": "#/components/schemas/TemplatesPagination" } } } } }, "TemplateView": { "type": "object", "description": "View of an email template", "required": [ "id", "name", "slug", "project_id", "folder_id", "created_at", "updated_at" ], "properties": { "id": { "type": "integer", "description": "Unique identifier for the template", "example": 1 }, "name": { "type": "string", "description": "Name of the template", "example": "Welcome Email" }, "slug": { "type": "string", "description": "URL-friendly identifier for the template", "example": "welcome-email" }, "project_id": { "type": "integer", "description": "ID of the project containing this template", "example": 5 }, "folder_id": { "type": "integer", "description": "ID of the folder containing this template", "example": 10 }, "created_at": { "type": "string", "format": "date-time", "description": "When the template was created", "example": "2025-01-15T10:00:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the template was last updated", "example": "2025-01-20T14:30:00+00:00" } } }, "TemplatesPagination": { "type": "object", "description": "Pagination information for templates list", "required": [ "total", "per_page", "current_page", "last_page" ], "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total number of templates", "example": 42 }, "per_page": { "type": "integer", "minimum": 1, "description": "Number of templates per page", "example": 25 }, "current_page": { "type": "integer", "minimum": 1, "description": "Current page number", "example": 1 }, "last_page": { "type": "integer", "minimum": 1, "description": "Last page number", "example": 2 } } }, "ShowTemplateResponse": { "type": "object", "description": "Response containing a single template with details", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Template retrieved successfully." }, "data": { "$ref": "#/components/schemas/TemplateDetailView" } } }, "TemplateDetailView": { "type": "object", "description": "Detailed view of an email template", "required": [ "id", "name", "slug", "project_id", "folder_id", "active_version", "versions_count", "created_at", "updated_at" ], "properties": { "id": { "type": "integer", "description": "Unique identifier for the template", "example": 1 }, "name": { "type": "string", "description": "Name of the template", "example": "Welcome Email" }, "slug": { "type": "string", "description": "URL-friendly identifier for the template", "example": "welcome-email" }, "project_id": { "type": "integer", "description": "ID of the project containing this template", "example": 5 }, "folder_id": { "type": "integer", "description": "ID of the folder containing this template", "example": 10 }, "active_version": { "type": [ "integer", "null" ], "description": "Version number of the currently active template version, or null if no version is active", "example": 2 }, "versions_count": { "type": "integer", "minimum": 0, "description": "Total number of versions for this template", "example": 3 }, "html": { "type": [ "string", "null" ], "description": "The HTML content of the active template version, or null if no active version exists", "example": "Hello {{NAME}}!
" }, "json": { "type": "string", "description": "JSON content for Topol visual editor templates. Required if `html` is not provided. Mutually exclusive with `html`.", "example": "{\"tagName\":\"mj-container\",\"children\":[{\"tagName\":\"mj-text\",\"content\":\"Hello {{FIRST_NAME}}!\"}]}" } } }, "CreateTemplateResponse": { "type": "object", "description": "Response after successfully creating a template", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Template created successfully." }, "data": { "$ref": "#/components/schemas/CreatedTemplateView" } } }, "DeleteTemplateResponse": { "type": "object", "description": "Response after successfully deleting a template", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Template deleted successfully." } } }, "UpdateTemplateRequest": { "type": "object", "description": "Request to update an existing email template. All fields are optional - provide only what you want to change. If `html` or `json` is provided, a new active version will be created.", "properties": { "project_id": { "type": "integer", "minimum": 1, "description": "Project ID to find the template in. If not provided, uses the team's default project.", "example": 5 }, "name": { "type": "string", "maxLength": 255, "description": "New name for the template", "example": "Updated Welcome Email" }, "html": { "type": "string", "description": "New HTML content for the template. Creates a new active version. Mutually exclusive with `json`.", "example": "Hello {{NAME}}!
" }, "json": { "type": "string", "description": "New JSON content for Topol visual editor templates. Creates a new active version. Mutually exclusive with `html`.", "example": "{\"tagName\":\"mj-container\",\"children\":[{\"tagName\":\"mj-text\",\"content\":\"Hello {{FIRST_NAME}}!\"}]}" } } }, "UpdateTemplateResponse": { "type": "object", "description": "Response after successfully updating a template", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Template updated successfully." }, "data": { "$ref": "#/components/schemas/UpdatedTemplateView" } } }, "UpdatedTemplateView": { "type": "object", "description": "View of an updated template", "required": [ "id", "name", "slug", "project_id", "folder_id", "active_version", "merge_tags", "created_at", "updated_at" ], "properties": { "id": { "type": "integer", "description": "Unique identifier for the template", "example": 123 }, "name": { "type": "string", "description": "Name of the template", "example": "Updated Welcome Email" }, "slug": { "type": "string", "description": "URL-friendly identifier for the template", "example": "welcome-email" }, "project_id": { "type": "integer", "description": "ID of the project containing this template", "example": 5 }, "folder_id": { "type": "integer", "description": "ID of the folder containing this template", "example": 10 }, "active_version": { "type": "integer", "description": "Version number of the active template version", "example": 2 }, "merge_tags": { "type": "array", "description": "List of merge tags extracted from the template content", "items": { "$ref": "#/components/schemas/MergeTagView" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the template was created", "example": "2026-01-15T10:00:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the template was last updated", "example": "2026-01-28T14:30:00+00:00" } } }, "CreatedTemplateView": { "type": "object", "description": "View of a newly created template", "required": [ "id", "name", "slug", "project_id", "folder_id", "active_version", "merge_tags", "created_at" ], "properties": { "id": { "type": "integer", "description": "Unique identifier for the template", "example": 123 }, "name": { "type": "string", "description": "Name of the template", "example": "Welcome Email" }, "slug": { "type": "string", "description": "URL-friendly identifier for the template", "example": "welcome-email" }, "project_id": { "type": "integer", "description": "ID of the project containing this template", "example": 5 }, "folder_id": { "type": "integer", "description": "ID of the folder containing this template", "example": 10 }, "active_version": { "type": "integer", "description": "Version number of the active template version", "example": 1 }, "merge_tags": { "type": "array", "description": "List of merge tags extracted from the template content", "items": { "$ref": "#/components/schemas/MergeTagView" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the template was created", "example": "2026-01-28T12:00:00+00:00" } } }, "GetMergeTagsResponse": { "type": "object", "description": "Response containing merge tags for a template version", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "description": "Human-readable response message", "example": "Merge tags retrieved successfully." }, "data": { "$ref": "#/components/schemas/MergeTagsListView" } } }, "MergeTagsListView": { "type": "object", "description": "Merge tags for a template version", "required": [ "project_id", "template_slug", "version", "merge_tags" ], "properties": { "project_id": { "type": "integer", "description": "Numeric ID of the project the template belongs to.", "example": 13 }, "template_slug": { "type": "string", "description": "The template slug", "example": "welcome-email" }, "version": { "type": "integer", "description": "The template version number", "example": 2 }, "merge_tags": { "type": "array", "description": "List of merge tags in this template version", "items": { "$ref": "#/components/schemas/MergeTagView" } } } }, "MergeTagView": { "type": "object", "description": "A single merge tag. Loop merge tags (for iterating over arrays) include a 'children' property with nested field definitions.", "required": [ "key", "required" ], "properties": { "key": { "type": "string", "description": "The merge tag key/name used in templates", "example": "first_name" }, "required": { "type": "boolean", "description": "Whether this merge tag is required when sending emails", "example": true }, "type": { "type": "string", "description": "The data type of the merge tag (only present for loop children)", "enum": [ "text", "number", "image", "button" ], "example": "text" }, "children": { "type": "array", "description": "Child merge tags for loop blocks. Each child represents a field available within the loop iteration.", "items": { "$ref": "#/components/schemas/MergeTagChild" } } } }, "MergeTagChild": { "type": "object", "description": "A child merge tag within a loop block", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "The child merge tag key/name", "example": "item_name" }, "type": { "type": "string", "description": "The data type of the child merge tag", "enum": [ "text", "number", "image", "button" ], "example": "text" } } }, "WebhookView": { "type": "object", "description": "View of a webhook", "required": [ "id", "name", "url", "enabled", "auth_type", "has_auth_credentials" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook", "example": "webhook-abc123" }, "name": { "type": "string", "description": "Name of the webhook", "example": "Order Notifications" }, "url": { "type": "string", "format": "uri", "description": "URL where webhook events will be sent", "example": "https://example.com/webhook" }, "enabled": { "type": "boolean", "description": "Whether the webhook is enabled", "example": true }, "event_types": { "type": [ "array", "null" ], "description": "Specific event types the webhook receives (null if all events)", "items": { "type": "string" }, "example": [ "message.delivery", "message.bounce" ] }, "auth_type": { "type": "string", "description": "Authentication type for the webhook (none, basic, oauth2)", "example": "basic" }, "has_auth_credentials": { "type": "boolean", "description": "Whether authentication credentials are configured", "example": true }, "last_successful_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last successful webhook delivery", "example": "2024-01-15T10:30:00+00:00" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last failed webhook delivery", "example": null }, "last_status": { "type": [ "string", "null" ], "description": "Status of the last delivery attempt (success or failure)", "enum": [ "success", "failure", null ], "example": "success" } } }, "ScheduleEmailRequest": { "type": "object", "description": "Schedule email request. Extends the standard send email request with a required `scheduled_at` field.", "allOf": [ { "$ref": "#/components/schemas/SendEmailRequest" }, { "type": "object", "required": [ "scheduled_at" ], "properties": { "scheduled_at": { "type": "string", "format": "date-time", "description": "The UTC date/time when the email should be sent. Must be at least 5 minutes in the future and within 3 days.", "example": "2024-01-16T10:00:00Z" } } } ] }, "ShowScheduledTransmissionResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "example": "Scheduled transmission retrieved successfully." }, "data": { "type": "object", "required": [ "transmission_id", "state", "from", "subject", "recipients", "num_recipients", "events" ], "properties": { "transmission_id": { "type": "string", "description": "The unique transmission ID.", "example": "12345678901234567890" }, "state": { "type": "string", "description": "Current state of the transmission. `submitted`/`generating` — still pending in SparkPost. `scheduled` — injected but not yet delivered (has `injection` event only). `delivered` — successfully delivered. `bounced` — rejected by recipient server. `failed` — generation or policy failure.", "enum": [ "submitted", "generating", "scheduled", "delivered", "bounced", "failed", "unknown" ], "example": "submitted" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The scheduled delivery time in ISO 8601 format. Present when the transmission is still pending. May be `null` when the transmission has already been delivered.", "example": "2024-01-16T10:00:00+00:00" }, "from": { "type": "string", "format": "email", "description": "Sender email address.", "example": "sender@example.com" }, "from_name": { "type": [ "string", "null" ], "description": "Sender display name.", "example": "Sender Name" }, "subject": { "type": "string", "description": "Email subject line.", "example": "Scheduled Newsletter" }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "List of recipient email addresses.", "example": [ "recipient@example.com" ] }, "num_recipients": { "type": "integer", "description": "Total number of recipients.", "example": 1 }, "events": { "type": "array", "description": "Delivery events for this transmission. Empty array when the email is still scheduled. Populated with delivery, bounce, open, click, and other events once the email has been processed.", "items": { "$ref": "#/components/schemas/EmailEvent" } } } } } }, "GetEmailDetailResponse": { "type": "object", "required": [ "message", "data" ], "description": "Email detail response. Uses the same data shape as the scheduled transmission detail — see `ShowScheduledTransmissionResponse` for field descriptions.", "properties": { "message": { "type": "string", "example": "Email retrieved successfully." }, "data": { "type": "object", "required": [ "transmission_id", "state", "from", "subject", "recipients", "num_recipients", "events" ], "properties": { "transmission_id": { "type": "string", "description": "The unique transmission ID (same as the `requestId` returned when the email was sent).", "example": "12345678901234567890" }, "state": { "type": "string", "description": "Derived delivery state based on events. `scheduled` — injected but not yet delivered. `delivered` — successfully delivered. `bounced` — rejected by recipient server. `failed` — generation or policy failure.", "enum": [ "scheduled", "delivered", "bounced", "failed" ], "example": "delivered" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The scheduled delivery time, if the email was scheduled. Usually `null` for immediately-sent emails.", "example": null }, "from": { "type": "string", "format": "email", "description": "Sender email address.", "example": "sender@example.com" }, "from_name": { "type": [ "string", "null" ], "description": "Sender display name.", "example": null }, "subject": { "type": "string", "description": "Email subject line.", "example": "Welcome to Lettr" }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Unique list of recipient email addresses derived from events.", "example": [ "recipient@example.com" ] }, "num_recipients": { "type": "integer", "description": "Total number of unique recipients.", "example": 1 }, "events": { "type": "array", "description": "Delivery events for this email (injection, delivery, bounce, open, click, etc.).", "items": { "$ref": "#/components/schemas/EmailEvent" } } } } } }, "ListEmailEventsResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string", "example": "Email events retrieved successfully." }, "data": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "object", "required": [ "data", "total_count", "from", "to", "pagination" ], "properties": { "data": { "type": "array", "description": "List of email events. Each event contains common fields plus type-specific fields (e.g. bounce events include bounce_class and reason, click events include target_link_url).", "items": { "$ref": "#/components/schemas/EmailEvent" } }, "total_count": { "type": "integer", "description": "Total number of events matching the query", "example": 2 }, "from": { "type": "string", "description": "Start of the date range used for the query", "example": "2024-01-05T00:00:00+00:00" }, "to": { "type": "string", "description": "End of the date range used for the query", "example": "2024-01-15T10:35:00+00:00" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page of results. Null if no more pages.", "example": null }, "per_page": { "type": "integer", "description": "Number of events per page", "example": 25 } } } } } } } } }, "EmailEvent": { "description": "An email event. The `type` field determines which additional fields are present. All event types share common fields defined in `CommonEventProperties`.", "oneOf": [ { "$ref": "#/components/schemas/InjectionEvent" }, { "$ref": "#/components/schemas/DeliveryEvent" }, { "$ref": "#/components/schemas/BounceEvent" }, { "$ref": "#/components/schemas/DelayEvent" }, { "$ref": "#/components/schemas/OutOfBandEvent" }, { "$ref": "#/components/schemas/SpamComplaintEvent" }, { "$ref": "#/components/schemas/PolicyRejectionEvent" }, { "$ref": "#/components/schemas/ClickEvent" }, { "$ref": "#/components/schemas/OpenEvent" }, { "$ref": "#/components/schemas/InitialOpenEvent" }, { "$ref": "#/components/schemas/AmpClickEvent" }, { "$ref": "#/components/schemas/AmpOpenEvent" }, { "$ref": "#/components/schemas/AmpInitialOpenEvent" }, { "$ref": "#/components/schemas/GenerationFailureEvent" }, { "$ref": "#/components/schemas/GenerationRejectionEvent" }, { "$ref": "#/components/schemas/ListUnsubscribeEvent" }, { "$ref": "#/components/schemas/LinkUnsubscribeEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "injection": "#/components/schemas/InjectionEvent", "delivery": "#/components/schemas/DeliveryEvent", "bounce": "#/components/schemas/BounceEvent", "delay": "#/components/schemas/DelayEvent", "out_of_band": "#/components/schemas/OutOfBandEvent", "spam_complaint": "#/components/schemas/SpamComplaintEvent", "policy_rejection": "#/components/schemas/PolicyRejectionEvent", "click": "#/components/schemas/ClickEvent", "open": "#/components/schemas/OpenEvent", "initial_open": "#/components/schemas/InitialOpenEvent", "amp_click": "#/components/schemas/AmpClickEvent", "amp_open": "#/components/schemas/AmpOpenEvent", "amp_initial_open": "#/components/schemas/AmpInitialOpenEvent", "generation_failure": "#/components/schemas/GenerationFailureEvent", "generation_rejection": "#/components/schemas/GenerationRejectionEvent", "list_unsubscribe": "#/components/schemas/ListUnsubscribeEvent", "link_unsubscribe": "#/components/schemas/LinkUnsubscribeEvent" } } }, "CommonEventProperties": { "type": "object", "required": [ "event_id", "type", "timestamp", "request_id", "rcpt_to", "raw_rcpt_to", "recipient_domain", "mailbox_provider", "mailbox_provider_region" ], "properties": { "event_id": { "type": "string", "description": "Unique identifier for the event", "example": "7609871845907017144" }, "type": { "type": "string", "description": "The event type", "enum": [ "injection", "delivery", "bounce", "delay", "out_of_band", "spam_complaint", "policy_rejection", "click", "open", "initial_open", "amp_click", "amp_open", "amp_initial_open", "generation_failure", "generation_rejection", "list_unsubscribe", "link_unsubscribe" ] }, "timestamp": { "type": "string", "description": "When the event occurred (ISO 8601)", "example": "2024-01-15T10:31:00.000Z" }, "request_id": { "type": "string", "description": "The transmission/request ID that generated this event", "example": "7610639000055488914" }, "rcpt_to": { "type": "string", "format": "email", "description": "Recipient email address", "example": "recipient@example.com" }, "raw_rcpt_to": { "type": "string", "format": "email", "description": "Original recipient email address before any modifications", "example": "recipient@example.com" }, "recipient_domain": { "type": "string", "description": "Domain of the recipient", "example": "example.com" }, "mailbox_provider": { "type": "string", "description": "Mailbox provider of the recipient", "example": "Gmail" }, "mailbox_provider_region": { "type": "string", "description": "Region of the mailbox provider", "example": "Global" }, "message_id": { "type": [ "string", "null" ], "description": "SMTP message ID", "example": "699715cd9e6961853a97" }, "subject": { "type": [ "string", "null" ], "description": "Email subject line", "example": "Welcome to Lettr" }, "friendly_from": { "type": [ "string", "null" ], "description": "Friendly from address", "example": "sender@example.com" }, "sending_domain": { "type": [ "string", "null" ], "description": "The sending domain", "example": "example.com" }, "sending_ip": { "type": [ "string", "null" ], "description": "IP address used to send the email", "example": "168.203.51.91" }, "click_tracking": { "type": [ "boolean", "null" ], "description": "Whether click tracking was enabled" }, "open_tracking": { "type": [ "boolean", "null" ], "description": "Whether open tracking was enabled" }, "transactional": { "type": [ "boolean", "null" ], "description": "Whether this was a transactional message" }, "msg_size": { "type": [ "integer", "null" ], "description": "Message size in bytes", "example": 30823 }, "injection_time": { "type": [ "string", "null" ], "description": "When the message was injected into the system (ISO 8601)", "example": "2024-01-15T10:30:00.000Z" }, "rcpt_meta": { "type": [ "array", "null" ], "description": "Recipient metadata" }, "campaign_id": { "type": [ "string", "null" ], "description": "Campaign identifier", "example": "welcome-series" }, "template_id": { "type": [ "string", "null" ], "description": "Template identifier", "example": "template_7610639000055488914" }, "template_version": { "type": [ "string", "null" ], "description": "Template version", "example": "0" }, "ip_pool": { "type": [ "string", "null" ], "description": "IP pool used for sending", "example": "default" }, "msg_from": { "type": [ "string", "null" ], "description": "Envelope sender (MAIL FROM)", "example": "msprvs1=abc123=bounces@sparkpostmail1.com" }, "rcpt_type": { "type": [ "string", "null" ], "description": "Recipient type" }, "rcpt_tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Recipient tags" }, "amp_enabled": { "type": [ "boolean", "null" ], "description": "Whether AMP was enabled" }, "delv_method": { "type": [ "string", "null" ], "description": "Delivery method (e.g. esmtp)", "example": "esmtp" }, "recv_method": { "type": [ "string", "null" ], "description": "Reception method (e.g. rest)", "example": "rest" }, "routing_domain": { "type": [ "string", "null" ], "description": "Routing domain", "example": "gmail.com" }, "scheduled_time": { "type": [ "string", "null" ], "description": "Scheduled delivery time if the email was scheduled" }, "ab_test_id": { "type": [ "string", "null" ], "description": "A/B test identifier" }, "ab_test_version": { "type": [ "string", "null" ], "description": "A/B test version" } } }, "UserAgentParsed": { "type": "object", "description": "Parsed user agent information from the open/click event.", "properties": { "agent_family": { "type": [ "string", "null" ], "description": "Browser or email client family", "example": "Edge" }, "device_brand": { "type": [ "string", "null" ], "description": "Device brand (e.g. Apple, Samsung)" }, "device_family": { "type": [ "string", "null" ], "description": "Device family (e.g. iPhone, Desktop)" }, "os_family": { "type": [ "string", "null" ], "description": "Operating system family", "example": "Windows" }, "os_version": { "type": [ "string", "null" ], "description": "Operating system version", "example": "10" }, "is_mobile": { "type": [ "boolean", "null" ], "description": "Whether the device is mobile" }, "is_proxy": { "type": [ "boolean", "null" ], "description": "Whether the request came through a proxy" }, "is_prefetched": { "type": [ "boolean", "null" ], "description": "Whether the open was prefetched by an email provider (e.g. Gmail Image Proxy, Apple Mail Privacy Protection). If true, this may not represent a real human open." } } }, "GeoIp": { "type": "object", "description": "Geolocation data derived from the IP address of the open/click event.", "properties": { "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code", "example": "CZ" }, "region": { "type": [ "string", "null" ], "description": "Region or state code", "example": "10" }, "city": { "type": [ "string", "null" ], "description": "City name", "example": "Prague" }, "latitude": { "type": [ "number", "null" ], "description": "Latitude", "example": 50.0883 }, "longitude": { "type": [ "number", "null" ], "description": "Longitude", "example": 14.4124 }, "zip": { "type": [ "string", "null" ], "description": "ZIP code", "example": "110" }, "postal_code": { "type": [ "string", "null" ], "description": "Postal code", "example": "110 00" } } }, "InjectionEvent": { "description": "Fired when a message is received by the system and queued for delivery.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "injection" ] }, "initial_pixel": { "type": [ "boolean", "null" ], "description": "Whether initial open tracking pixel was included" } } } ] }, "DeliveryEvent": { "description": "Fired when a message is successfully delivered to the recipient's mail server.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "delivery" ] }, "queue_time": { "type": [ "integer", "null" ], "description": "Time spent in queue in milliseconds", "example": 1845 }, "outbound_tls": { "type": [ "string", "null" ], "description": "Whether TLS was used for outbound delivery (\"1\" = yes)", "example": "1" } } } ] }, "BounceEvent": { "description": "Fired when a message is permanently rejected by the recipient's mail server.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bounce" ] }, "bounce_class": { "type": [ "integer", "null" ], "description": "Bounce classification code (e.g. 10 = Invalid Recipient, 30 = Generic Bounce)", "example": 10 }, "error_code": { "type": [ "string", "null" ], "description": "SMTP error code", "example": "550" }, "reason": { "type": [ "string", "null" ], "description": "Human-readable bounce reason", "example": "550 5.1.1 The email account that you tried to reach does not exist." }, "raw_reason": { "type": [ "string", "null" ], "description": "Raw SMTP reason string", "example": "550 5.1.1 User unknown" }, "num_retries": { "type": [ "integer", "null" ], "description": "Number of delivery retries attempted" }, "device_token": { "type": [ "string", "null" ], "description": "Device token if applicable" } } } ] }, "DelayEvent": { "description": "Fired when a message delivery is temporarily delayed (will be retried).", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "delay" ] }, "reason": { "type": [ "string", "null" ], "description": "Human-readable delay reason" }, "raw_reason": { "type": [ "string", "null" ], "description": "Raw SMTP reason string" }, "error_code": { "type": [ "string", "null" ], "description": "SMTP error code", "example": "421" }, "bounce_class": { "type": [ "integer", "null" ], "description": "Bounce classification code" }, "num_retries": { "type": [ "integer", "null" ], "description": "Number of delivery retries attempted so far" }, "queue_time": { "type": [ "integer", "null" ], "description": "Time spent in queue in milliseconds" }, "outbound_tls": { "type": [ "string", "null" ], "description": "Whether TLS was used for outbound delivery" } } } ] }, "OutOfBandEvent": { "description": "Fired when a remote mail server sends an asynchronous bounce after initially accepting the message.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "out_of_band" ] }, "bounce_class": { "type": [ "integer", "null" ], "description": "Bounce classification code" }, "error_code": { "type": [ "string", "null" ], "description": "SMTP error code" }, "reason": { "type": [ "string", "null" ], "description": "Human-readable bounce reason" }, "raw_reason": { "type": [ "string", "null" ], "description": "Raw SMTP reason string" }, "device_token": { "type": [ "string", "null" ], "description": "Device token if applicable" } } } ] }, "SpamComplaintEvent": { "description": "Fired when a recipient marks the message as spam via a feedback loop.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "spam_complaint" ] }, "fbtype": { "type": [ "string", "null" ], "description": "Feedback type (e.g. \"abuse\")", "example": "abuse" }, "report_by": { "type": [ "string", "null" ], "description": "Who reported the spam" }, "report_to": { "type": [ "string", "null" ], "description": "Where the spam report was sent" } } } ] }, "PolicyRejectionEvent": { "description": "Fired when a message is rejected due to policy (e.g. suppression list, rate limiting).", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "policy_rejection" ] }, "remote_addr": { "type": [ "string", "null" ], "description": "Remote IP address" }, "reason": { "type": [ "string", "null" ], "description": "Human-readable rejection reason" }, "raw_reason": { "type": [ "string", "null" ], "description": "Raw rejection reason" }, "error_code": { "type": [ "string", "null" ], "description": "Error code" }, "bounce_class": { "type": [ "integer", "null" ], "description": "Bounce classification code" } } } ] }, "ClickEvent": { "description": "Fired when a recipient clicks a tracked link in the email.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "click" ] }, "target_link_url": { "type": [ "string", "null" ], "description": "The URL that was clicked", "example": "https://example.com/reset-password?token=abc123" }, "target_link_name": { "type": [ "string", "null" ], "description": "The name/label of the clicked link" }, "user_agent": { "type": [ "string", "null" ], "description": "Raw user agent string", "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" }, "user_agent_parsed": { "$ref": "#/components/schemas/UserAgentParsed" }, "geo_ip": { "$ref": "#/components/schemas/GeoIp" }, "ip_address": { "type": [ "string", "null" ], "description": "IP address of the click", "example": "104.28.114.11" } } } ] }, "OpenEvent": { "description": "Fired when a recipient opens the email (subsequent opens after the initial open).", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "open" ] }, "user_agent": { "type": [ "string", "null" ], "description": "Raw user agent string", "example": "Mozilla/5.0" }, "user_agent_parsed": { "$ref": "#/components/schemas/UserAgentParsed" }, "geo_ip": { "$ref": "#/components/schemas/GeoIp" }, "ip_address": { "type": [ "string", "null" ], "description": "IP address of the open", "example": "104.28.114.11" }, "initial_pixel": { "type": [ "boolean", "null" ], "description": "Whether this was triggered by the initial tracking pixel" } } } ] }, "InitialOpenEvent": { "description": "Fired the first time a recipient opens the email.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "initial_open" ] }, "user_agent": { "type": [ "string", "null" ], "description": "Raw user agent string", "example": "Mozilla/5.0" }, "user_agent_parsed": { "$ref": "#/components/schemas/UserAgentParsed" }, "geo_ip": { "$ref": "#/components/schemas/GeoIp" }, "ip_address": { "type": [ "string", "null" ], "description": "IP address of the open", "example": "104.28.114.11" }, "initial_pixel": { "type": [ "boolean", "null" ], "description": "Whether this was triggered by the initial tracking pixel" } } } ] }, "AmpClickEvent": { "description": "Fired when a recipient clicks a tracked link in an AMP email.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "amp_click" ] }, "target_link_url": { "type": [ "string", "null" ], "description": "The URL that was clicked" }, "target_link_name": { "type": [ "string", "null" ], "description": "The name/label of the clicked link" }, "user_agent": { "type": [ "string", "null" ], "description": "Raw user agent string" }, "user_agent_parsed": { "$ref": "#/components/schemas/UserAgentParsed" }, "geo_ip": { "$ref": "#/components/schemas/GeoIp" }, "ip_address": { "type": [ "string", "null" ], "description": "IP address of the click" } } } ] }, "AmpOpenEvent": { "description": "Fired when a recipient opens an AMP email (subsequent opens).", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "amp_open" ] }, "user_agent": { "type": [ "string", "null" ], "description": "Raw user agent string" }, "user_agent_parsed": { "$ref": "#/components/schemas/UserAgentParsed" }, "geo_ip": { "$ref": "#/components/schemas/GeoIp" }, "ip_address": { "type": [ "string", "null" ], "description": "IP address of the open" }, "initial_pixel": { "type": [ "boolean", "null" ], "description": "Whether this was triggered by the initial tracking pixel" } } } ] }, "AmpInitialOpenEvent": { "description": "Fired the first time a recipient opens an AMP email.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "amp_initial_open" ] }, "user_agent": { "type": [ "string", "null" ], "description": "Raw user agent string" }, "user_agent_parsed": { "$ref": "#/components/schemas/UserAgentParsed" }, "geo_ip": { "$ref": "#/components/schemas/GeoIp" }, "ip_address": { "type": [ "string", "null" ], "description": "IP address of the open" }, "initial_pixel": { "type": [ "boolean", "null" ], "description": "Whether this was triggered by the initial tracking pixel" } } } ] }, "GenerationFailureEvent": { "description": "Fired when the system fails to generate a message (e.g. template rendering error).", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "generation_failure" ] }, "reason": { "type": [ "string", "null" ], "description": "Human-readable failure reason" }, "raw_reason": { "type": [ "string", "null" ], "description": "Raw failure reason" }, "error_code": { "type": [ "string", "null" ], "description": "Error code" } } } ] }, "GenerationRejectionEvent": { "description": "Fired when the system rejects message generation (e.g. policy violation).", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "generation_rejection" ] }, "reason": { "type": [ "string", "null" ], "description": "Human-readable rejection reason" }, "raw_reason": { "type": [ "string", "null" ], "description": "Raw rejection reason" }, "error_code": { "type": [ "string", "null" ], "description": "Error code" } } } ] }, "ListUnsubscribeEvent": { "description": "Fired when a recipient uses the List-Unsubscribe header to unsubscribe.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "list_unsubscribe" ] } } } ] }, "LinkUnsubscribeEvent": { "description": "Fired when a recipient clicks an unsubscribe link in the email body.", "allOf": [ { "$ref": "#/components/schemas/CommonEventProperties" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "link_unsubscribe" ] } } } ] }, "ListEmailsResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string" }, "data": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "object", "required": [ "data", "total_count", "from", "to", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SentEmailListItem" } }, "total_count": { "type": "integer", "description": "Total number of matching emails" }, "from": { "type": "string", "format": "date-time", "description": "Start of the query date range" }, "to": { "type": "string", "format": "date-time", "description": "End of the query date range" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more results" }, "per_page": { "type": "integer" } } } } } } } } }, "SentEmailListItem": { "type": "object", "required": [ "event_id", "type", "timestamp" ], "properties": { "event_id": { "type": "string" }, "type": { "type": "string", "description": "SparkPost event type (e.g., injection)" }, "timestamp": { "type": "string", "format": "date-time" }, "request_id": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "friendly_from": { "type": [ "string", "null" ] }, "sending_domain": { "type": [ "string", "null" ] }, "rcpt_to": { "type": [ "string", "null" ] }, "raw_rcpt_to": { "type": [ "string", "null" ] }, "recipient_domain": { "type": [ "string", "null" ] }, "mailbox_provider": { "type": [ "string", "null" ] }, "mailbox_provider_region": { "type": [ "string", "null" ] }, "sending_ip": { "type": [ "string", "null" ] }, "click_tracking": { "type": [ "boolean", "null" ] }, "open_tracking": { "type": [ "boolean", "null" ] }, "transactional": { "type": [ "boolean", "null" ] }, "msg_size": { "type": [ "integer", "null" ] }, "injection_time": { "type": [ "string", "null" ], "format": "date-time" }, "rcpt_meta": { "type": [ "object", "null" ], "additionalProperties": true } } }, "GetTemplateHtmlResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "html", "merge_tags" ], "properties": { "html": { "type": "string", "description": "The template HTML content" }, "merge_tags": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "required" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "required": { "type": "boolean" } } } }, "subject": { "type": [ "string", "null" ], "description": "The template subject line, if set" } } } } }, "ListProjectsResponse": { "type": "object", "required": [ "message", "data" ], "properties": { "message": { "type": "string" }, "data": { "type": "object", "required": [ "projects", "pagination" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectView" } }, "pagination": { "$ref": "#/components/schemas/ProjectsPagination" } } } } }, "ProjectView": { "type": "object", "required": [ "id", "name", "team_id", "created_at", "updated_at" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "emoji": { "type": [ "string", "null" ] }, "team_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProjectsPagination": { "type": "object", "required": [ "total", "per_page", "current_page", "last_page" ], "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" } } } } }, "tags": [ { "name": "Emails", "description": "Email sending operations" }, { "name": "Templates", "description": "Email template management operations" }, { "name": "Domains", "description": "Domain management operations" }, { "name": "Webhooks", "description": "Webhook management operations" } ] }