{ "openapi": "3.0.0", "info": { "title": "Kirim.Email SMTP API Documentation", "description": "Kirim.Email SMTP Domain and credential management API Documentation", "contact": { "email": "support@kirim.email" }, "version": "1.0.0" }, "servers": [ { "url": "https://smtp-app.kirim.email", "description": "Application server" } ], "paths": { "/api/domains/{domain}/credentials": { "get": { "tags": [ "Credentials" ], "summary": "Get domain credentials", "description": "Retrieve a paginated list of SMTP credentials for a domain", "operationId": "d9ba7dafcd024c2a47790065816f4e86", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "limit", "in": "query", "description": "Number of credentials per page", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates if the request was successful", "type": "boolean", "example": true }, "data": { "description": "Array of credential objects with pagination metadata", "type": "array", "items": { "$ref": "#/components/schemas/Credential" } }, "domain": { "description": "Domain name for which credentials are listed", "type": "string", "example": "example.com" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/CredentialUnauthorized" }, "404": { "$ref": "#/components/responses/CredentialNotFound" }, "429": { "$ref": "#/components/responses/CredentialTooManyRequests" }, "500": { "$ref": "#/components/responses/CredentialServerError" } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Credentials" ], "summary": "Create a new credential", "description": "Create a new SMTP credential for a domain", "operationId": "3ba562c18c4a84e46afa1637b5819104", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "description": "SMTP credential creation details", "required": true, "content": { "application/json": { "schema": { "required": [ "username" ], "properties": { "username": { "description": "SMTP username", "type": "string", "example": "myuser" } }, "type": "object" } }, "multipart/form-data": { "schema": { "required": [ "username" ], "properties": { "username": { "description": "SMTP username", "type": "string", "example": "myuser" } }, "type": "object" } } } }, "responses": { "201": { "description": "Credential created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates if the request was successful", "type": "boolean", "example": true }, "message": { "description": "Human-readable success message", "type": "string", "example": "Credential created successfully." }, "data": { "description": "Created credential data and metadata", "properties": { "credential": { "$ref": "#/components/schemas/Credential" }, "password": { "description": "Generated password for the credential. Store this securely as it cannot be retrieved later", "type": "string", "example": "generated-password" }, "remote_synced": { "description": "Whether the credential was successfully synchronized with the remote SMTP server", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/CredentialUnauthorized" }, "404": { "$ref": "#/components/responses/CredentialNotFound" }, "422": { "$ref": "#/components/responses/CredentialValidationError" }, "429": { "$ref": "#/components/responses/CredentialTooManyRequests" }, "500": { "$ref": "#/components/responses/CredentialServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/credentials/{credential}": { "get": { "tags": [ "Credentials" ], "summary": "Get credential details", "description": "Retrieve details of a specific SMTP credential", "operationId": "dbb33bc3eaa899b41440947123096fe7", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "credential", "in": "path", "description": "Credential GUID (user_smtp_guid)", "required": true, "schema": { "type": "string", "format": "uuid", "example": "92703823-f3a4-48e2-8e87-7adf25454800" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates if the request was successful", "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Credential" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/CredentialUnauthorized" }, "403": { "$ref": "#/components/responses/CredentialForbidden" }, "404": { "$ref": "#/components/responses/CredentialNotFound" }, "429": { "$ref": "#/components/responses/CredentialTooManyRequests" }, "500": { "$ref": "#/components/responses/CredentialServerError" } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Credentials" ], "summary": "Delete credential", "description": "Delete a specific SMTP credential", "operationId": "d3f52c115e7013a47d348b9e2743a2c1", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "credential", "in": "path", "description": "Credential GUID (user_smtp_guid)", "required": true, "schema": { "type": "string", "format": "uuid", "example": "92703823-f3a4-48e2-8e87-7adf25454800" } } ], "responses": { "204": { "description": "Credential deleted successfully", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } } }, "401": { "$ref": "#/components/responses/CredentialUnauthorized" }, "403": { "$ref": "#/components/responses/CredentialForbidden" }, "404": { "$ref": "#/components/responses/CredentialNotFound" }, "429": { "$ref": "#/components/responses/CredentialTooManyRequests" }, "500": { "$ref": "#/components/responses/CredentialServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/credentials/{credential}/reset-password": { "put": { "tags": [ "Credentials" ], "summary": "Reset credential password", "description": "Reset the password for a specific SMTP credential", "operationId": "3bb48e47b58f0aa9c096797e224cbdf3", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "credential", "in": "path", "description": "Credential GUID (user_smtp_guid)", "required": true, "schema": { "type": "string", "format": "uuid", "example": "92703823-f3a4-48e2-8e87-7adf25454800" } } ], "responses": { "200": { "description": "Password reset successfully", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates if the request was successful", "type": "boolean", "example": true }, "message": { "description": "Human-readable success message", "type": "string", "example": "Password reset successfully." }, "data": { "description": "Password reset result data", "properties": { "credential": { "$ref": "#/components/schemas/Credential" }, "new_password": { "description": "The new generated password. Store this securely as it cannot be retrieved later", "type": "string", "example": "new-generated-password" }, "strength_info": { "description": "Password strength analysis and complexity information", "type": "object" }, "remote_synced": { "description": "Whether the password change was successfully synchronized with the remote SMTP server", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/CredentialUnauthorized" }, "403": { "$ref": "#/components/responses/CredentialForbidden" }, "404": { "$ref": "#/components/responses/CredentialNotFound" }, "429": { "$ref": "#/components/responses/CredentialTooManyRequests" }, "500": { "$ref": "#/components/responses/CredentialServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains": { "get": { "tags": [ "Domains" ], "summary": "Get user domains", "description": "Retrieve a paginated list of domains for authenticated user", "operationId": "007dad882bbac6f56df37906d3926a73", "parameters": [ { "name": "limit", "in": "query", "description": "Number of domains per page", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search domains by name", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved paginated list of domains owned by the authenticated user", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates if the request was successful", "type": "boolean", "example": true }, "data": { "description": "Array of domain objects for the authenticated user", "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Domains" ], "summary": "Create a new domain", "description": "Add a new domain to the authenticated user's account", "operationId": "624385e5a50c4084d78a561453143b30", "requestBody": { "description": "Domain configuration details for creating a new domain", "required": true, "content": { "application/json": { "schema": { "required": [ "domain", "dkim_key_length" ], "properties": { "domain": { "description": "Domain name", "type": "string", "example": "example.com" }, "dkim_key_length": { "description": "DKIM key length", "type": "integer", "example": 2048, "enum": [ 1024, 2048 ] } }, "type": "object" } }, "multipart/form-data": { "schema": { "required": [ "domain", "dkim_key_length" ], "properties": { "domain": { "description": "Domain name", "type": "string", "example": "example.com" }, "dkim_key_length": { "description": "DKIM key length", "type": "integer", "example": 2048, "enum": [ 1024, 2048 ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Domain created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates if the request was successful", "type": "boolean", "example": true }, "message": { "description": "Human-readable success message", "type": "string", "example": "Domain added successfully." }, "data": { "description": "Created domain information", "properties": { "domain": { "description": "The domain name that was successfully created", "type": "string", "example": "example.com" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "422": { "$ref": "#/components/responses/DomainValidationError" }, "409": { "$ref": "#/components/responses/DomainConflict" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" }, "500": { "$ref": "#/components/responses/DomainServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}": { "get": { "tags": [ "Domains" ], "summary": "Get domain details", "description": "Retrieve details of a specific domain", "operationId": "600be6f470c4aa49f55abd86bde1c6d8", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "Successfully retrieved domain details including verification status and configuration", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates if the request was successful", "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Domain" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" } }, "security": [ { "basicAuth": [] } ] }, "put": { "tags": [ "Domains" ], "summary": "Update domain configuration", "description": "Update tracking settings for a domain", "operationId": "d745f34d3f7e5a4eb985cb41efdf3ef9", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "description": "Domain tracking configuration updates", "required": false, "content": { "application/json": { "schema": { "properties": { "open_track": { "description": "Enable open tracking", "type": "boolean", "example": true }, "click_track": { "description": "Enable click tracking", "type": "boolean", "example": true }, "unsub_track": { "description": "Enable unsubscribe tracking", "type": "boolean", "example": true } }, "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "open_track": { "description": "Enable open tracking", "type": "boolean", "example": true }, "click_track": { "description": "Enable click tracking", "type": "boolean", "example": true }, "unsub_track": { "description": "Enable unsubscribe tracking", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Domain updated successfully", "content": { "application/json": { "schema": { "properties": { "data": { "description": "Updated domain tracking configuration", "properties": { "open_track": { "description": "Whether open tracking is enabled for emails sent from this domain", "type": "boolean", "example": true }, "click_track": { "description": "Whether click tracking is enabled for emails sent from this domain", "type": "boolean", "example": true }, "unsub_track": { "description": "Whether unsubscribe tracking is enabled for emails sent from this domain", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "422": { "$ref": "#/components/responses/DomainValidationError" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" }, "500": { "$ref": "#/components/responses/DomainServerError" } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Domains" ], "summary": "Delete domain", "description": "Remove a domain from the authenticated user's account", "operationId": "708279d42df8762576ecbf2879bf11f9", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "responses": { "204": { "description": "Domain deleted successfully", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/setup-auth-domain": { "post": { "tags": [ "Domains" ], "summary": "Setup authentication domain", "description": "Configure an authentication domain for a domain", "operationId": "891f43606fa4a9bb5239e690d0122f98", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "dkim_key_length" ], "properties": { "auth_domain": { "description": "Authentication domain", "type": "string", "example": "auth.example.com" }, "dkim_key_length": { "description": "DKIM key length", "type": "integer", "example": 2048, "enum": [ 1024, 2048 ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Authentication domain setup successfully", "content": { "application/json": { "schema": { "properties": { "data": { "description": "Authentication domain configuration", "properties": { "auth_domain": { "description": "The authentication domain that was successfully configured for DKIM and email authentication", "type": "string", "example": "auth.example.com" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "422": { "$ref": "#/components/responses/DomainValidationError" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" }, "500": { "$ref": "#/components/responses/DomainServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/verify-mandatory": { "post": { "tags": [ "Domains" ], "summary": "Verify mandatory DNS records", "description": "Verify DKIM and SPF DNS records for a domain. MX record validation is optional.", "operationId": "56ee3b2ebea51e570144973a25fd697d", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "DNS verification completed", "content": { "application/json": { "schema": { "properties": { "records": { "description": "DNS record validation results", "properties": { "dkim": { "description": "Whether DKIM record is valid and properly configured", "type": "boolean", "example": true }, "spf": { "description": "Whether SPF record is valid and properly configured", "type": "boolean", "example": true }, "mx": { "description": "Whether MX record is valid and properly configured", "type": "boolean", "example": true }, "a": { "description": "Whether A record is valid (optional)", "type": "boolean", "example": true }, "dmarc": { "description": "Whether DMARC record is valid (optional)", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" }, "500": { "$ref": "#/components/responses/DomainServerError" }, "503": { "$ref": "#/components/responses/DomainDnsLookupTemporaryFailure" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/verify-auth-domain": { "post": { "tags": [ "Domains" ], "summary": "Verify authentication domain DNS records", "description": "Verify DKIM and SPF DNS records for authentication domain. MX record validation is optional.", "operationId": "f105077a578d254a5ec6b14307499918", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "Auth domain DNS verification completed", "content": { "application/json": { "schema": { "properties": { "records": { "description": "Authentication domain DNS record validation results", "properties": { "auth_dkim": { "description": "Whether authentication domain DKIM record is valid and properly configured", "type": "boolean", "example": true }, "auth_spf": { "description": "Whether authentication domain SPF record is valid and properly configured", "type": "boolean", "example": true }, "auth_mx": { "description": "Whether authentication domain MX record is valid and properly configured", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "422": { "$ref": "#/components/responses/DomainValidationError" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" }, "500": { "$ref": "#/components/responses/DomainServerError" }, "503": { "$ref": "#/components/responses/DomainDnsLookupTemporaryFailure" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/setup-tracklink": { "post": { "tags": [ "Domains" ], "summary": "Setup tracking domain", "description": "Configure a tracking domain for click and open tracking", "operationId": "3663ec9709b87ac389d23cad2cc3d3fe", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tracking_domain" ], "properties": { "tracking_domain": { "description": "Tracking domain for click and open tracking", "type": "string", "example": "track.example.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tracking domain setup successfully", "content": { "application/json": { "schema": { "properties": { "data": { "description": "Tracking domain configuration", "properties": { "tracking_domain": { "description": "The tracking domain that was successfully configured for click and open tracking", "type": "string", "example": "track.example.com" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "422": { "$ref": "#/components/responses/DomainValidationError" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" }, "500": { "$ref": "#/components/responses/DomainServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/verify-tracklink": { "post": { "tags": [ "Domains" ], "summary": "Verify tracking domain DNS records", "description": "Verify CNAME record for tracking domain configuration", "operationId": "f02a3b48a14aa8ff86d5445027d73327", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "Tracking domain verification completed", "content": { "application/json": { "schema": { "properties": { "records": { "description": "Tracking domain DNS validation results", "properties": { "cname": { "description": "Whether CNAME record is valid and properly configured", "type": "boolean", "example": true }, "tracking_domain": { "description": "The tracking domain that was verified", "type": "string", "example": "track.example.com" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "422": { "$ref": "#/components/responses/DomainValidationError" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" }, "500": { "$ref": "#/components/responses/DomainServerError" }, "503": { "$ref": "#/components/responses/DomainDnsLookupTemporaryFailure" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/auth-domain": { "delete": { "tags": [ "Domains" ], "summary": "Remove authentication domain", "description": "Remove the authentication domain from a domain", "operationId": "b21ef8bb64f55828d24e09a53e1ec739", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "responses": { "204": { "description": "Authentication domain removed successfully", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" }, "500": { "$ref": "#/components/responses/DomainServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/tracklink": { "delete": { "tags": [ "Domains" ], "summary": "Remove tracking domain", "description": "Remove the tracking domain from a domain", "operationId": "a7a67bc0f4628c2d7f6d7c0227d806bd", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "responses": { "204": { "description": "Tracking domain removed successfully", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } } }, "401": { "$ref": "#/components/responses/DomainUnauthorized" }, "404": { "$ref": "#/components/responses/DomainNotFound" }, "429": { "$ref": "#/components/responses/DomainTooManyRequests" }, "500": { "$ref": "#/components/responses/DomainServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/email/validate": { "post": { "tags": [ "Email Validation" ], "summary": "Validate a single email address", "description": "Comprehensive email validation including RFC compliance, DNS checks, and blocklist validation. Results are cached for performance.", "operationId": "fc91ed9af223697d7fb92ab520e2eb70", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "description": "The email address to validate", "type": "string", "format": "email", "example": "user@example.com", "maxLength": 254 } }, "type": "object" } }, "multipart/form-data": { "schema": { "required": [ "email" ], "properties": { "email": { "description": "The email address to validate", "type": "string", "format": "email", "example": "user@example.com", "maxLength": 254 } }, "type": "object" } } } }, "responses": { "200": { "description": "Email validation completed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EmailValidationResult" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/EmailValidationBadRequest" }, "401": { "$ref": "#/components/responses/EmailValidationUnauthorized" }, "429": { "$ref": "#/components/responses/EmailValidationTooManyRequests" }, "500": { "$ref": "#/components/responses/EmailValidationServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/email/validate/strict": { "post": { "tags": [ "Email Validation" ], "summary": "Validate a single email address with strict mode", "description": "Strict email validation including RFC compliance with no warnings, comprehensive DNS checks, and blocklist validation. Results are cached for performance.", "operationId": "96874999da39716bd1d732c32488670e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email" ], "properties": { "email": { "description": "The email address to validate", "type": "string", "format": "email", "example": "user@example.com", "maxLength": 254 } }, "type": "object" } }, "multipart/form-data": { "schema": { "required": [ "email" ], "properties": { "email": { "description": "The email address to validate", "type": "string", "format": "email", "example": "user@example.com", "maxLength": 254 } }, "type": "object" } } } }, "responses": { "200": { "description": "Strict email validation completed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EmailValidationResult" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/EmailValidationBadRequest" }, "401": { "$ref": "#/components/responses/EmailValidationUnauthorized" }, "429": { "$ref": "#/components/responses/EmailValidationTooManyRequests" }, "500": { "$ref": "#/components/responses/EmailValidationServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/email/validate/bulk": { "post": { "tags": [ "Email Validation" ], "summary": "Validate multiple email addresses", "description": "Batch email validation with comprehensive checks. Optimized with caching - only uncached emails are processed. Maximum 100 emails per batch.", "operationId": "6fd7f992f851a3b8586c4e6739260037", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "emails" ], "properties": { "emails": { "description": "Array of email addresses to validate (max 100)", "type": "array", "items": { "type": "string", "format": "email", "example": "user@example.com", "maxLength": 254 }, "example": { "emails": [ "user1@example.com", "user2@test.org", "invalid-email" ] }, "maxItems": 100 } }, "type": "object" } }, "multipart/form-data": { "schema": { "required": [ "emails" ], "properties": { "emails": { "description": "Array of email addresses to validate (max 100)", "type": "array", "items": { "type": "string", "format": "email", "example": "user@example.com", "maxLength": 254 }, "maxItems": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Batch email validation completed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EmailValidationBatchResult" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/EmailValidationBadRequest" }, "401": { "$ref": "#/components/responses/EmailValidationUnauthorized" }, "429": { "$ref": "#/components/responses/EmailValidationTooManyRequests" }, "500": { "$ref": "#/components/responses/EmailValidationServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/email/validate/bulk/strict": { "post": { "tags": [ "Email Validation" ], "summary": "Validate multiple email addresses with strict mode", "description": "Batch strict email validation with comprehensive checks. Uses RFC validation with no warnings, comprehensive DNS checks, and blocklist validation. Optimized with caching - only uncached emails are processed. Maximum 100 emails per batch.", "operationId": "3dcfb8a953f07f9b48d77e55f1a6b66a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "emails" ], "properties": { "emails": { "description": "Array of email addresses to validate (max 100)", "type": "array", "items": { "type": "string", "format": "email", "example": "user@example.com", "maxLength": 254 }, "example": { "emails": [ "user1@example.com", "user2@test.org", "invalid-email" ] }, "maxItems": 100 } }, "type": "object" } }, "multipart/form-data": { "schema": { "required": [ "emails" ], "properties": { "emails": { "description": "Array of email addresses to validate (max 100)", "type": "array", "items": { "type": "string", "format": "email", "example": "user@example.com", "maxLength": 254 }, "maxItems": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Batch strict email validation completed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EmailValidationBatchResult" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/EmailValidationBadRequest" }, "401": { "$ref": "#/components/responses/EmailValidationUnauthorized" }, "429": { "$ref": "#/components/responses/EmailValidationTooManyRequests" }, "500": { "$ref": "#/components/responses/EmailValidationServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/log": { "get": { "tags": [ "Logs" ], "summary": "Get logs for authenticated user domain", "description": "Retrieve logs for a specific domain owned by the authenticated user", "operationId": "7c2562bf981ec76c90759e249b19b37f", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "start", "in": "query", "description": "Filter logs by start date (ISO8601)", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" } }, { "name": "end", "in": "query", "description": "Filter logs by end date (ISO8601)", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2023-12-31T23:59:59Z" } }, { "name": "sender", "in": "query", "description": "Filter logs by sender email", "required": false, "schema": { "type": "string", "example": "sender@example.com" } }, { "name": "recipient", "in": "query", "description": "Filter logs by recipient email", "required": false, "schema": { "type": "string", "example": "recipient@example.com" } }, { "name": "subject", "in": "query", "description": "Filter logs by subject (partial match)", "required": false, "schema": { "type": "string", "example": "Welcome" } }, { "name": "event_type", "in": "query", "description": "Filter logs by event type (queued, send, delivered, bounced, failed, opened, clicked, unsubscribed, temporary_fail, permanent_fail, deferred)", "required": false, "schema": { "type": "string", "example": "delivered" } }, { "name": "tags", "in": "query", "description": "Filter logs by tags (partial match)", "required": false, "schema": { "type": "string", "example": "newsletter" } }, { "name": "limit", "in": "query", "description": "Number of logs per page", "required": false, "schema": { "type": "integer", "default": 1000, "maximum": 10000, "minimum": 1 } }, { "name": "offset", "in": "query", "description": "Offset for pagination", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "count": { "type": "integer", "example": 100 }, "offset": { "type": "integer", "example": 0 }, "limit": { "type": "integer", "example": 1000 }, "pagination": { "properties": { "total": { "type": "integer", "example": 500 }, "per_page": { "type": "integer", "example": 1000 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/LogBadRequest" }, "401": { "$ref": "#/components/responses/LogUnauthorized" }, "404": { "$ref": "#/components/responses/LogNotFound" }, "429": { "$ref": "#/components/responses/LogTooManyRequests" }, "500": { "$ref": "#/components/responses/LogServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/log/{message_guid}": { "get": { "tags": [ "Logs" ], "summary": "Get logs for specific message in user domain", "description": "Retrieve all logs for a specific message in a domain owned by the authenticated user", "operationId": "7ee71943ae62b35a0715d4a9cff2862a", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "message_guid", "in": "path", "description": "Message GUID", "required": true, "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "data": { "description": "Array of log entries for the specific message in the user's domain", "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/LogBadRequest" }, "401": { "$ref": "#/components/responses/LogUnauthorized" }, "404": { "$ref": "#/components/responses/LogNotFound" }, "429": { "$ref": "#/components/responses/LogTooManyRequests" }, "500": { "$ref": "#/components/responses/LogServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/log/stream": { "get": { "tags": [ "Logs" ], "summary": "Stream logs for authenticated user domain in real-time", "description": "Stream email logs in real-time using Server-Sent Events for a domain owned by the authenticated user", "operationId": "c97985f24739a57a07ef9c4ae17135b4", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "start", "in": "query", "description": "Filter logs by start date (ISO8601)", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" } }, { "name": "end", "in": "query", "description": "Filter logs by end date (ISO8601)", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2023-12-31T23:59:59Z" } }, { "name": "sender", "in": "query", "description": "Filter logs by sender email", "required": false, "schema": { "type": "string", "example": "sender@example.com" } }, { "name": "recipient", "in": "query", "description": "Filter logs by recipient email", "required": false, "schema": { "type": "string", "example": "recipient@example.com" } }, { "name": "subject", "in": "query", "description": "Filter logs by subject (partial match)", "required": false, "schema": { "type": "string", "example": "Welcome" } }, { "name": "event_type", "in": "query", "description": "Filter logs by event type (queued, delivered, bounced, failed, opened, clicked, unsubscribed, temporary_fail, permanent_fail, deferred)", "required": false, "schema": { "type": "string", "example": "delivered" } }, { "name": "tags", "in": "query", "description": "Filter logs by tags (partial match)", "required": false, "schema": { "type": "string", "example": "newsletter" } }, { "name": "limit", "in": "query", "description": "Maximum number of logs to stream", "required": false, "schema": { "type": "integer", "default": 50000, "maximum": 500000, "minimum": 1 } } ], "responses": { "200": { "description": "Server-Sent Events stream", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "text/event-stream": { "schema": { "description": "SSE stream with log data batches and completion events", "type": "string" } } } }, "400": { "$ref": "#/components/responses/LogBadRequest" }, "401": { "$ref": "#/components/responses/LogUnauthorized" }, "404": { "$ref": "#/components/responses/LogNotFound" }, "429": { "$ref": "#/components/responses/LogTooManyRequests" }, "500": { "$ref": "#/components/responses/LogServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/message": { "post": { "tags": [ "Message" ], "summary": "Send transactional email for user domain with optional attachments", "description": "Send a transactional email for a specific domain owned by the authenticated user. This endpoint is designed for user-authenticated requests where the user owns and manages the domain. Supports comprehensive email customization, bulk sending, file attachments with advanced processing, and asynchronous job handling for optimal performance. Perfect for building custom email solutions and transactional workflows.", "operationId": "1be688750591647e7ef9b61ba34b6d93", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. This domain must be verified and configured with SMTP credentials.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "description": "Complete email configuration including content, recipients, and optional attachments with processing options.", "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "from", "to", "subject", "text" ], "properties": { "from": { "description": "Sender email address. Must belong to the authenticated domain. Used for envelope sender and Return-Path header.", "type": "string", "format": "email", "example": "noreply@example.com" }, "from_name": { "description": "Optional sender display name. If not provided, will use the email address only.", "type": "string", "example": "Company Name" }, "to": { "description": "Recipient email address(es). Single email string or array of emails for bulk sending. Maximum 1000 recipients per request.", "oneOf": [ { "type": "string", "format": "email", "example": "customer@clientdomain.com" }, { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "customer1@clientdomain.com", "customer2@anotherdomain.com", "user@example.org" ], "maxItems": 1000 } ] }, "subject": { "description": "Email subject line. Supports Unicode characters, emojis, and variable content. Keep under 78 characters for optimal display across email clients.", "type": "string", "example": "Your Order Confirmation - #12345" }, "text": { "description": "Required plain text content for the email body. This will be used as fallback for email clients that don't support HTML. Line breaks will be preserved.", "type": "string", "example": "Dear Valued Customer,\\n\\nThank you for your recent order #12345. Your items are being prepared for shipment.\\n\\nOrder Details:\\n- Product: Premium Widget\\n- Quantity: 2\\n- Total: $49.99\\n\\nTracking information will be sent once your order ships.\\n\\nBest regards,\\nCustomer Service Team" }, "html": { "description": "Optional HTML content for the email body. If provided, this will be used for HTML email clients. Should be a complete HTML document or HTML fragment.", "type": "string", "example": "

Order Confirmation - #12345

Dear Valued Customer,

Thank you for your recent order #12345. Your items are being prepared for shipment.

Order Details:

Tracking information will be sent once your order ships.

Best regards,
Customer Service Team

" }, "headers": { "description": "Optional custom email headers. Can be provided as an object or JSON string. Common use cases include tracking headers, priority settings, X-Tags for log filtering, and unsubscribe links.", "oneOf": [ { "type": "object", "example": { "X-Order-ID": "12345", "X-Customer-Tier": "premium", "X-Tags": "newsletter,promo", "List-Unsubscribe": "mailto:unsubscribe@example.com", "X-Priority": "3" } }, { "type": "string", "example": "{\"X-Order-ID\": \"12345\", \"X-Customer-Tier\": \"premium\", \"X-Tags\": \"newsletter,promo\"}" } ] }, "reply_to": { "description": "Reply-to email address. Must share the same top-level domain as the 'from' address for security compliance.", "type": "string", "format": "email", "example": "support@example.com" }, "attachments": { "description": "File attachment(s). Single file or array of files. Maximum 10 files per email, 20MB per file, 25MB total payload. Supports documents, images, and archives with optional processing.", "oneOf": [ { "description": "Single file attachment", "type": "string", "format": "binary" }, { "description": "Multiple file attachments", "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 10 } ] }, "attachment_options": { "description": "Advanced attachment processing configuration as JSON string. Enables compression, password protection, and watermarking features.", "type": "string", "example": "{\"compress\": true, \"password\": \"SecureDoc2024\", \"watermark\": {\"enabled\": true, \"text\": \"CONFIDENTIAL\", \"position\": \"center\"}}" } }, "type": "object" } } } }, "responses": { "202": { "description": "Email send jobs successfully dispatched for asynchronous processing", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "description": "Request processing success status", "type": "boolean", "example": true }, "message": { "description": "Detailed success message including recipient count, job batching information, and attachment count", "type": "string", "example": "Email send jobs dispatched for 5 recipients in 1 job(s) with 2 attachment(s)" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/MessageBadRequest" }, "401": { "$ref": "#/components/responses/MessageUnauthorized" }, "404": { "$ref": "#/components/responses/MessageNotFound" }, "422": { "$ref": "#/components/responses/MessageValidationError" }, "429": { "$ref": "#/components/responses/MessageTooManyRequests" }, "500": { "$ref": "#/components/responses/MessageServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/message/template": { "post": { "tags": [ "Message" ], "summary": "Send transactional email for user domain using a saved template", "description": "Send an email for a domain owned by the authenticated user using a stored template. Supports variable replacement using {{variable}} syntax in both subject and content. Template must belong to the authenticated domain. Supports attachments with the same processing options as non-template message endpoint.", "operationId": "b42f46d598302983ded09154c7d1de6e", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "template_guid", "to" ], "properties": { "template_guid": { "description": "UUID of the template to use", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "to": { "description": "Recipient email address(es). Single email string or array of emails for bulk sending. Maximum 1000 recipients per request.", "oneOf": [ { "type": "string", "format": "email", "example": "recipient@example.com" }, { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "recipient1@example.com", "recipient2@example.com" ], "maxItems": 1000 } ] }, "from": { "description": "Sender email address. Must belong to the authenticated domain. Defaults to noreply@{domain} if not provided.", "type": "string", "format": "email", "example": "sender@example.com" }, "from_name": { "description": "Optional sender display name. If not provided, will use the email address only.", "type": "string", "example": "Company Name" }, "variables": { "description": "Variables for template replacement using {{variable}} syntax. Can be single object for all recipients or array matching recipient count", "oneOf": [ { "description": "Single set of variables for all recipients", "type": "object", "example": { "name": "John Doe", "product": "Premium Widget" } }, { "description": "Array of variable objects, one per recipient", "type": "array", "items": { "type": "object" }, "example": [ { "name": "John", "product": "Widget A" }, { "name": "Jane", "product": "Widget B" } ] } ] }, "headers": { "description": "Optional custom email headers. Can be provided as an object or JSON string. Common use cases include tracking headers, priority settings, and unsubscribe links.", "oneOf": [ { "type": "object", "example": { "X-Campaign-ID": "welcome-series" } }, { "type": "string", "example": "{\"X-Campaign-ID\": \"welcome-series\"}" } ] }, "reply_to": { "description": "Reply-to email address. Must share the same top-level domain as the 'from' address for security compliance.", "type": "string", "format": "email", "example": "support@example.com" }, "attachments": { "description": "File attachment(s). Single file or array of files. Maximum 10 files per email, 20MB per file, 25MB total payload. Supports documents, images, and archives with optional processing.", "oneOf": [ { "description": "Single file attachment", "type": "string", "format": "binary" }, { "description": "Multiple file attachments", "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 10 } ] }, "attachment_options": { "description": "JSON string with attachment processing options. Watermark text is limited to 50 characters.", "type": "string", "example": "{\"compress\": true, \"password\": \"secret123\", \"watermark\": {\"enabled\": true, \"text\": \"CONFIDENTIAL\"}}" } }, "type": "object" } } } }, "responses": { "202": { "description": "Template-based email jobs dispatched", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Template-based email jobs dispatched for 2 recipients in 1 job(s)" }, "template_guid": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "template_name": { "type": "string", "example": "Welcome Email" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/TemplateMessageUnauthorized" }, "404": { "$ref": "#/components/responses/TemplateMessageNotFound" }, "422": { "$ref": "#/components/responses/TemplateMessageValidationError" }, "429": { "$ref": "#/components/responses/TemplateMessageTooManyRequests" }, "500": { "$ref": "#/components/responses/TemplateMessageServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/quota": { "get": { "tags": [ "User" ], "summary": "Get user quota information", "description": "Retrieve current quota information including current usage and maximum allowed quota for the authenticated user.", "operationId": "1ae375d10afea45d3bfbaa82249659d4", "responses": { "200": { "description": "Quota information retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Request status", "type": "boolean", "example": true }, "data": { "properties": { "current_quota": { "description": "Current available quota (aggregate + update)", "type": "integer", "example": 850 }, "max_quota": { "description": "Maximum allowed quota (aggregate limit)", "type": "integer", "example": 1000 }, "usage_percentage": { "description": "Percentage of quota used ((max - current) / max * 100)", "type": "number", "format": "float", "example": 15 } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/QuotaUnauthorized" }, "404": { "$ref": "#/components/responses/QuotaNotFound" }, "429": { "$ref": "#/components/responses/QuotaTooManyRequests" }, "500": { "$ref": "#/components/responses/QuotaServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/suppressions": { "get": { "tags": [ "Suppressions" ], "summary": "Get domain suppressions", "description": "Retrieve a paginated list of suppressions for a domain", "operationId": "85ae0df37a4ae27adc6339af5bd3ee2a", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "type", "in": "query", "description": "Suppression type", "required": false, "schema": { "type": "string", "default": "unsubscribe", "enum": [ "unsubscribe", "bounce", "whitelist" ] } }, { "name": "search", "in": "query", "description": "Search suppressions by recipient", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 10 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }, "pagination": { "type": "object" }, "filters": { "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/SuppressionUnauthorized" }, "404": { "$ref": "#/components/responses/SuppressionNotFound" }, "429": { "$ref": "#/components/responses/SuppressionTooManyRequests" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/suppressions/unsubscribes": { "get": { "tags": [ "Suppressions" ], "summary": "Get unsubscribe suppressions", "description": "Retrieve a paginated list of unsubscribe suppressions for a domain", "operationId": "f2d22ba28804c68ac1f6238541f52762", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "search", "in": "query", "description": "Search suppressions by recipient", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 10 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }, "pagination": { "type": "object" }, "filters": { "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/SuppressionUnauthorized" }, "404": { "$ref": "#/components/responses/SuppressionNotFound" }, "429": { "$ref": "#/components/responses/SuppressionTooManyRequests" } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Suppressions" ], "summary": "Delete unsubscribe suppressions", "description": "Remove unsubscribe suppressions by IDs", "operationId": "49b7e6666b9ca66e6f1844d25005107d", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids" ], "properties": { "ids": { "description": "Array of suppression IDs to delete", "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] } }, "type": "object" } } } }, "responses": { "204": { "description": "Suppressions deleted successfully", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } } }, "401": { "$ref": "#/components/responses/SuppressionUnauthorized" }, "422": { "$ref": "#/components/responses/SuppressionValidationError" }, "429": { "$ref": "#/components/responses/SuppressionTooManyRequests" }, "500": { "$ref": "#/components/responses/SuppressionServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/suppressions/bounces": { "get": { "tags": [ "Suppressions" ], "summary": "Get bounce suppressions", "description": "Retrieve a paginated list of bounce suppressions for a domain", "operationId": "1ded4797e7750999fa79f4ad5f829fb4", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "search", "in": "query", "description": "Search suppressions by recipient", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 10 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }, "pagination": { "type": "object" }, "filters": { "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/SuppressionUnauthorized" }, "404": { "$ref": "#/components/responses/SuppressionNotFound" }, "429": { "$ref": "#/components/responses/SuppressionTooManyRequests" } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Suppressions" ], "summary": "Delete bounce suppressions", "description": "Remove bounce suppressions by IDs", "operationId": "08b2dfbd22c111b2b458cad3047f1f26", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids" ], "properties": { "ids": { "description": "Array of suppression IDs to delete", "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] } }, "type": "object" } } } }, "responses": { "204": { "description": "Suppressions deleted successfully", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } } }, "401": { "$ref": "#/components/responses/SuppressionUnauthorized" }, "422": { "$ref": "#/components/responses/SuppressionValidationError" }, "429": { "$ref": "#/components/responses/SuppressionTooManyRequests" }, "500": { "$ref": "#/components/responses/SuppressionServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/suppressions/whitelist": { "get": { "tags": [ "Suppressions" ], "summary": "Get whitelist suppressions", "description": "Retrieve a paginated list of whitelist suppressions for a domain", "operationId": "16bc6d1494a017c7c36cb765c055f1d7", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "search", "in": "query", "description": "Search suppressions by recipient", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 10 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }, "pagination": { "type": "object" }, "filters": { "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/SuppressionUnauthorized" }, "404": { "$ref": "#/components/responses/SuppressionNotFound" }, "429": { "$ref": "#/components/responses/SuppressionTooManyRequests" } }, "security": [ { "basicAuth": [] } ] }, "post": { "tags": [ "Suppressions" ], "summary": "Create whitelist suppression", "description": "Add a new entry to whitelist suppressions", "operationId": "e4df9f589b60bb2606df8cacb73d5ba3", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "description": "Whitelist suppression entry details", "required": true, "content": { "application/json": { "schema": { "required": [ "recipient", "recipient_type" ], "properties": { "recipient": { "description": "Email or domain to whitelist", "type": "string", "example": "user@example.com" }, "recipient_type": { "description": "Type of recipient", "type": "string", "example": "email", "enum": [ "email", "domain" ] }, "description": { "description": "Optional description", "type": "string", "example": "Trusted sender" } }, "type": "object" } }, "multipart/form-data": { "schema": { "required": [ "recipient", "recipient_type" ], "properties": { "recipient": { "description": "Email or domain to whitelist", "type": "string", "example": "user@example.com" }, "recipient_type": { "description": "Type of recipient", "type": "string", "example": "email", "enum": [ "email", "domain" ] }, "description": { "description": "Optional description", "type": "string", "example": "Trusted sender" } }, "type": "object" } } } }, "responses": { "201": { "description": "Whitelist entry created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Whitelist entry created successfully." }, "data": { "$ref": "#/components/schemas/Suppression" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/SuppressionUnauthorized" }, "404": { "$ref": "#/components/responses/SuppressionNotFound" }, "422": { "$ref": "#/components/responses/SuppressionValidationError" }, "429": { "$ref": "#/components/responses/SuppressionTooManyRequests" }, "500": { "$ref": "#/components/responses/SuppressionServerError" } }, "security": [ { "basicAuth": [] } ] }, "delete": { "tags": [ "Suppressions" ], "summary": "Delete whitelist suppressions", "description": "Remove whitelist suppressions by IDs", "operationId": "2f0dde9c3a47ae8c18fe9b583e9e7120", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids" ], "properties": { "ids": { "description": "Array of suppression IDs to delete", "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] } }, "type": "object" } } } }, "responses": { "204": { "description": "Suppressions deleted successfully", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } } }, "401": { "$ref": "#/components/responses/SuppressionUnauthorized" }, "422": { "$ref": "#/components/responses/SuppressionValidationError" }, "429": { "$ref": "#/components/responses/SuppressionTooManyRequests" }, "500": { "$ref": "#/components/responses/SuppressionServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/domains/{domain}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhooks for a domain", "description": "Retrieve a list of webhook configurations for the specified domain owned by the authenticated user", "operationId": "7525b40b9b578e378fe19b6592d00394", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "type", "in": "query", "description": "Filter webhooks by event type", "required": false, "schema": { "type": "string", "example": "delivered", "enum": [ "queued", "send", "delivered", "bounced", "failed", "permanent_fail", "opened", "clicked", "unsubscribed", "temporary_fail", "deferred" ] } } ], "responses": { "200": { "description": "Successfully retrieved webhook list for the domain", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates the request was successful", "type": "boolean", "example": true }, "data": { "description": "Array of webhook configurations", "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "count": { "description": "Number of webhooks returned", "type": "integer", "example": 5 } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "429": { "$ref": "#/components/responses/WebhookTooManyRequests" }, "500": { "$ref": "#/components/responses/WebhookServerError" } }, "security": [ { "userAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create a new webhook", "description": "Create a new webhook configuration for the specified domain owned by the authenticated user", "operationId": "8d582c9655e819451b3774f989149afa", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "description": "Webhook configuration details", "required": true, "content": { "application/json": { "schema": { "required": [ "type", "url" ], "properties": { "type": { "description": "Event type that will trigger this webhook", "type": "string", "example": "delivered", "enum": [ "queued", "send", "delivered", "bounced", "failed", "permanent_fail", "opened", "clicked", "unsubscribed", "temporary_fail", "deferred" ] }, "url": { "description": "URL endpoint where webhook events will be sent (must use HTTP or HTTPS)", "type": "string", "format": "uri", "example": "https://example.com/webhook" } }, "type": "object" } } } }, "responses": { "201": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates the request was successful", "type": "boolean", "example": true }, "message": { "description": "Human-readable success message", "type": "string", "example": "Webhook created successfully." }, "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "429": { "$ref": "#/components/responses/WebhookTooManyRequests" }, "500": { "$ref": "#/components/responses/WebhookServerError" } }, "security": [ { "userAuth": [] } ] } }, "/api/domains/{domain}/webhooks/{webhookGuid}": { "get": { "tags": [ "Webhooks" ], "summary": "Get a specific webhook", "description": "Retrieve details of a specific webhook configuration owned by the authenticated user", "operationId": "c3ea986c0de465b81cad6f745cd6aeba", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "webhookGuid", "in": "path", "description": "Unique identifier (GUID) of the webhook", "required": true, "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Successfully retrieved webhook details", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates the request was successful", "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "429": { "$ref": "#/components/responses/WebhookTooManyRequests" }, "500": { "$ref": "#/components/responses/WebhookServerError" } }, "security": [ { "userAuth": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Update an existing webhook configuration for the specified domain owned by the authenticated user", "operationId": "009c187453dc299fa3b9a6b8711478a3", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "webhookGuid", "in": "path", "description": "Unique identifier (GUID) of the webhook to update", "required": true, "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "requestBody": { "description": "Webhook configuration updates (at least one field must be provided)", "required": false, "content": { "application/json": { "schema": { "properties": { "type": { "description": "New event type that will trigger this webhook", "type": "string", "example": "opened", "enum": [ "queued", "send", "delivered", "bounced", "failed", "permanent_fail", "opened", "clicked", "unsubscribed", "temporary_fail", "deferred" ] }, "url": { "description": "New URL endpoint where webhook events will be sent (must use HTTP or HTTPS)", "type": "string", "format": "uri", "example": "https://example.com/new-webhook" } }, "type": "object" } } } }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates the request was successful", "type": "boolean", "example": true }, "message": { "description": "Human-readable success message", "type": "string", "example": "Webhook updated successfully." }, "data": { "$ref": "#/components/schemas/Webhook" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "429": { "$ref": "#/components/responses/WebhookTooManyRequests" }, "500": { "$ref": "#/components/responses/WebhookServerError" } }, "security": [ { "userAuth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Remove a webhook configuration from the specified domain owned by the authenticated user", "operationId": "77298a7609c9e52c627e28768abbc2e4", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user", "required": true, "schema": { "type": "string", "example": "example.com" } }, { "name": "webhookGuid", "in": "path", "description": "Unique identifier (GUID) of the webhook to delete", "required": true, "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "204": { "description": "Webhook deleted successfully", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "429": { "$ref": "#/components/responses/WebhookTooManyRequests" }, "500": { "$ref": "#/components/responses/WebhookServerError" } }, "security": [ { "userAuth": [] } ] } }, "/api/domains/{domain}/webhooks/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test a webhook URL", "description": "Send a test webhook event to the specified URL to verify it can receive webhook notifications", "operationId": "a47c3827107de9d85fe2eef7e1a5a966", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name that must be owned by the authenticated user", "required": true, "schema": { "type": "string", "example": "example.com" } } ], "requestBody": { "description": "Test webhook parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "url", "event_type" ], "properties": { "url": { "description": "URL endpoint to test", "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "event_type": { "description": "Event type to use for the test", "type": "string", "example": "delivered", "enum": [ "queued", "send", "delivered", "bounced", "failed", "permanent_fail", "opened", "clicked", "unsubscribed", "temporary_fail", "deferred" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Webhook test completed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates the webhook test was successful", "type": "boolean", "example": true }, "message": { "description": "Human-readable result message", "type": "string", "example": "Webhook test completed successfully" }, "data": { "description": "Test result details", "properties": { "url": { "description": "The tested webhook URL", "type": "string", "example": "https://example.com/webhook" }, "event_type": { "description": "The event type used for testing", "type": "string", "example": "delivered" }, "response_status": { "description": "HTTP status code received from webhook URL", "type": "integer", "example": 200 }, "response_time": { "description": "Response time in milliseconds", "type": "integer", "example": 150 } }, "type": "object" } }, "type": "object" } } } }, "424": { "description": "Webhook test failed - URL did not respond correctly", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates the webhook test failed", "type": "boolean", "example": false }, "message": { "description": "Human-readable error message", "type": "string", "example": "Webhook URL did not respond correctly" }, "data": { "description": "Test result details", "properties": { "url": { "description": "The tested webhook URL", "type": "string", "example": "https://example.com/webhook" }, "event_type": { "description": "The event type used for testing", "type": "string", "example": "delivered" }, "response_status": { "description": "HTTP status code received from webhook URL", "type": "integer", "example": 404 }, "response_time": { "description": "Response time in milliseconds", "type": "integer", "example": 0 } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#/components/responses/WebhookUnauthorized" }, "404": { "$ref": "#/components/responses/WebhookNotFound" }, "422": { "$ref": "#/components/responses/WebhookValidationError" }, "429": { "$ref": "#/components/responses/WebhookTooManyRequests" }, "500": { "$ref": "#/components/responses/WebhookServerError" } }, "security": [ { "userAuth": [] } ] } } }, "components": { "schemas": { "Credential": { "description": "SMTP credential object containing authentication details for email sending", "properties": { "id": { "description": "Database auto-increment ID (internal use only)", "type": "integer", "example": 1 }, "user_smtp_guid": { "description": "Unique credential GUID used for API operations", "type": "string", "example": "92703823-f3a4-48e2-8e87-7adf25454800" }, "username": { "description": "SMTP username for authentication. Must be unique within the domain", "type": "string", "example": "myuser" }, "created_at": { "description": "Unix timestamp when the credential was created", "type": "integer", "example": 1640995200 }, "modified_at": { "description": "Unix timestamp when the credential was last modified", "type": "integer", "example": 1640995200 } }, "type": "object" }, "Domain": { "description": "Domain object containing email domain configuration and verification status", "properties": { "id": { "description": "Unique identifier for the domain", "type": "integer", "example": 1 }, "domain": { "description": "Domain name used for sending emails", "type": "string", "example": "example.com" }, "tracklink_domain": { "description": "Custom tracking domain for click and open tracking", "type": "string", "example": "" }, "tracklink_domain_is_verified": { "description": "Whether the tracking domain has been verified", "type": "boolean", "example": false }, "auth_domain_is_verified": { "description": "Whether the authentication domain has been verified", "type": "boolean", "example": false }, "dns_selector": { "description": "DKIM selector used for DNS verification", "type": "string", "example": "k1" }, "dns_record": { "description": "DKIM public key record that should be configured in DNS", "type": "string", "example": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDjF2J8K5xqH7N8Z9L2zQ3bX9Y1tW7vU6kR5aP4sT8nB3mV7cZ2jX5L8oR9pN3tQ1wE4vY6bF2aC8hI7gD5eJ9kL3mX8oQ6bH2nV5pZ9cR8tW7yB4mX6qN5zL3oV8cF2tH9nB5pQ7eZ1mX8sT6kR4vY9bH3mC8qI7gL5nX2oW9zF5pD8eB7hR3mX6yV9cQ2tK4nB5pL1mX8sT6kR9vY9bH3mC8qI7gL5nX2oW9zF5pD8eB7hR3mX6yV9cQ2tK4nB5pL1mX8sT6kR9vY9bH3mC8qI7gL5nX2oW9zF5pD8eB7hR3mX6yV9cQIDAQAB" }, "click_track": { "description": "Whether click tracking is enabled for emails sent from this domain", "type": "boolean", "example": false }, "open_track": { "description": "Whether open tracking is enabled for emails sent from this domain", "type": "boolean", "example": false }, "unsub_track": { "description": "Whether unsubscribe tracking is enabled for emails sent from this domain", "type": "boolean", "example": false }, "is_verified": { "description": "Whether the domain has been verified for email sending", "type": "boolean", "example": false }, "status": { "description": "Domain status (active/inactive)", "type": "boolean", "example": true }, "created_at": { "description": "Unix timestamp when the domain was created", "type": "integer", "example": 1762810896 }, "modified_at": { "description": "Unix timestamp when the domain was last modified", "type": "integer", "example": 1762810896 }, "spf_record": { "description": "Expected SPF record value that should be configured in DNS", "type": "string", "example": "v=spf1 mx include:spf.kirim.email ~all" } }, "type": "object" }, "Pagination": { "description": "Pagination metadata for paginated API responses", "properties": { "total": { "description": "Total number of items available across all pages", "type": "integer", "example": 50 }, "page": { "description": "Current page number (1-based)", "type": "integer", "example": 1 }, "limit": { "description": "Maximum number of items per page", "type": "integer", "example": 10 }, "offset": { "description": "Number of items skipped from the beginning (0-based)", "type": "integer", "example": 0 } }, "type": "object" }, "EmailValidationResult": { "description": "Email validation result with comprehensive checks", "properties": { "email": { "description": "The validated email address", "type": "string", "example": "user@example.com" }, "is_valid": { "description": "Whether the email passed all validation checks", "type": "boolean", "example": true }, "error": { "description": "Error message if validation failed", "type": "string", "example": null, "nullable": true }, "warnings": { "description": "Array of validation warnings", "type": "array", "items": { "type": "string" }, "example": [] }, "cached": { "description": "Whether result was served from cache", "type": "boolean", "example": false }, "validated_at": { "description": "ISO timestamp of validation", "type": "string", "example": "2024-01-01T12:00:00Z" }, "is_spamtrap": { "description": "Whether email is identified as likely spamtrap", "type": "boolean", "example": false }, "spamtrap_score": { "description": "Spamtrap probability score (0.0-1.0)", "type": "number", "format": "float", "example": 0.1, "maximum": 1, "minimum": 0 } }, "type": "object" }, "EmailValidationBatchResult": { "description": "Batch email validation results with summary", "properties": { "results": { "description": "Array of individual validation results", "type": "array", "items": { "$ref": "#/components/schemas/EmailValidationResult" } }, "summary": { "properties": { "total": { "description": "Total number of emails validated", "type": "integer", "example": 10 }, "valid": { "description": "Number of valid emails", "type": "integer", "example": 7 }, "invalid": { "description": "Number of invalid emails", "type": "integer", "example": 3 }, "cached": { "description": "Number of results served from cache", "type": "integer", "example": 4 }, "validated": { "description": "Number of emails freshly validated", "type": "integer", "example": 6 } }, "type": "object" } }, "type": "object" }, "LogEntry": { "description": "Email log entry", "properties": { "id": { "description": "Unique identifier for the log entry", "type": "string", "example": "log-id-123" }, "user_guid": { "description": "GUID of the user who sent the email", "type": "string", "example": "user-guid-123" }, "user_domain_guid": { "description": "GUID of the domain used to send the email", "type": "string", "example": "domain-guid-456" }, "event_type": { "description": "Type of email event (sent, delivered, bounced, opened, clicked, etc.)", "type": "string", "example": "delivered" }, "message_guid": { "description": "Unique identifier for the email message", "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "timestamp": { "description": "Unix timestamp when the event occurred", "type": "integer", "example": 1640995200 } }, "type": "object" }, "Suppression": { "description": "Suppression entry", "properties": { "id": { "type": "integer", "example": 1 }, "type": { "type": "string", "example": "unsubscribe", "enum": [ "unsubscribe", "bounce", "whitelist" ] }, "recipient_type": { "type": "string", "example": "email", "enum": [ "email", "domain" ] }, "recipient": { "type": "string", "example": "user@example.com" }, "tags": { "type": "string", "example": "marketing", "nullable": true }, "description": { "type": "string", "example": "Opted out from newsletter", "nullable": true }, "source": { "type": "string", "example": "api", "nullable": true }, "created_at": { "type": "integer", "example": 1711234567 } }, "type": "object" }, "Webhook": { "description": "Webhook configuration for email event notifications", "properties": { "webhook_guid": { "description": "Unique identifier for the webhook", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "user_guid": { "description": "GUID of the user who owns the webhook", "type": "string", "example": "user-guid-123" }, "user_domain_guid": { "description": "GUID of the domain associated with the webhook", "type": "string", "example": "domain-guid-456" }, "user_smtp_guid": { "description": "GUID of the SMTP configuration", "type": "string", "example": "smtp-guid-789" }, "type": { "description": "Event type that triggers the webhook", "type": "string", "example": "delivered", "enum": [ "queued", "send", "delivered", "bounced", "failed", "permanent_fail", "opened", "clicked", "unsubscribed", "temporary_fail", "deferred" ] }, "url": { "description": "URL endpoint where webhook events will be sent", "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "is_deleted": { "description": "Whether the webhook has been deleted", "type": "boolean", "example": false }, "created_at": { "description": "Unix timestamp when the webhook was created", "type": "integer", "example": 1640995200 }, "modified_at": { "description": "Unix timestamp when the webhook was last modified", "type": "integer", "example": 1640995200 } }, "type": "object" } }, "responses": { "CredentialUnauthorized": { "description": "Unauthorized - Invalid or missing authentication credentials", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "CredentialForbidden": { "description": "Forbidden - Credential does not belong to the specified domain", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Credential does not belong to the specified domain" } }, "type": "object" } } } }, "CredentialNotFound": { "description": "Credential not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Credential not found" } }, "type": "object" } } } }, "CredentialValidationError": { "description": "Validation Error - Invalid input data", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed." }, "errors": { "description": "Field-specific validation errors", "type": "object" } }, "type": "object" } } } }, "CredentialServerError": { "description": "Server Error - Unexpected error occurred", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } }, "CredentialTooManyRequests": { "description": "Too Many Requests - Rate limit exceeded. Retry after the specified time.", "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many attempts. Please try again later." } }, "type": "object" } } } }, "DomainUnauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error type indicating authentication failure", "type": "string", "example": "Unauthorized" }, "message": { "description": "Human-readable error message explaining the authentication issue", "type": "string", "example": "Authorization header is required" } }, "type": "object" } } } }, "DomainNotFound": { "description": "Domain not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Domain not found" } }, "type": "object" } } } }, "DomainValidationError": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates the request failed due to validation errors", "type": "boolean", "example": false }, "message": { "description": "Human-readable error message", "type": "string", "example": "Validation failed." }, "errors": { "description": "Field-specific validation error messages organized by field name", "type": "object" } }, "type": "object" } } } }, "DomainServerError": { "description": "Server Error", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Indicates the request failed due to a server error", "type": "boolean", "example": false }, "message": { "description": "Human-readable error message describing the server error", "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } }, "DomainDnsLookupTemporaryFailure": { "description": "DNS lookup temporarily failed - the DNS server did not respond. Retry after a few minutes.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "We couldn't check the DNS records for the domain right now because the DNS server is temporarily unavailable. This usually resolves on its own - please wait a few minutes and try again. If the problem persists, please contact support." }, "error": { "type": "string", "example": "dns_lookup_temporary_failure" } }, "type": "object" } } } }, "DomainTooManyRequests": { "description": "Too Many Requests - Rate limit exceeded. Retry after the specified time.", "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many attempts. Please try again later." } }, "type": "object" } } } }, "DomainConflict": { "description": "Conflict - Domain already exists", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "This domain is already registered in our system. Please use a different domain." }, "errors": { "description": "Field-specific validation errors", "properties": { "domain": { "type": "array", "items": { "type": "string" }, "example": [ "This domain is already registered in our system. Please use a different domain." ] } }, "type": "object" } }, "type": "object" } } } }, "EmailValidationBadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object" } }, "type": "object" } } } }, "EmailValidationUnauthorized": { "description": "Unauthorized - Invalid or missing authentication", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "EmailValidationTooManyRequests": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests per hour", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Rate limit exceeded. Please try again later." }, "retry_after": { "description": "Seconds until rate limit resets", "type": "integer", "example": 3600 } }, "type": "object" } } } }, "EmailValidationServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal server error occurred during email validation" } }, "type": "object" } } } }, "LogBadRequest": { "description": "Bad Request - User authentication missing", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User authentication missing" } }, "type": "object" } } } }, "LogUnauthorized": { "description": "Unauthorized - Invalid or missing authentication", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "LogNotFound": { "description": "Not Found - Domain or log not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Domain not found or you do not own this domain" } }, "type": "object" } } } }, "LogServerError": { "description": "Server Error - Unexpected error occurred", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unknown error" } }, "type": "object" } } } }, "LogTooManyRequests": { "description": "Too Many Requests - Rate limit exceeded. Retry after the specified time.", "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many attempts. Please try again later." } }, "type": "object" } } } }, "MessageBadRequest": { "description": "Bad Request - Missing authentication or invalid request structure", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User authentication missing" } }, "type": "object" } } } }, "MessageUnauthorized": { "description": "Unauthorized - Invalid user credentials or session expired", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Authentication required" } }, "type": "object" } } } }, "MessageNotFound": { "description": "Domain not found or user does not own the specified domain", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Domain not found or you do not own this domain." } }, "type": "object" } } } }, "MessageValidationError": { "description": "Validation Error - Invalid input data, business rule violations, or configuration issues", "content": { "application/json": { "schema": { "properties": { "": { "oneOf": [ { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed." }, "errors": { "type": "object" } }, "type": "object" }, { "properties": { "error": { "type": "string", "example": "Total email payload exceeds maximum size" } }, "type": "object" } ] } }, "type": "object" } } } }, "MessageServerError": { "description": "Internal Server Error - Unexpected system error during processing", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while sending the message. Please try again." } }, "type": "object" } } } }, "MessageTooManyRequests": { "description": "Too Many Requests - Rate limit exceeded. Retry after the specified time.", "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many attempts. Please try again later." } }, "type": "object" } } } }, "TemplateMessageBadRequest": { "description": "Bad Request - User authentication missing or invalid request", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User authentication missing" } }, "type": "object" } } } }, "TemplateMessageUnauthorized": { "description": "Unauthorized - Invalid or missing authentication credentials", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "TemplateMessageNotFound": { "description": "Not Found - Domain or template not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Domain not found or you do not own this domain." } }, "type": "object" } } } }, "TemplateMessageValidationError": { "description": "Validation Error - Invalid input data", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed." }, "errors": { "description": "Field-specific validation errors", "type": "object" } }, "type": "object" } } } }, "TemplateMessageServerError": { "description": "Server Error - Unexpected error occurred", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while sending the template message. Please try again." } }, "type": "object" } } } }, "TemplateMessageTooManyRequests": { "description": "Too Many Requests - Rate limit exceeded. Retry after the specified time.", "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many attempts. Please try again later." } }, "type": "object" } } } }, "QuotaUnauthorized": { "description": "Unauthorized - Invalid or missing API credentials", "content": { "application/json": { "schema": { "properties": { "success": { "description": "Public API Controller for Quota Management\n\nHandles public-facing quota-related API requests.", "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized - User not authenticated" } }, "type": "object" } } } }, "QuotaNotFound": { "description": "User not found or has no quota configured", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "User quota not found" } }, "type": "object" } } } }, "QuotaTooManyRequests": { "description": "Too many requests - Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many requests" } }, "type": "object" } } } }, "QuotaServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Internal server error" } }, "type": "object" } } } }, "SuppressionUnauthorized": { "description": "Unauthorized - Invalid or missing authentication credentials", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "SuppressionNotFound": { "description": "Not Found - Domain not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Domain not found" } }, "type": "object" } } } }, "SuppressionValidationError": { "description": "Validation Error - Invalid input data", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed." }, "errors": { "description": "Field-specific validation errors", "type": "object" } }, "type": "object" } } } }, "SuppressionServerError": { "description": "Server Error - Unexpected error occurred", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } }, "SuppressionTooManyRequests": { "description": "Too Many Requests - Rate limit exceeded. Retry after the specified time.", "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many attempts. Please try again later." } }, "type": "object" } } } }, "WebhookBadRequest": { "description": "Bad Request - User authentication missing", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User authentication missing" } }, "type": "object" } } } }, "WebhookUnauthorized": { "description": "Unauthorized - Invalid or missing authentication credentials", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "WebhookNotFound": { "description": "Not Found - Domain or webhook not found", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Domain not found or you do not own this domain" } }, "type": "object" } } } }, "WebhookValidationError": { "description": "Validation Error - Invalid input data", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed." }, "errors": { "description": "Field-specific validation errors", "type": "object" } }, "type": "object" } } } }, "WebhookServerError": { "description": "Server Error - Unexpected error occurred", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "An error occurred while processing the request." } }, "type": "object" } } } }, "WebhookTooManyRequests": { "description": "Too Many Requests - Rate limit exceeded. Retry after the specified time.", "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Too many attempts. Please try again later." } }, "type": "object" } } } } }, "securitySchemes": { "basicAuth": { "type": "http", "description": "Basic Authentication using username and token from User model", "scheme": "basic" } } }, "tags": [ { "name": "Domains", "description": "Domain management endpoints" }, { "name": "Credentials", "description": "SMTP credential management endpoints" }, { "name": "Suppressions", "description": "Email suppression management endpoints" }, { "name": "Message", "description": "Email sending endpoints" }, { "name": "Logs", "description": "Email logs endpoints" }, { "name": "Email Validation", "description": "Email Validation" }, { "name": "User", "description": "User" }, { "name": "Webhooks", "description": "Webhooks" } ] }