{ "components": { "securitySchemes": { "apiKeyAuth": { "description": "API key authentication", "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "description": "Public REST API for Benchmark Email.\n\nAuthenticate every request by including your API key in the `X-API-Key` header.\nEach key is issued with one or more scopes that control which endpoints it may call.\n\nRate limits: 60 requests per minute per account.\nMonthly quota: determined by your subscription plan.", "title": "Benchmark Email API", "version": "1.0.0" }, "openapi": "3.0.0", "paths": { "/api/contact": { "get": { "operationId": "get_api_contact", "responses": { "200": { "description": "Successful" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get all contacts", "tags": [ "contact" ], "x-api-key-scope": "contacts:read" }, "post": { "operationId": "post_api_contact", "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "description": "Successfully created" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Create a new contact", "tags": [ "contact" ], "x-api-key-scope": "contacts:write" } }, "/api/contact-structure": { "get": { "operationId": "get_api_contact_structure", "responses": { "200": { "description": "Successful" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get all contact structures", "tags": [ "contact-structure" ], "x-api-key-scope": "contacts:read" }, "post": { "operationId": "post_api_contact_structure", "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "description": "Successfully created" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Create a new contact structure", "tags": [ "contact-structure" ], "x-api-key-scope": "contacts:write" } }, "/api/contact-structure/{contactStructureId}": { "get": { "operationId": "get_api_contact_structure_by_contactStructureId", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get a contact structure by id", "tags": [ "contact-structure" ], "x-api-key-scope": "contacts:read" }, "put": { "operationId": "put_api_contact_structure_by_contactStructureId", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "description": "Successfully updated" }, "400": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "List of application errors", "items": { "properties": { "debug": { "properties": { "affectedForms": { "description": "Forms that reference the contact field(s) being removed", "items": { "properties": { "_id": { "description": "Form ID", "type": "string" }, "name": { "description": "Form name", "type": "string" } }, "required": [ "_id", "name" ], "type": "object" }, "type": "array" } }, "required": [ "affectedForms" ], "type": "object" }, "errorType": { "description": "Error code (e.g. ContactFieldInUseError, ValidationError)", "type": "string" }, "field": { "description": "Field path when applicable", "type": "string" }, "fieldId": { "description": "Field identifier when applicable", "type": "string" }, "message": { "description": "Human-readable error message", "type": "string" } }, "required": [ "message", "errorType", "debug" ], "type": "object" }, "type": "array" } }, "required": [ "errors" ], "type": "object" } } }, "description": "Contact field(s) cannot be removed because they are used by one or more forms (ContactFieldInUseError). Response body includes errors[].debug.affectedForms (array of { _id, name }) for UI display. Update or unpublish the affected forms first." } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Update a contact structure by id", "tags": [ "contact-structure" ], "x-api-key-scope": "contacts:write" } }, "/api/contact-structure/{contactStructureId}/lists": { "delete": { "operationId": "delete_api_contact_structure_by_contactStructureId_lists", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "format": "mongo-id", "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "204": { "description": "Successfully deleted" }, "400": { "description": "Invalid request" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Delete multiple lists", "tags": [ "lists" ], "x-api-key-scope": "contacts:write" }, "get": { "operationId": "get_api_contact_structure_by_contactStructureId_lists", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "format": "mongo-id", "type": "string" } }, { "description": "page number", "in": "query", "name": "page", "schema": { "minimum": 1, "type": "integer" } }, { "description": "page size", "in": "query", "name": "size", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Sorting parameter with the format 'field:direction'. Supported fields: name, createdAt, updatedAt.", "examples": { "ascSort": { "summary": "ascending sort by name", "value": "name:asc" }, "descSort": { "summary": "descending sort by createdAt", "value": "createdAt:desc" } }, "in": "query", "name": "sort", "required": false, "schema": { "pattern": "^[a-zA-Z0-9_]+:(asc|desc)$", "type": "string" } }, { "description": "A string used to filter the search results. The maximum length is 50 characters.", "in": "query", "name": "criteria", "schema": { "maxLength": 50, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "__v": { "type": "number" }, "_id": { "type": "string" }, "createdAt": { "type": "string" }, "name": { "type": "string" }, "totalCampaigns": { "type": "number" }, "totalContacts": { "type": "number" }, "type": { "type": "string" }, "updatedAt": { "type": "string" } }, "type": "object" }, "type": "array" } } }, "description": "Successful" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get paginated lists", "tags": [ "lists" ], "x-api-key-scope": "contacts:read" }, "post": { "operationId": "post_api_contact_structure_by_contactStructureId_lists", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "format": "mongo-id", "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "__v": { "type": "number" }, "_id": { "type": "string" }, "createdAt": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "updatedAt": { "type": "string" } }, "type": "object" } } }, "description": "Successfully created" }, "400": { "description": "Invalid request" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Create a new list", "tags": [ "lists" ], "x-api-key-scope": "contacts:write" } }, "/api/contact-structure/{contactStructureId}/lists/all": { "get": { "operationId": "get_api_contact_structure_by_contactStructureId_lists_all", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "format": "mongo-id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" } } }, "description": "Successful" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get all lists", "tags": [ "lists" ], "x-api-key-scope": "contacts:read" } }, "/api/contact-structure/{contactStructureId}/lists/merge": { "post": { "operationId": "post_api_contact_structure_by_contactStructureId_lists_merge", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "format": "mongo-id", "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "__v": { "type": "number" }, "_id": { "type": "string" }, "createdAt": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "updatedAt": { "type": "string" } }, "type": "object" } } }, "description": "Successfully merged lists" }, "400": { "description": "Invalid request" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Merge lists into a new list.", "tags": [ "lists" ], "x-api-key-scope": "contacts:write" } }, "/api/contact-structure/{contactStructureId}/lists/{listId}": { "delete": { "operationId": "delete_api_contact_structure_by_contactStructureId_lists_by_listId", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "format": "mongo-id", "type": "string" } }, { "in": "path", "name": "listId", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Successfully deleted" }, "400": { "description": "Invalid request" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Delete a list by id", "tags": [ "lists" ], "x-api-key-scope": "contacts:write" }, "get": { "operationId": "get_api_contact_structure_by_contactStructureId_lists_by_listId", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "format": "mongo-id", "type": "string" } }, { "in": "path", "name": "listId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "__v": { "type": "number" }, "_id": { "type": "string" }, "createdAt": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "updatedAt": { "type": "string" } }, "type": "object" } } }, "description": "Successful" }, "400": { "description": "Invalid request" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get a list by id", "tags": [ "lists" ], "x-api-key-scope": "contacts:read" }, "patch": { "operationId": "patch_api_contact_structure_by_contactStructureId_lists_by_listId", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "format": "mongo-id", "type": "string" } }, { "in": "path", "name": "listId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "__v": { "type": "number" }, "_id": { "type": "string" }, "createdAt": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "updatedAt": { "type": "string" } }, "type": "object" } } }, "description": "Successfully updated" }, "400": { "description": "Invalid request" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Update a list by id", "tags": [ "lists" ], "x-api-key-scope": "contacts:write" } }, "/api/contact-structure/{contactStructureId}/lists/{listId}/duplicate": { "post": { "operationId": "post_api_contact_structure_by_contactStructureId_lists_by_listId_duplicate", "parameters": [ { "in": "path", "name": "contactStructureId", "required": true, "schema": { "format": "mongo-id", "type": "string" } }, { "in": "path", "name": "listId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "__v": { "type": "number" }, "_id": { "type": "string" }, "createdAt": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "updatedAt": { "type": "string" } }, "type": "object" } } }, "description": "Successfully duplicated" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Duplicate a list", "tags": [ "lists" ], "x-api-key-scope": "contacts:write" } }, "/api/contact/events": { "get": { "description": "Get all contact events for the account", "operationId": "get_api_contact_events", "parameters": [ { "description": "Filter events by type", "example": [ "contact-created", "contact-updated" ], "explode": false, "in": "query", "name": "types", "schema": { "items": { "enum": [ "contact-created", "contact-updated", "contact-update-failed", "contact-unsubscribed", "contact-reactivated", "email-sent", "email-bounced", "email-delivered", "email-delayed", "email-rejected", "email-complaint", "email-opened", "email-clicked", "email-skipped" ], "type": "string" }, "type": "array" } }, { "description": "Filter events from the last N days (1-90). Defaults to 30 when omitted", "example": 30, "in": "query", "name": "pastDays", "required": false, "schema": { "default": 30, "maximum": 90, "minimum": 1, "type": "integer" } }, { "description": "page number", "in": "query", "name": "page", "schema": { "minimum": 1, "type": "integer" } }, { "description": "page size", "in": "query", "name": "size", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "records": { "items": { "properties": { "contactId": { "type": "string" }, "emailBounceDiagCode": { "type": "string" }, "emailBounceSubType": { "type": "string" }, "emailBounceType": { "type": "string" }, "emailCampaignId": { "type": "string" }, "emailCampaignName": { "type": "string" }, "emailComplaintFeedbackType": { "type": "string" }, "emailDelayType": { "type": "string" }, "emailLinkId": { "type": "string" }, "emailRejectReason": { "type": "string" }, "emailSender": { "type": "string" }, "emailSenderName": { "type": "string" }, "emailSmtpResponse": { "type": "string" }, "emailSubject": { "type": "string" }, "emailTargetUrl": { "type": "string" }, "emailTo": { "type": "string" }, "importId": { "type": "string" }, "importOriginalFileName": { "type": "string" }, "source": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "triggeredBy": { "description": "Present on contact-created/contact-updated events when a triggering user is recorded. The type and userId fields come from the event index.", "properties": { "type": { "description": "The type of actor that triggered the event (e.g. 'user', 'admin')", "type": "string" }, "userId": { "description": "The ID of the user who triggered the event", "type": "string" } }, "type": "object" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "total": { "type": "integer" } }, "type": "object" } } }, "description": "Contact events for the account" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get account contact events", "tags": [ "contact" ], "x-api-key-scope": "contacts:read" } }, "/api/contact/export": { "post": { "operationId": "post_api_contact_export", "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "content": { "text/csv": {} }, "description": "Successful" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Export contacts", "tags": [ "contact" ], "x-api-key-scope": "contacts:read" } }, "/api/contact/search": { "post": { "operationId": "post_api_contact_search", "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "contacts": { "items": { "properties": { "_id": { "description": "Id of the contact", "type": "string" }, "contactStructureId": { "description": "Id of the contact structure", "type": "string" }, "createdAt": { "description": "Date of creation", "type": "string" }, "fields": { "items": { "properties": { "_id": { "description": "Id of the field", "type": "string" }, "value": { "description": "Value of the field", "type": "string" } }, "type": "object" }, "type": "array" }, "key": { "description": "Primary key of the contact", "type": "string" }, "tags": { "items": { "properties": { "_id": { "description": "Id of the tag", "type": "string" } }, "type": "object" }, "type": "array" }, "updatedAt": { "description": "Date of update", "type": "string" } }, "type": "object" }, "type": "array" }, "totalRecords": { "description": "Total number of records", "type": "number" } }, "type": "object" } } }, "description": "Successful" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Search for contacts", "tags": [ "contact" ], "x-api-key-scope": "contacts:read" } }, "/api/contact/{contactId}": { "delete": { "operationId": "delete_api_contact_by_contactId", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully deleted" }, "404": { "description": "Contact not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Delete a contact by id", "tags": [ "contact" ], "x-api-key-scope": "contacts:write" }, "get": { "operationId": "get_api_contact_by_contactId", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully created" }, "404": { "description": "Contact not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get a contact by id", "tags": [ "contact" ], "x-api-key-scope": "contacts:read" }, "patch": { "operationId": "patch_api_contact_by_contactId", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "description": "Successfully updated" }, "404": { "description": "Contact not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Partial update a contact by id", "tags": [ "contact" ], "x-api-key-scope": "contacts:write" }, "put": { "operationId": "put_api_contact_by_contactId", "parameters": [ { "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "description": "Successfully updated" }, "404": { "description": "Contact not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Update a contact by id", "tags": [ "contact" ], "x-api-key-scope": "contacts:write" } }, "/api/contact/{contactId}/events": { "get": { "description": "Get events for a contact", "operationId": "get_api_contact_by_contactId_events", "parameters": [ { "description": "The contact id", "in": "path", "name": "contactId", "required": true, "schema": { "type": "string" } }, { "description": "Filter events by type", "example": [ "contact-created", "contact-updated" ], "explode": false, "in": "query", "name": "types", "schema": { "items": { "enum": [ "contact-created", "contact-updated", "contact-update-failed", "contact-unsubscribed", "contact-reactivated", "email-sent", "email-bounced", "email-delivered", "email-delayed", "email-rejected", "email-complaint", "email-opened", "email-clicked", "email-skipped" ], "type": "string" }, "type": "array" } }, { "description": "page number", "in": "query", "name": "page", "schema": { "minimum": 1, "type": "integer" } }, { "description": "page size", "in": "query", "name": "size", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "records": { "items": { "properties": { "contactId": { "type": "string" }, "emailBounceDiagCode": { "type": "string" }, "emailBounceSubType": { "type": "string" }, "emailBounceType": { "type": "string" }, "emailCampaignId": { "type": "string" }, "emailCampaignName": { "type": "string" }, "emailComplaintFeedbackType": { "type": "string" }, "emailDelayType": { "type": "string" }, "emailLinkId": { "type": "string" }, "emailRejectReason": { "type": "string" }, "emailSender": { "type": "string" }, "emailSenderName": { "type": "string" }, "emailSmtpResponse": { "type": "string" }, "emailSubject": { "type": "string" }, "emailTargetUrl": { "type": "string" }, "emailTo": { "type": "string" }, "importId": { "type": "string" }, "importOriginalFileName": { "type": "string" }, "source": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "triggeredBy": { "description": "Present on contact-created/contact-updated events when a triggering user is recorded. The type and userId fields come from the event index.", "properties": { "type": { "description": "The type of actor that triggered the event (e.g. 'user', 'admin')", "type": "string" }, "userId": { "description": "The ID of the user who triggered the event", "type": "string" } }, "type": "object" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "total": { "type": "integer" } }, "type": "object" } } }, "description": "Events for the contact" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get contact events", "tags": [ "contact" ], "x-api-key-scope": "contacts:read" } }, "/api/email/campaign": { "get": { "operationId": "get_api_email_campaign", "parameters": [ { "description": "page number", "in": "query", "name": "page", "schema": { "minimum": 1, "type": "integer" } }, { "description": "page size", "in": "query", "name": "size", "schema": { "minimum": 1, "type": "integer" } }, { "in": "query", "name": "statuses", "schema": { "enum": [ "scheduled", "sent", "draft", "sending", "paused", "failed", "cancelled" ], "type": "string" } }, { "description": "Sorting parameter with the format 'field:direction'. Supported fields: name, createdAt, updatedAt, scheduledAt.", "examples": { "ascSort": { "summary": "ascending sort by name", "value": "name:asc" }, "descSort": { "summary": "descending sort by createdAt", "value": "createdAt:desc" } }, "in": "query", "name": "sort", "required": false, "schema": { "pattern": "^[a-zA-Z0-9_]+:(asc|desc)$", "type": "string" } }, { "description": "A string used to filter the search results. The maximum length is 50 characters.", "in": "query", "name": "criteria", "schema": { "maxLength": 50, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "records": { "items": { "properties": { "_id": { "description": "Id of the campaign", "type": "string" }, "cancelledAt": { "description": "Timestamp when the campaign was cancelled or failed", "nullable": true, "type": "string" }, "createdAt": { "description": "Date and time of creation", "type": "string" }, "failedCount": { "description": "Failed sent count", "type": "number" }, "from": { "description": "From email address", "type": "string" }, "name": { "description": "Name of the campaign", "type": "string" }, "previewImageUrl": { "description": "Email Preview Image Url", "type": "string" }, "previewText": { "description": "Preview text of the email", "type": "string" }, "scheduledAt": { "description": "Date and time of scheduled email", "type": "string" }, "sentCount": { "description": "Successfully sent count", "type": "number" }, "stats": { "description": "email campaign stats", "properties": { "clicks": { "properties": { "rate": { "description": "Campaign click rate", "example": 15.75, "format": "float", "type": "number" }, "unique": { "description": "Campaign clicked count", "example": 145, "type": "number" } }, "type": "object" }, "delivered": { "description": "Campaign total delivered count", "example": 599, "type": "number" }, "opens": { "properties": { "rate": { "description": "Campaign open rate", "example": 25.35, "format": "float", "type": "number" }, "unique": { "description": "Campaign opened count", "example": 255, "type": "number" } }, "type": "object" }, "sent": { "description": "Campaign total sent count", "example": 650, "type": "number" } }, "type": "object" }, "status": { "description": "Status of the campaign", "type": "string" }, "subStatus": { "description": "Granular failure/cancellation reason. Null for non-failure states or legacy campaigns.", "enum": [ null ], "nullable": true, "type": "string" }, "subject": { "description": "Subject of the email", "type": "string" }, "totalRecipients": { "description": "Total email recipients", "type": "number" }, "updatedAt": { "description": "Date and time of last update", "type": "string" } }, "type": "object" }, "type": "array" }, "total": { "description": "Total number of campaigns", "type": "number" } }, "type": "object" } } }, "description": "Successfully retrieved" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get all campaigns", "tags": [ "email-campaign" ], "x-api-key-scope": "campaigns:read" }, "post": { "operationId": "post_api_email_campaign", "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "_id": { "description": "Id of the campaign", "type": "string" }, "cancelledAt": { "description": "Timestamp when the campaign was cancelled or failed", "nullable": true, "type": "string" }, "createdAt": { "description": "Date and time of creation", "type": "string" }, "failedCount": { "description": "Failed sent count", "type": "number" }, "previewImageUrl": { "description": "Email Preview Image Url", "type": "string" }, "scheduledAt": { "description": "Date and time of scheduled email", "type": "string" }, "sentCount": { "description": "Successfully sent count", "type": "number" }, "status": { "description": "Status of the campaign", "type": "string" }, "subStatus": { "description": "Granular failure/cancellation reason. Null for non-failure states or legacy campaigns.", "enum": [ null ], "nullable": true, "type": "string" }, "totalRecipients": { "description": "Total email recipients", "type": "number" }, "updatedAt": { "description": "Date and time of last update", "type": "string" } }, "type": "object" } } }, "description": "Successfully created" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Add a campaign", "tags": [ "email-campaign" ], "x-api-key-scope": "campaigns:write" } }, "/api/email/campaign/{campaignId}": { "delete": { "operationId": "delete_api_email_campaign_by_campaignId", "parameters": [ { "in": "path", "name": "campaignId", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Successfully deleted" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Campaign not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Delete campaign by id", "tags": [ "email-campaign" ], "x-api-key-scope": "campaigns:write" }, "get": { "operationId": "get_api_email_campaign_by_campaignId", "parameters": [ { "in": "path", "name": "campaignId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "_id": { "description": "Id of the campaign", "type": "string" }, "cancelledAt": { "description": "Timestamp when the campaign was cancelled or failed", "nullable": true, "type": "string" }, "createdAt": { "description": "Date and time of creation", "type": "string" }, "failedCount": { "description": "Failed sent count", "type": "number" }, "previewImageUrl": { "description": "Email Preview Image Url", "type": "string" }, "scheduledAt": { "description": "Date and time of scheduled email", "type": "string" }, "sentCount": { "description": "Successfully sent count", "type": "number" }, "status": { "description": "Status of the campaign", "type": "string" }, "subStatus": { "description": "Granular failure/cancellation reason. Null for non-failure states or legacy campaigns.", "enum": [ null ], "nullable": true, "type": "string" }, "totalRecipients": { "description": "Total email recipients", "type": "number" }, "updatedAt": { "description": "Date and time of last update", "type": "string" } }, "type": "object" } } }, "description": "Successfully retrieved" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get campaign by id", "tags": [ "email-campaign" ], "x-api-key-scope": "campaigns:read" }, "patch": { "operationId": "patch_api_email_campaign_by_campaignId", "parameters": [ { "in": "path", "name": "campaignId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "_id": { "description": "Id of the campaign", "type": "string" }, "cancelledAt": { "description": "Timestamp when the campaign was cancelled or failed", "nullable": true, "type": "string" }, "createdAt": { "description": "Date and time of creation", "type": "string" }, "failedCount": { "description": "Failed sent count", "type": "number" }, "previewImageUrl": { "description": "Email Preview Image Url", "type": "string" }, "scheduledAt": { "description": "Date and time of scheduled email", "type": "string" }, "sentCount": { "description": "Successfully sent count", "type": "number" }, "status": { "description": "Status of the campaign", "type": "string" }, "subStatus": { "description": "Granular failure/cancellation reason. Null for non-failure states or legacy campaigns.", "enum": [ null ], "nullable": true, "type": "string" }, "totalRecipients": { "description": "Total email recipients", "type": "number" }, "updatedAt": { "description": "Date and time of last update", "type": "string" } }, "type": "object" } } }, "description": "Successfully updated" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Update campaign by id", "tags": [ "email-campaign" ], "x-api-key-scope": "campaigns:write" } }, "/api/email/campaign/{campaignId}/duplicate": { "post": { "operationId": "post_api_email_campaign_by_campaignId_duplicate", "parameters": [ { "in": "path", "name": "campaignId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "_id": { "description": "Id of the campaign", "type": "string" }, "cancelledAt": { "description": "Timestamp when the campaign was cancelled or failed", "nullable": true, "type": "string" }, "createdAt": { "description": "Date and time of creation", "type": "string" }, "failedCount": { "description": "Failed sent count", "type": "number" }, "previewImageUrl": { "description": "Email Preview Image Url", "type": "string" }, "scheduledAt": { "description": "Date and time of scheduled email", "type": "string" }, "sentCount": { "description": "Successfully sent count", "type": "number" }, "status": { "description": "Status of the campaign", "type": "string" }, "subStatus": { "description": "Granular failure/cancellation reason. Null for non-failure states or legacy campaigns.", "enum": [ null ], "nullable": true, "type": "string" }, "totalRecipients": { "description": "Total email recipients", "type": "number" }, "updatedAt": { "description": "Date and time of last update", "type": "string" } }, "type": "object" } } }, "description": "Successfully duplicated" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Duplicate an existing campaign", "tags": [ "email-campaign" ], "x-api-key-scope": "campaigns:write" } }, "/api/email/domain": { "get": { "operationId": "get_api_email_domain", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "_id": { "description": "Id of the domain", "type": "string" }, "createdAt": { "description": "Date of creation", "type": "string" }, "dkim": { "description": "DKIM (DomainKeys Identified Mail) configuration (multi-record domains only)", "properties": { "records": { "description": "DNS records (CNAME record)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Verification details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastRecordFound": { "description": "Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "dmarc": { "description": "DMARC (Domain-based Message Authentication, Reporting & Conformance) configuration with status and DNS records (multi-record domains only)", "properties": { "records": { "description": "DNS records (TXT record)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Verification details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastRecordFound": { "description": "Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "domain": { "description": "Domain name", "type": "string" }, "identity": { "description": "Domain identity information (not present in multi-record domains - see spf/dkim sections instead)", "properties": { "mailFrom": { "description": "Mail-from configuration", "properties": { "status": { "description": "Mail-from status", "type": "string" }, "subdomain": { "description": "Mail-from subdomain", "type": "string" } }, "type": "object" }, "status": { "description": "Identity status (pending, created, verified, failed)", "type": "string" }, "verificationInfo": { "description": "Verification status and details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastCheckedAt": { "description": "Timestamp of last verification check", "format": "date-time", "type": "string" }, "lastRecordFound": { "description": "DKIM CNAME value from the most recent diagnostic DNS lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" }, "lastSuccessAt": { "description": "Timestamp of last successful verification", "format": "date-time", "type": "string" } }, "type": "object" }, "verificationStatus": { "description": "Overall verification status", "type": "string" } }, "type": "object" }, "isReadyForSending": { "description": "Is the domain ready for sending", "type": "boolean" }, "lastCheckedAt": { "description": "Date of last domain verification", "type": "string" }, "linkTracking": { "description": "Link tracking configuration with status and DNS records (multi-record domains only)", "properties": { "records": { "description": "DNS records (CNAME record)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Verification details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastRecordFound": { "description": "Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "nameServer": { "description": "Name server for the domain", "type": "string" }, "provider": { "description": "Domain provider", "type": "string" }, "spf": { "description": "SPF (Sender Policy Framework) configuration with mail-from records (multi-record domains only)", "properties": { "records": { "description": "DNS records (MX and TXT records)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Mail-from verification details", "properties": { "lastRecordFound": { "description": "DNS record values from the most recent diagnostic lookup", "nullable": true, "properties": { "mx": { "description": "MX exchange hostname found at bounces.{domain}. null if no record found.", "maxLength": 512, "nullable": true, "type": "string" }, "txt": { "description": "SPF TXT record value found at bounces.{domain}. null if no record found.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "sslCertStatus": { "description": "SSL certificate status (pending, created, renewed, expired, failed)", "type": "string" }, "status": { "description": "Status of the domain (verifying, verified)", "type": "string" }, "type": { "description": "Type of the domain (private, grey-label, multi-record)", "type": "string" }, "updatedAt": { "description": "Date of update", "type": "string" }, "validationResults": { "items": { "properties": { "checkedAt": { "description": "Date of last domain verification", "type": "string" }, "code": { "description": "Code of the validation result", "type": "string" }, "description": { "description": "Description of the validation result", "type": "string" }, "domainInfo": { "properties": { "authorities": { "description": "Authorities of the DNS record for the domain.", "items": { "type": "string" }, "type": "array" }, "domainFirstRecord": { "description": "First record found for the domain", "properties": { "ttl": { "description": "TTL of the DNS record", "type": "number" }, "type": { "description": "Type of the DNS record", "type": "string" }, "value": { "description": "Value of the DNS record", "type": "string" } }, "type": "object" }, "parentDomain": { "description": "Parent domain name", "type": "string" }, "parentNameServers": { "description": "Parent name servers", "items": { "type": "string" }, "type": "array" }, "resultRecord": { "description": "Result of the DNS record validation", "properties": { "type": { "description": "Type of the DNS record (NS, MX, A, CNAME, etc.)", "type": "string" }, "value": { "description": "Value of the DNS record", "type": "string" } }, "type": "object" }, "validType": { "description": "Indicates if the DNS record is valid type", "type": "boolean" }, "validValue": { "description": "Indicates if the DNS record is valid value", "type": "boolean" } }, "type": "object" }, "result": { "description": "Result of the validation", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } } }, "description": "Successfully fetched" }, "401": { "description": "Unauthorized" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get all domains", "tags": [ "email-domain" ], "x-api-key-scope": "domains:read" } }, "/api/email/domain/grey-label": { "get": { "operationId": "get_api_email_domain_grey_label", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "_id": { "description": "Id of the domain", "type": "string" }, "createdAt": { "description": "Date of creation", "type": "string" }, "dkim": { "description": "DKIM (DomainKeys Identified Mail) configuration (multi-record domains only)", "properties": { "records": { "description": "DNS records (CNAME record)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Verification details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastRecordFound": { "description": "Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "dmarc": { "description": "DMARC (Domain-based Message Authentication, Reporting & Conformance) configuration with status and DNS records (multi-record domains only)", "properties": { "records": { "description": "DNS records (TXT record)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Verification details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastRecordFound": { "description": "Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "domain": { "description": "Domain name", "type": "string" }, "identity": { "description": "Domain identity information (not present in multi-record domains - see spf/dkim sections instead)", "properties": { "mailFrom": { "description": "Mail-from configuration", "properties": { "status": { "description": "Mail-from status", "type": "string" }, "subdomain": { "description": "Mail-from subdomain", "type": "string" } }, "type": "object" }, "status": { "description": "Identity status (pending, created, verified, failed)", "type": "string" }, "verificationInfo": { "description": "Verification status and details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastCheckedAt": { "description": "Timestamp of last verification check", "format": "date-time", "type": "string" }, "lastRecordFound": { "description": "DKIM CNAME value from the most recent diagnostic DNS lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" }, "lastSuccessAt": { "description": "Timestamp of last successful verification", "format": "date-time", "type": "string" } }, "type": "object" }, "verificationStatus": { "description": "Overall verification status", "type": "string" } }, "type": "object" }, "isReadyForSending": { "description": "Is the domain ready for sending", "type": "boolean" }, "lastCheckedAt": { "description": "Date of last domain verification", "type": "string" }, "linkTracking": { "description": "Link tracking configuration with status and DNS records (multi-record domains only)", "properties": { "records": { "description": "DNS records (CNAME record)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Verification details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastRecordFound": { "description": "Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "nameServer": { "description": "Name server for the domain", "type": "string" }, "provider": { "description": "Domain provider", "type": "string" }, "spf": { "description": "SPF (Sender Policy Framework) configuration with mail-from records (multi-record domains only)", "properties": { "records": { "description": "DNS records (MX and TXT records)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Mail-from verification details", "properties": { "lastRecordFound": { "description": "DNS record values from the most recent diagnostic lookup", "nullable": true, "properties": { "mx": { "description": "MX exchange hostname found at bounces.{domain}. null if no record found.", "maxLength": 512, "nullable": true, "type": "string" }, "txt": { "description": "SPF TXT record value found at bounces.{domain}. null if no record found.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "sslCertStatus": { "description": "SSL certificate status (pending, created, renewed, expired, failed)", "type": "string" }, "status": { "description": "Status of the domain (verifying, verified)", "type": "string" }, "type": { "description": "Type of the domain (private, grey-label, multi-record)", "type": "string" }, "updatedAt": { "description": "Date of update", "type": "string" } }, "type": "object" } } }, "description": "Successfully fetched" }, "404": { "description": "Not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get the grey label domain for the account", "tags": [ "email-domain" ], "x-api-key-scope": "domains:read" } }, "/api/email/domain/{domainId}": { "get": { "operationId": "get_api_email_domain_by_domainId", "parameters": [ { "in": "path", "name": "domainId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "_id": { "description": "Id of the domain", "type": "string" }, "createdAt": { "description": "Date of creation", "type": "string" }, "dkim": { "description": "DKIM (DomainKeys Identified Mail) configuration (multi-record domains only)", "properties": { "records": { "description": "DNS records (CNAME record)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Verification details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastRecordFound": { "description": "Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "dmarc": { "description": "DMARC (Domain-based Message Authentication, Reporting & Conformance) configuration with status and DNS records (multi-record domains only)", "properties": { "records": { "description": "DNS records (TXT record)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Verification details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastRecordFound": { "description": "Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "domain": { "description": "Domain name", "type": "string" }, "identity": { "description": "Domain identity information (not present in multi-record domains - see spf/dkim sections instead)", "properties": { "mailFrom": { "description": "Mail-from configuration", "properties": { "status": { "description": "Mail-from status", "type": "string" }, "subdomain": { "description": "Mail-from subdomain", "type": "string" } }, "type": "object" }, "status": { "description": "Identity status (pending, created, verified, failed)", "type": "string" }, "verificationInfo": { "description": "Verification status and details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastCheckedAt": { "description": "Timestamp of last verification check", "format": "date-time", "type": "string" }, "lastRecordFound": { "description": "DKIM CNAME value from the most recent diagnostic DNS lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" }, "lastSuccessAt": { "description": "Timestamp of last successful verification", "format": "date-time", "type": "string" } }, "type": "object" }, "verificationStatus": { "description": "Overall verification status", "type": "string" } }, "type": "object" }, "isReadyForSending": { "description": "Is the domain ready for sending", "type": "boolean" }, "lastCheckedAt": { "description": "Date of last domain verification", "type": "string" }, "linkTracking": { "description": "Link tracking configuration with status and DNS records (multi-record domains only)", "properties": { "records": { "description": "DNS records (CNAME record)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Verification details", "properties": { "errorCode": { "description": "Error code if verification failed", "type": "string" }, "lastRecordFound": { "description": "Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "nameServer": { "description": "Name server for the domain", "type": "string" }, "provider": { "description": "Domain provider", "type": "string" }, "spf": { "description": "SPF (Sender Policy Framework) configuration with mail-from records (multi-record domains only)", "properties": { "records": { "description": "DNS records (MX and TXT records)", "items": { "properties": { "name": { "description": "DNS record name", "type": "string" }, "ttl": { "description": "Time to live in seconds", "type": "number" }, "type": { "description": "DNS record type (MX, TXT, CNAME)", "type": "string" }, "value": { "description": "DNS record value", "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "description": "Verification status (pending, success)", "type": "string" }, "verificationInfo": { "description": "Mail-from verification details", "properties": { "lastRecordFound": { "description": "DNS record values from the most recent diagnostic lookup", "nullable": true, "properties": { "mx": { "description": "MX exchange hostname found at bounces.{domain}. null if no record found.", "maxLength": 512, "nullable": true, "type": "string" }, "txt": { "description": "SPF TXT record value found at bounces.{domain}. null if no record found.", "maxLength": 512, "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "sslCertStatus": { "description": "SSL certificate status (pending, created, renewed, expired, failed)", "type": "string" }, "status": { "description": "Status of the domain (verifying, verified)", "type": "string" }, "type": { "description": "Type of the domain (private, grey-label, multi-record)", "type": "string" }, "updatedAt": { "description": "Date of update", "type": "string" }, "validationResults": { "items": { "properties": { "checkedAt": { "description": "Date of last domain verification", "type": "string" }, "code": { "description": "Code of the validation result", "type": "string" }, "description": { "description": "Description of the validation result", "type": "string" }, "domainInfo": { "properties": { "authorities": { "description": "Authorities of the DNS record for the domain.", "items": { "type": "string" }, "type": "array" }, "domainFirstRecord": { "description": "First record found for the domain", "properties": { "ttl": { "description": "TTL of the DNS record", "type": "number" }, "type": { "description": "Type of the DNS record", "type": "string" }, "value": { "description": "Value of the DNS record", "type": "string" } }, "type": "object" }, "parentDomain": { "description": "Parent domain name", "type": "string" }, "parentNameServers": { "description": "Parent name servers", "items": { "type": "string" }, "type": "array" }, "resultRecord": { "description": "Result of the DNS record validation", "properties": { "type": { "description": "Type of the DNS record (NS, MX, A, CNAME, etc.)", "type": "string" }, "value": { "description": "Value of the DNS record", "type": "string" } }, "type": "object" }, "validType": { "description": "Indicates if the DNS record is valid type", "type": "boolean" }, "validValue": { "description": "Indicates if the DNS record is valid value", "type": "boolean" } }, "type": "object" }, "result": { "description": "Result of the validation", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Successfully fetched" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get a domain by id", "tags": [ "email-domain" ], "x-api-key-scope": "domains:read" } }, "/api/email/template": { "get": { "description": "Get email templates with optional filters", "operationId": "get_api_email_template", "parameters": [ { "description": "Language code", "in": "query", "name": "lang", "required": true, "schema": { "type": "string" } }, { "description": "Search term to filter templates", "in": "query", "name": "searchTerm", "schema": { "type": "string" } }, { "description": "Template attribute IDs to filter by", "example": [ "6b1234567890123456789012" ], "explode": false, "in": "query", "name": "attributeIds", "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Flag to retrieve only internal templates (by default false)", "example": true, "in": "query", "name": "internal", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "records": { "items": { "properties": { "attributeIds": { "items": { "description": "Template category attribute IDs", "type": "string" }, "type": "array" }, "id": { "description": "Template ID", "type": "string" }, "imageUrl": { "description": "Template image URL", "type": "string" }, "lang": { "description": "Language code", "type": "string" }, "name": { "description": "Template name", "type": "string" }, "order": { "description": "Display order (ascending, 1-indexed). Present only when explicitly assigned.", "minimum": 1, "type": "integer" }, "subject": { "description": "Template subject", "type": "string" }, "unlayerId": { "description": "Template Unlayer ID", "type": "string" } }, "type": "object" }, "type": "array" }, "total": { "description": "Total number of templates", "type": "number" } }, "type": "object" } } }, "description": "Successful operation" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get email templates", "tags": [ "email-template" ], "x-api-key-scope": "campaigns:read" } }, "/api/email/template/categories": { "get": { "description": "Get all email template categories", "operationId": "getEmailTemplateCategories", "parameters": [ { "description": "Language code", "in": "query", "name": "lang", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "records": { "description": "List of template categories", "items": { "properties": { "attributes": { "description": "List of attributes in this category", "items": { "properties": { "categoryId": { "description": "Parent category ID", "type": "string" }, "id": { "description": "Attribute ID", "type": "string" }, "lang": { "description": "Language code", "type": "string" }, "order": { "description": "Attribute display order", "type": "integer" }, "value": { "description": "Attribute display value", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Category ID", "type": "string" }, "lang": { "description": "Language code", "type": "string" }, "name": { "description": "Category name", "type": "string" }, "order": { "description": "Category display order", "type": "integer" } }, "type": "object" }, "type": "array" }, "total": { "description": "Total number of categories", "type": "integer" } }, "type": "object" } } }, "description": "Successful operation" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get email template categories", "tags": [ "email-template" ], "x-api-key-scope": "campaigns:read" } }, "/api/email/template/{id}": { "get": { "description": "Get an email template by its ID", "operationId": "get_api_email_template_by_id", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Language code", "in": "query", "name": "lang", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "attributeIds": { "items": { "description": "Template category attribute IDs", "type": "string" }, "type": "array" }, "design": { "description": "Unlayer JSON of the template", "type": "string" }, "html": { "description": "HTML body of the template", "type": "string" }, "id": { "description": "Template ID", "type": "string" }, "imageUrl": { "description": "Template image URL", "type": "string" }, "lang": { "description": "Language code", "type": "string" }, "name": { "description": "Template name", "type": "string" }, "order": { "description": "Display order (ascending, 1-indexed). Present only when explicitly assigned.", "minimum": 1, "type": "integer" }, "subject": { "description": "Template subject", "type": "string" }, "unlayerId": { "description": "Template Unlayer ID", "type": "string" } }, "type": "object" } } }, "description": "Successful operation" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get email template by ID", "tags": [ "email-template" ], "x-api-key-scope": "campaigns:read" } }, "/api/reports/dashboard": { "get": { "operationId": "get_api_reports_dashboard", "parameters": [ { "description": "The number of past days (between 1 and 90) to retrieve report stats and precedent stats.", "in": "query", "name": "pastDays", "required": true, "schema": { "maximum": 90, "minimum": 1, "type": "integer" } }, { "description": "The user timezone (IANA) code.", "in": "query", "name": "timezone", "required": false, "schema": { "default": "UTC", "example": "America/La_Paz", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "campaign": { "description": "campaign reports", "properties": { "delivered": { "description": "delivered emails statistics.", "properties": { "count": { "description": "delivered email count.", "example": 2203, "type": "integer" }, "diff": { "description": "delivered email difference from previous period.", "example": 11.3, "format": "float", "type": "number" } }, "type": "object" }, "sent": { "description": "sent emails statistics.", "properties": { "count": { "description": "sent email count.", "example": 2379, "type": "integer" }, "diff": { "description": "sent email difference from previous period.", "example": 0.76, "format": "float", "type": "number" } }, "type": "object" }, "uniqueClicks": { "description": "clicked emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "unique clicked email count difference from previous period.", "example": -21.52, "format": "float", "type": "number" }, "value": { "description": "unique clicked email count", "example": 569, "type": "integer" } }, "type": "object" }, "rate": { "properties": { "diff": { "description": "unique clicked email rate difference from previous period.", "example": 20.47, "format": "float", "type": "number" }, "value": { "description": "unique clicked email rate (opens/delivered)", "example": 25.83, "format": "float", "type": "number" } }, "type": "object" } }, "type": "object" }, "uniqueOpens": { "description": "unique opened emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "unique opened email count difference from previous period.", "example": -23.41, "format": "float", "type": "number" }, "value": { "description": "unique opened email count", "example": 733, "type": "integer" } }, "type": "object" }, "rate": { "properties": { "diff": { "description": "unique opened email rate difference from previous period.", "example": -22.41, "format": "float", "type": "number" }, "value": { "description": "unique opened email rate (opens/delivered)", "example": 33.27, "format": "float", "type": "number" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "contact": { "properties": { "count": { "properties": { "diff": { "description": "contact count diff from past time period", "example": 29.55, "format": "float", "type": "number" }, "value": { "description": "current contact count", "example": 5900, "type": "number" } }, "type": "object" }, "histogram": { "properties": { "end": { "description": "contact snapshot histogram end date point", "example": "2024-10-29T00:00:00.000Z", "format": "date-time", "type": "string" }, "histogram": { "items": { "properties": { "date": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" }, "total": { "example": 4, "type": "integer" } }, "type": "object" }, "type": "array" }, "peak": { "properties": { "date": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" }, "total": { "example": 4, "type": "integer" } }, "type": "object" }, "start": { "description": "contact snapshot histogram start date point", "example": "2024-09-29T00:00:00.000Z", "format": "date-time", "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "description": "Successfully report retrieved" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get dashboard snapshot reports", "tags": [ "reports" ], "x-api-key-scope": "reports:read" } }, "/api/reports/email/overall": { "get": { "operationId": "get_api_reports_email_overall", "parameters": [ { "description": "The number of past days (between 1 and 90) to retrieve report stats and precedent stats.", "in": "query", "name": "pastDays", "required": true, "schema": { "maximum": 90, "minimum": 1, "type": "integer" } }, { "description": "The user timezone (IANA) code.", "in": "query", "name": "timezone", "required": false, "schema": { "default": "UTC", "example": "America/La_Paz", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "campaignComparison": { "items": { "properties": { "_id": { "description": "Campaign ID", "type": "string" }, "name": { "description": "Campaign name", "type": "string" }, "rates": { "properties": { "clicks": { "description": "Click rate", "format": "float", "type": "number" }, "opens": { "description": "Open rate", "format": "float", "type": "number" } }, "type": "object" }, "scheduledAt": { "description": "Campaign scheduled at", "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" }, "deliveryTimeStats": { "description": "Email delivery open rates by day time distribution statistics.", "properties": { "afternoon": { "description": "Percentage of open rate for delivered in the afternoon. (10am-4pm)", "example": 39.18, "format": "float", "type": "number" }, "evening": { "description": "Percentage of open rate for delivered in the evening. (4pm-10pm)", "example": 0, "format": "float", "type": "number" }, "morning": { "description": "Percentage of open rate for delivered in the morning. (4am-10am)", "example": 34.28, "format": "float", "type": "number" }, "night": { "description": "Percentage of open rate for delivered at night. (10pm-4am)", "example": 0, "format": "float", "type": "number" } }, "type": "object" }, "stats": { "properties": { "complaints": { "description": "Complaint emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "Complaint count difference from previous period.", "example": 100, "format": "float", "type": "number" }, "prev": { "description": "Previous period complaint email count.", "example": 5, "type": "integer" }, "value": { "description": "Complaint count.", "example": 10, "type": "integer" } }, "type": "object" } }, "type": "object" }, "delivered": { "description": "Delivered emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "Delivered email count difference from previous period.", "example": -42.95, "format": "float", "type": "number" }, "prev": { "description": "Previous period delivered email count.", "example": 3722, "type": "integer" }, "value": { "description": "Delivered email count.", "example": 2611, "type": "integer" } }, "type": "object" } }, "type": "object" }, "hardBounces": { "description": "Hard bounce emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "Hard bounce email count difference from previous period.", "example": -25.64, "format": "float", "type": "number" }, "prev": { "description": "Previous period hard bounce email count.", "example": 152, "type": "integer" }, "value": { "description": "Hard bounce email count.", "example": 116, "type": "integer" } }, "type": "object" }, "rate": { "properties": { "diff": { "description": "Hard bounce email rate difference from previous period.", "example": 30.21, "format": "float", "type": "number" }, "prev": { "description": "Previous period hard bounce email rate (bounces/sent).", "example": 22.32, "format": "float", "type": "number" }, "value": { "description": "Hard bounce email rate (bounces/sent).", "example": 28.53, "format": "float", "type": "number" } }, "type": "object" } }, "type": "object" }, "sent": { "description": "Sent emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "Sent email count difference from previous period.", "example": -42.28, "format": "float", "type": "number" }, "prev": { "description": "Previous period sent email count.", "example": 3942, "type": "integer" }, "value": { "description": "Sent email count.", "example": 2822, "type": "integer" } }, "type": "object" } }, "type": "object" }, "softBounces": { "description": "Soft bounce emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "Soft bounce email count difference from previous period.", "example": -39.1, "format": "float", "type": "number" }, "prev": { "description": "Previous period soft bounce email count.", "example": 125, "type": "integer" }, "value": { "description": "Soft bounce email count.", "example": 95, "type": "integer" } }, "type": "object" }, "rate": { "properties": { "diff": { "description": "Soft bounce email rate difference from previous period.", "example": 30.21, "format": "float", "type": "number" }, "prev": { "description": "Previous period soft bounce email rate (bounces/sent).", "example": 22.32, "format": "float", "type": "number" }, "value": { "description": "Soft bounce email rate (bounces/sent).", "example": 28.53, "format": "float", "type": "number" } }, "type": "object" } }, "type": "object" }, "totalBounces": { "description": "Total bounce emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "Total bounce email count difference from previous period.", "example": -25.64, "format": "float", "type": "number" }, "prev": { "description": "Previous period total bounce email count.", "example": 152, "type": "integer" }, "value": { "description": "Total bounce email count.", "example": 116, "type": "integer" } }, "type": "object" }, "rate": { "properties": { "diff": { "description": "Total bounce email rate difference from previous period.", "example": 30.21, "format": "float", "type": "number" }, "prev": { "description": "Previous period total bounce email rate (bounces/sent).", "example": 22.32, "format": "float", "type": "number" }, "value": { "description": "Total bounce email rate (bounces/sent).", "example": 28.53, "format": "float", "type": "number" } }, "type": "object" } }, "type": "object" }, "uniqueClicks": { "description": "Unique clicked emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "Unique clicked email count difference from previous period.", "example": -25.72, "format": "float", "type": "number" }, "prev": { "description": "Previous period unique clicked email count.", "example": 1283, "type": "integer" }, "value": { "description": "Unique clicked email count.", "example": 745, "type": "integer" } }, "type": "object" }, "rate": { "properties": { "diff": { "description": "Unique clicked email rate difference from previous period.", "example": 30.21, "format": "float", "type": "number" }, "prev": { "description": "Previous period unique clicked email rate (clicks/delivered).", "example": 22.32, "format": "float", "type": "number" }, "value": { "description": "Unique clicked email rate (clicks/delivered).", "example": 28.53, "format": "float", "type": "number" } }, "type": "object" } }, "type": "object" }, "uniqueOpens": { "description": "Unique opened emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "Unique opened email count difference from previous period.", "example": -28.34, "format": "float", "type": "number" }, "prev": { "description": "Previous period unique opened email count.", "example": 1283, "type": "integer" }, "value": { "description": "Unique opened email count.", "example": 971, "type": "integer" } }, "type": "object" }, "rate": { "properties": { "diff": { "description": "Unique opened email rate difference from previous period.", "example": 25.64, "format": "float", "type": "number" }, "prev": { "description": "Previous period unique opened email rate (opens/delivered).", "example": 27.32, "format": "float", "type": "number" }, "value": { "description": "Unique opened email rate (opens/delivered).", "example": 37.19, "format": "float", "type": "number" } }, "type": "object" } }, "type": "object" }, "unsubscribes": { "description": "Unsubscribed emails statistics.", "properties": { "count": { "properties": { "diff": { "description": "Unsubscribe count difference from previous period.", "example": -25, "format": "float", "type": "number" }, "prev": { "description": "Previous period unsubscribed email count.", "example": 125, "type": "integer" }, "value": { "description": "Unsubscribe count.", "example": 100, "type": "integer" } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "description": "Successfully report retrieved" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get overall email reports", "tags": [ "reports" ], "x-api-key-scope": "reports:read" } }, "/api/reports/email/overall/histogram": { "get": { "operationId": "get_api_reports_email_overall_histogram", "parameters": [ { "description": "The number of past days (between 1 and 90) to retrieve the event type histogram.", "in": "query", "name": "pastDays", "required": true, "schema": { "maximum": 90, "minimum": 1, "type": "integer" } }, { "description": "The requested campaign event type to generate the histogram.", "in": "query", "name": "eventType", "required": true, "schema": { "enum": [ "email-sent", "email-delivered", "email-bounced", "first-contact-unsubscribed", "first-email-complaint", "first-email-opened", "first-email-clicked" ], "type": "string" } }, { "description": "The user timezone (IANA) code.", "in": "query", "name": "timezone", "required": false, "schema": { "default": "UTC", "example": "America/La_Paz", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Campaign histogram details", "properties": { "end": { "example": "2024-09-24T17:00:00.000Z", "format": "date-time", "type": "string" }, "histogram": { "items": { "properties": { "date": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" }, "detail": { "description": "Details only for email-bounced event type", "properties": { "hard": { "example": 3, "type": "integer" }, "soft": { "example": 1, "type": "integer" } }, "type": "object" }, "total": { "example": 4, "type": "integer" } }, "type": "object" }, "type": "array" }, "peak": { "properties": { "endDate": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" }, "startDate": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" }, "total": { "example": 4, "type": "integer" } }, "type": "object" }, "start": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" } }, "type": "object" } } }, "description": "Successfully report retrieved" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get overall email histogram by event type", "tags": [ "reports" ], "x-api-key-scope": "reports:read" } }, "/api/reports/email/{id}": { "get": { "operationId": "get_api_reports_email_by_id", "parameters": [ { "description": "email campaign identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "linkActivity": { "description": "List of link activity", "items": { "properties": { "clicks": { "properties": { "total": { "example": 0, "type": "integer" }, "unique": { "example": 0, "type": "integer" } }, "type": "object" }, "id": { "example": "66f1a6e4698f1bca60424808", "type": "string" }, "path": { "example": "https://instagram.com/", "type": "string" } }, "type": "object" }, "type": "array" }, "stats": { "description": "Statistics of the campaign", "properties": { "clicks": { "description": "Email clicks statistics", "properties": { "last": { "example": "2024-09-27T18:28:40.575Z", "format": "date-time", "type": "string" }, "rate": { "example": 25.8, "format": "float", "type": "number" }, "unique": { "example": 169, "type": "integer" } }, "type": "object" }, "complaints": { "description": "Number of complaints", "example": 0, "type": "integer" }, "delivered": { "description": "Total number of delivered emails", "example": 655, "type": "integer" }, "hardBounces": { "description": "Hard bounce emails statistics", "properties": { "count": { "example": 25, "type": "integer" }, "rate": { "example": 3.81, "format": "float", "type": "number" } }, "type": "object" }, "opens": { "description": "Email opens statistics", "properties": { "last": { "example": "2024-09-27T17:33:45.464Z", "format": "date-time", "type": "string" }, "rate": { "example": 32.06, "format": "float", "type": "number" }, "unique": { "example": 210, "type": "integer" } }, "type": "object" }, "sent": { "description": "Total number of sent emails", "example": 697, "type": "integer" }, "softBounces": { "description": "Soft bounce emails statistics", "properties": { "count": { "example": 17, "type": "integer" }, "rate": { "example": 2.59, "format": "float", "type": "number" } }, "type": "object" }, "totalBounces": { "description": "Total bounce emails statistics", "properties": { "count": { "example": 42, "type": "integer" }, "rate": { "example": 6.87, "format": "float", "type": "number" } }, "type": "object" }, "unsubscribes": { "description": "Number of unsubscribes", "example": 0, "type": "integer" } }, "type": "object" } }, "type": "object" } } }, "description": "Successfully retrieved report" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get individual email campaign reports", "tags": [ "reports" ], "x-api-key-scope": "reports:read" } }, "/api/reports/email/{id}/engagement": { "get": { "operationId": "get_api_reports_email_by_id_engagement", "parameters": [ { "description": "email campaign identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The engage period criteria to generate the histogram.", "in": "query", "name": "period", "required": false, "schema": { "default": "24hours", "enum": [ "24hours", "week", "month" ], "type": "string" } }, { "description": "The user timezone (IANA) code.", "in": "query", "name": "timezone", "required": false, "schema": { "default": "UTC", "example": "America/La_Paz", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "Campaign histogram details", "properties": { "end": { "example": "2024-09-24T17:00:00.000Z", "format": "date-time", "type": "string" }, "histogram": { "items": { "properties": { "date": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" }, "detail": { "properties": { "uniqueClicks": { "example": 1, "type": "integer" }, "uniqueOpens": { "example": 3, "type": "integer" } }, "type": "object" }, "total": { "example": 4, "type": "integer" } }, "type": "object" }, "type": "array" }, "peak": { "properties": { "endDate": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" }, "startDate": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" }, "total": { "example": 4, "type": "integer" } }, "type": "object" }, "start": { "example": "2024-09-23T17:00:00.000Z", "format": "date-time", "type": "string" } }, "type": "object" } } }, "description": "Successfully retrieved report" } }, "security": [ { "apiKeyAuth": [] } ], "summary": "Get individual email campaign engagement reports", "tags": [ "reports" ], "x-api-key-scope": "reports:read" } } }, "security": [ { "apiKeyAuth": [] } ], "servers": [ { "description": "Your account's API base URL. Copy the full URL shown on Settings > API Keys in your Benchmark Email account and paste it here.", "url": "{apiBaseUrl}", "variables": { "apiBaseUrl": { "default": "", "description": "Your account's API base URL. Copy it from Settings > API Keys in your Benchmark Email account." } } } ], "tags": [ { "description": "Contact related endpoints", "name": "contact" }, { "description": "Contact structure related endpoints", "name": "contact-structure" }, { "description": "List related endpoints", "name": "lists" }, { "description": "Email domain related endpoints", "name": "email-domain" }, { "description": "Email campaign related endpoints", "name": "email-campaign" }, { "description": "Email template related endpoints", "name": "email-template" }, { "description": "Report related endpoints", "name": "reports" } ] }