{
"openapi": "3.1.0",
"info": {
"title": "Ecomail API",
"version": "2.0",
"description": "Programmatically manage your email marketing — lists, subscribers, campaigns, automations, and more.",
"contact": {
"name": "Ecomail",
"url": "https://ecomail.cz",
"email": "support@ecomail.cz"
},
"license": {
"name": "Proprietary",
"url": "https://ecomail.cz/obchodni-podminky/"
}
},
"servers": [
{
"url": "https://api2.ecomailapp.cz"
}
],
"security": [
{
"apiKey": []
}
],
"tags": [
{
"name": "Automations",
"description": "Trigger automation pipelines and read automation statistics."
},
{
"name": "Campaigns",
"description": "Create, send, and analyze email campaigns."
},
{
"name": "Discount coupons",
"description": "Import and delete discount coupons."
},
{
"name": "Domains",
"description": "Manage sending domains and their verification status."
},
{
"name": "Feeds",
"description": "Refresh product feed data used for personalization."
},
{
"name": "Lists",
"description": "Manage subscriber lists and the subscribers within them."
},
{
"name": "Recommenders",
"description": "Manage product recommendation engines."
},
{
"name": "Search",
"description": "Search for contacts across your account."
},
{
"name": "Subscribers",
"description": "Read subscriber profiles, events, and activity logs."
},
{
"name": "Templates",
"description": "Manage reusable email templates."
},
{
"name": "Tracker events",
"description": "Send custom tracking events for contacts."
},
{
"name": "Transactional emails",
"description": "Send transactional messages and read their statistics."
},
{
"name": "Transactions",
"description": "Record and manage e-commerce transactions."
},
{
"name": "Webhooks",
"description": "Configure webhook URLs for real-time event delivery."
}
],
"paths": {
"/pipelines": {
"get": {
"operationId": "automationsListAll",
"summary": "List all automations",
"description": "Retrieve all automations in your account.",
"tags": [
"Automations"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"list_id": {
"type": "integer"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
}
},
"example": [
{
"id": 1,
"name": "Pipeline name",
"list_id": 1,
"created_at": "2020-09-08 22:04:03",
"updated_at": "2021-04-03 20:04:04"
}
]
}
}
}
}
}
},
"/pipelines/{id}/actions": {
"get": {
"operationId": "automationsGetActions",
"summary": "Get automation actions",
"description": "Retrieve all actions (nodes) within a given automation.",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Automation ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"properties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"template": {
"type": "integer"
}
}
},
"next": {
"description": "Ids of the follow-up nodes: an array of node ids on most node types, or an object with one array of node ids per output port on branching node types (`yes`/`no` on a check node, the variant keys on a split node, `default`/`quarantine_skip` on a mail node). Empty or null at the end of a branch.",
"nullable": true,
"oneOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
]
}
}
}
}
}
},
"example": {
"data": [
{
"id": "abc-123",
"type": "mail",
"properties": {
"name": "Welcome email",
"template": 42
},
"next": ["def-456"]
},
{
"id": "def-456",
"type": "check",
"properties": {
"name": "Opened the welcome email?"
},
"next": {
"yes": ["ghi-789"],
"no": []
}
},
{
"id": "ghi-789",
"type": "tag",
"properties": {
"tag": "engaged"
},
"next": []
}
]
}
}
}
}
}
}
},
"/pipelines/{id}/actions/{actionId}": {
"get": {
"operationId": "automationsGetActionDetail",
"summary": "Get automation action detail",
"description": "Retrieve detail of a specific action (node) within a given automation.",
"tags": [
"Automations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Automation ID.",
"schema": {
"type": "integer"
}
},
{
"name": "actionId",
"in": "path",
"required": true,
"description": "Action ID.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"properties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"template": {
"type": "integer"
}
}
},
"next": {
"description": "Ids of the follow-up nodes: an array of node ids on most node types, or an object with one array of node ids per output port on branching node types (`yes`/`no` on a check node, the variant keys on a split node, `default`/`quarantine_skip` on a mail node). Empty or null at the end of a branch.",
"nullable": true,
"oneOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
]
}
}
}
}
},
"example": {
"data": {
"id": "abc-123",
"type": "mail",
"properties": {
"name": "Welcome email",
"template": 42
},
"next": ["def-456"]
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"example": {
"message": "Action not found"
}
}
}
}
}
}
},
"/pipelines/{pipeline_id}/trigger": {
"post": {
"operationId": "automationsTrigger",
"summary": "Trigger automation",
"description": "Run a specific automation for the given email/subscriber.",
"tags": [
"Automations"
],
"parameters": [
{
"name": "pipeline_id",
"in": "path",
"required": true,
"description": "Automation ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Subscriber's email address."
}
},
"required": [
"email"
]
},
"example": {
"email": "foo@bar.cz"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string"
}
}
},
"example": {
"email": "foo@bar.cz"
}
}
}
}
}
}
},
"/pipelines/{pipeline_id}/stats": {
"get": {
"operationId": "automationsGetStats",
"summary": "Get automation stats",
"description": "Retrieve aggregate statistics for a specific automation.",
"tags": [
"Automations"
],
"parameters": [
{
"name": "pipeline_id",
"in": "path",
"required": true,
"description": "Automation ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"stats": {
"type": "object",
"properties": {
"triggered": {
"type": "integer"
},
"ended": {
"type": "integer"
},
"open": {
"type": "integer"
},
"open_rate": {
"type": "integer"
},
"total_open": {
"type": "integer"
},
"not_opened": {
"type": "integer"
},
"send": {
"type": "integer"
},
"click": {
"type": "integer"
},
"total_click": {
"type": "integer"
},
"click_rate": {
"type": "integer"
},
"inject": {
"type": "integer"
},
"soft_bounce": {
"type": "integer"
},
"hard_bounce": {
"type": "integer"
},
"bounce": {
"type": "integer"
},
"bounce_rate": {
"type": "integer"
},
"conversions": {
"type": "integer"
},
"conversions_value": {
"type": "integer"
},
"spam": {
"type": "integer"
},
"unsub": {
"type": "integer"
},
"delivery_rate": {
"type": "integer"
}
}
}
}
},
"example": {
"stats": {
"triggered": 1,
"ended": 1,
"open": 0,
"open_rate": 0,
"total_open": 0,
"not_opened": 2,
"send": 2,
"click": 1,
"total_click": 4,
"click_rate": 50,
"inject": 2,
"soft_bounce": 0,
"hard_bounce": 0,
"bounce": 0,
"bounce_rate": 0,
"conversions": 0,
"conversions_value": 0,
"spam": 0,
"unsub": 0,
"delivery_rate": 100
}
}
}
}
}
}
}
},
"/pipelines/{pipeline_id}/stats-detail": {
"get": {
"operationId": "automationsGetStatsDetail",
"summary": "Get automation stats detail",
"description": "Return statistics for a specific automation with each subscriber and their individual events.",
"tags": [
"Automations"
],
"parameters": [
{
"name": "pipeline_id",
"in": "path",
"required": true,
"description": "Automation ID.",
"schema": {
"type": "integer"
}
},
{
"name": "event",
"in": "query",
"required": false,
"description": "Filter by event type. One of: `open`, `send`, `unsub`, `soft_bounce`, `click`, `hard_bounce`, `out_of_band`, `spam`.",
"schema": {
"type": "string"
}
},
{
"name": "email",
"in": "query",
"required": false,
"description": "Filter by subscriber email address.",
"schema": {
"type": "string"
}
},
{
"name": "from_date",
"in": "query",
"required": false,
"description": "Filter from date onwards in `YYYY-MM-DD` format (UTC).",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Number of results per page. Default is `100`, maximum is `5000`.",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page number.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"next_page_url": {
"type": "string"
},
"total": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"subscribers": {
"type": "object",
"properties": {
"foo@bar.com": {
"type": "object",
"properties": {
"open": {
"type": "integer"
},
"send": {
"type": "integer"
},
"unsub": {
"type": "integer"
},
"soft_bounce": {
"type": "integer"
},
"click": {
"type": "integer"
},
"hard_bounce": {
"type": "integer"
},
"out_of_band": {
"type": "integer"
},
"spam": {
"type": "integer"
}
}
}
}
}
}
},
"example": {
"next_page_url": "https://api2.ecomailapp.cz/pipelines/12345/stats-detail?page=2",
"total": 2546,
"per_page": 100,
"subscribers": {
"foo@bar.com": {
"open": 2,
"send": 3,
"unsub": 0,
"soft_bounce": 0,
"click": 0,
"hard_bounce": 0,
"out_of_band": 0,
"spam": 0
}
}
}
}
}
}
}
}
},
"/campaigns": {
"get": {
"operationId": "campaignsListAll",
"summary": "List all campaigns",
"description": "Returns all campaigns with pagination and filtering.",
"tags": [
"Campaigns"
],
"parameters": [
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Number of items per page.",
"schema": {
"type": "integer"
}
},
{
"name": "filters[title]",
"in": "query",
"required": false,
"description": "Filter by campaign title.",
"schema": {
"type": "string"
}
},
{
"name": "filters[subject]",
"in": "query",
"required": false,
"description": "Filter by campaign subject.",
"schema": {
"type": "string"
}
},
{
"name": "filters[status]",
"in": "query",
"required": false,
"description": "Filter by campaign status code.",
"schema": {
"type": "integer"
}
},
{
"name": "filters[updated_at]",
"in": "query",
"required": false,
"description": "Filter by updated date (`YYYY-MM-DD`).",
"schema": {
"type": "string"
}
},
{
"name": "filters[date_from]",
"in": "query",
"required": false,
"description": "Filter from date (`YYYY-MM-DD`).",
"schema": {
"type": "string"
}
},
{
"name": "filters[date_to]",
"in": "query",
"required": false,
"description": "Filter to date (`YYYY-MM-DD`).",
"schema": {
"type": "string"
}
},
{
"name": "filters[id]",
"in": "query",
"required": false,
"description": "Filter by campaign ID.",
"schema": {
"type": "integer"
}
},
{
"name": "sort_by",
"in": "query",
"required": false,
"description": "Column to sort results by. Allowed values: `id`, `sent_at`, `changed_at`, `title`, `status`.",
"schema": {
"type": "string",
"default": "id"
}
},
{
"name": "sort_dir",
"in": "query",
"required": false,
"description": "Sort direction. Allowed values: `asc`, `desc`.",
"schema": {
"type": "string",
"default": "desc"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"from_name": {
"type": "string"
},
"from_email": {
"type": "string"
},
"reply_to": {
"type": "string"
},
"title": {
"type": "string"
},
"subject": {
"type": "string"
},
"sent_at": {
"type": "string"
},
"recipients": {
"type": "integer"
},
"status": {
"type": "integer"
},
"scheduled_at": {},
"template_id": {
"type": "integer"
},
"archive_url": {
"type": "string"
}
}
}
},
"example": [
{
"id": 1,
"from_name": "From name",
"from_email": "from@foo.cz",
"reply_to": "reply@bar.cz",
"title": "My first campaign",
"subject": "First hello",
"sent_at": "2014-09-08 22:04:03",
"recipients": 1,
"status": 3,
"scheduled_at": null,
"template_id": 62,
"archive_url": "https://foo.ecomailapp.cz/campaigns/render/1/randomhashhere"
}
]
}
}
}
}
},
"post": {
"operationId": "campaignsAddNew",
"summary": "Add new campaign",
"description": "Create a new campaign.",
"tags": [
"Campaigns"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Campaign title."
},
"from_name": {
"type": "string",
"description": "Sender's name."
},
"from_email": {
"type": "string",
"description": "Sender's email address."
},
"reply_to": {
"type": "string",
"description": "Reply-to email address."
},
"subject": {
"type": "string",
"description": "Campaign subject line."
},
"html_text": {
"type": "string",
"description": "HTML content of the campaign."
},
"recepient_lists": {
"type": [
"array",
"object"
],
"description": "Array of list IDs or an object with segments. See the example above for the segments format.",
"items": {}
}
},
"required": [
"title",
"from_name",
"from_email",
"reply_to",
"subject",
"html_text",
"recepient_lists"
]
},
"example": {
"title": "Campaign title",
"from_name": "Senders name",
"from_email": "test@ecomailapp.cz",
"reply_to": "test@ecomailapp.cz",
"subject": "New campaign subject",
"html_text": "HTML content of new campaign",
"recepient_lists": [
1
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"from_name": {
"type": "string"
},
"from_email": {
"type": "string"
},
"reply_to": {
"type": "string"
},
"subject": {
"type": "string"
},
"recepient_lists": {
"type": "array",
"items": {
"type": "integer"
}
},
"template_type": {
"type": "string"
},
"campaign_type": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
},
"example": {
"id": 712,
"title": "Campaign title",
"from_name": "Senders name",
"from_email": "test@ecomailapp.cz",
"reply_to": "test@ecomailapp.cz",
"subject": "New campaign subject",
"recepient_lists": [
1
],
"template_type": "html",
"campaign_type": "email",
"updated_at": "2023-06-14T10:16:16.112614Z"
}
}
}
}
}
}
},
"/campaigns/{campaign_id}": {
"get": {
"operationId": "campaignsGetDetail",
"summary": "Get campaign detail",
"description": "Returns detailed campaign information including statistics for sent campaigns.",
"tags": [
"Campaigns"
],
"parameters": [
{
"name": "campaign_id",
"in": "path",
"required": true,
"description": "Campaign ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"from_name": {
"type": "string"
},
"from_email": {
"type": "string"
},
"reply_to": {
"type": "string"
},
"title": {
"type": "string"
},
"subject": {
"type": "string"
},
"recepient_lists": {
"type": "object",
"properties": {
"segments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"list": {
"type": "integer"
}
}
}
}
}
},
"sent_at": {
"type": "string"
},
"recipients": {
"type": "integer"
},
"status": {
"type": "integer"
},
"archive_url": {
"type": "string"
},
"stats": {
"type": "object",
"properties": {
"inject": {
"type": "integer"
},
"send": {
"type": "integer"
},
"delivered": {
"type": "integer"
},
"open": {
"type": "integer"
},
"total_open": {
"type": "integer"
},
"click": {
"type": "integer"
},
"total_click": {
"type": "integer"
},
"hard_bounce": {
"type": "integer"
},
"spam": {
"type": "integer"
},
"unsub": {
"type": "integer"
},
"openrate": {
"type": "number"
},
"clickrate": {
"type": "number"
},
"delivery_rate": {
"type": "integer"
}
}
}
}
},
"example": {
"id": 1,
"from_name": "From name",
"from_email": "from@foo.cz",
"reply_to": "reply@bar.cz",
"title": "My first campaign",
"subject": "First hello",
"recepient_lists": {
"segments": [
{
"id": "segment_abc123",
"list": 1
}
]
},
"sent_at": "2025-01-10 08:30:00",
"recipients": 100,
"status": 3,
"archive_url": "https://foo.ecomailapp.cz/campaigns/render/1/randomhashhere",
"stats": {
"inject": 100,
"send": 99,
"delivered": 99,
"open": 40,
"total_open": 45,
"click": 12,
"total_click": 15,
"hard_bounce": 1,
"spam": 0,
"unsub": 2,
"openrate": 40.4,
"clickrate": 12.12,
"delivery_rate": 99
}
}
}
}
}
}
},
"put": {
"operationId": "campaignsUpdate",
"summary": "Update campaign",
"description": "Update an existing campaign.",
"tags": [
"Campaigns"
],
"parameters": [
{
"name": "campaign_id",
"in": "path",
"required": true,
"description": "Campaign ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Campaign title."
},
"from_name": {
"type": "string",
"description": "Sender's name."
},
"from_email": {
"type": "string",
"description": "Sender's email address."
},
"reply_to": {
"type": "string",
"description": "Reply-to email address."
},
"subject": {
"type": "string",
"description": "Campaign subject line."
},
"html_text": {
"type": "string",
"description": "HTML content of the campaign."
},
"recepient_lists": {
"type": [
"array",
"object"
],
"description": "Array of list IDs or an object with segments.",
"items": {}
}
},
"required": [
"title",
"from_name",
"from_email",
"reply_to",
"subject",
"html_text",
"recepient_lists"
]
},
"example": {
"title": "Campaign title",
"from_name": "Senders name",
"from_email": "test@ecomailapp.cz",
"reply_to": "test@ecomailapp.cz",
"subject": "New campaign subject",
"html_text": "HTML content of new campaign",
"recepient_lists": [
1,
2
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"from_name": {
"type": "string"
},
"from_email": {
"type": "string"
},
"reply_to": {
"type": "string"
},
"title": {
"type": "string"
},
"subject": {
"type": "string"
},
"status": {
"type": "integer"
},
"archive_url": {
"type": "string"
}
}
},
"example": {
"id": 1,
"from_name": "From name",
"from_email": "from@foo.cz",
"reply_to": "reply@bar.cz",
"title": "My first campaign",
"subject": "First hello",
"status": 0,
"archive_url": "https://foo.ecomailapp.cz/campaigns/render/1"
}
}
}
}
}
}
},
"/campaigns/{campaign_id}/send": {
"post": {
"operationId": "campaignsSend",
"summary": "Send campaign",
"description": "Puts the campaign in the sending queue immediately.",
"tags": [
"Campaigns"
],
"parameters": [
{
"name": "campaign_id",
"in": "path",
"required": true,
"description": "Campaign ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"from_name": {
"type": "string"
},
"from_email": {
"type": "string"
},
"reply_to": {
"type": "string"
},
"subject": {
"type": "string"
},
"recepient_lists": {
"type": "array",
"items": {
"type": "integer"
}
},
"template_type": {
"type": "string"
},
"campaign_type": {
"type": "string"
}
}
}
},
"example": [
{
"id": 1,
"title": "My first campaign",
"from_name": "From name",
"from_email": "from@foo.cz",
"reply_to": "reply@bar.cz",
"subject": "First hello",
"recepient_lists": [
1,
2
],
"template_type": "html",
"campaign_type": "email"
}
]
}
}
}
}
}
},
"/campaigns/{campaign_id}/send-test": {
"post": {
"operationId": "campaignsSendTest",
"summary": "Send test campaign",
"description": "Sends a test version of a draft campaign to up to 5 recipients.",
"tags": [
"Campaigns"
],
"parameters": [
{
"name": "campaign_id",
"in": "path",
"required": true,
"description": "Campaign ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"emails": {
"type": "array",
"description": "Recipients of the test email. At least 1 and at most 5 email addresses.",
"items": {}
},
"merge": {
"type": "object",
"description": "Optional map of merge-tag values used to personalize the test email. Keys are merge-tag names, values are their replacements; empty values are ignored."
}
},
"required": [
"emails"
]
},
"example": {
"emails": [
"test@foo.cz",
"qa@foo.cz"
],
"merge": {
"first_name": "Foo"
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"campaign_id": {
"type": "integer"
},
"sent_emails_count": {
"type": "integer"
}
}
},
"example": {
"campaign_id": 1,
"sent_emails_count": 2
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"errors": [
"You can not do this because you have a blocked account"
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"errors": [
"Only draft campaigns can be tested."
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"example": {
"errors": {
"emails": [
"The emails field is required."
]
}
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"errors": [
"You have exceeded daily limit of sent test emails of 50."
]
}
}
}
}
}
}
},
"/campaigns/{campaign_id}/stats": {
"get": {
"operationId": "campaignsGetStats",
"summary": "Get campaign stats",
"description": "Returns aggregated statistics for a specific campaign.",
"tags": [
"Campaigns"
],
"parameters": [
{
"name": "campaign_id",
"in": "path",
"required": true,
"description": "Campaign ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"stats": {
"type": "object",
"properties": {
"inject": {
"type": "integer"
},
"delivery": {
"type": "integer"
},
"delivery_rate": {
"type": "integer"
},
"open": {
"type": "integer"
},
"total_open": {
"type": "integer"
},
"open_rate": {
"type": "integer"
},
"click": {
"type": "integer"
},
"total_click": {
"type": "integer"
},
"click_rate": {
"type": "integer"
},
"bounce": {
"type": "integer"
},
"bounce_rate": {
"type": "integer"
},
"spam": {
"type": "integer"
},
"spam_rate": {
"type": "number"
},
"unsub": {
"type": "integer"
},
"unsub_rate": {
"type": "integer"
},
"conversions": {
"type": "integer"
},
"conversions_value": {
"type": "integer"
}
}
}
}
},
"example": {
"stats": {
"inject": 10,
"delivery": 10,
"delivery_rate": 97,
"open": 5,
"total_open": 10,
"open_rate": 10,
"click": 2,
"total_click": 4,
"click_rate": 4,
"bounce": 3,
"bounce_rate": 3,
"spam": 1,
"spam_rate": 0.01,
"unsub": 1,
"unsub_rate": 1,
"conversions": 0,
"conversions_value": 0
}
}
}
}
}
}
}
},
"/campaigns/{id}/stats-detail": {
"get": {
"operationId": "campaignsGetStatsDetail",
"summary": "Get campaign stats detail",
"description": "Returns statistics for a specific campaign with each subscriber and their individual events.",
"tags": [
"Campaigns"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Campaign ID.",
"schema": {
"type": "integer"
}
},
{
"name": "event",
"in": "query",
"required": false,
"description": "Filter by event type: `open`, `send`, `unsub`, `soft_bounce`, `click`, `hard_bounce`, `out_of_band`, `spam`.",
"schema": {
"type": "string"
}
},
{
"name": "email",
"in": "query",
"required": false,
"description": "Filter by subscriber email.",
"schema": {
"type": "string"
}
},
{
"name": "from_date",
"in": "query",
"required": false,
"description": "Filter from date onwards (`YYYY-MM-DD` in UTC).",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Results per page. Maximum and default is `100`.",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page number.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"next_page_url": {
"type": "string"
},
"total": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"subscribers": {
"type": "object",
"properties": {
"foo@bar.com": {
"type": "object",
"properties": {
"open": {
"type": "integer"
},
"send": {
"type": "integer"
},
"unsub": {
"type": "integer"
},
"soft_bounce": {
"type": "integer"
},
"click": {
"type": "integer"
},
"hard_bounce": {
"type": "integer"
},
"out_of_band": {
"type": "integer"
},
"spam": {
"type": "integer"
}
}
}
}
}
}
},
"example": {
"next_page_url": "https://api2.ecomailapp.cz/campaigns/12345/stats-detail?page=2",
"total": 4256,
"per_page": 100,
"subscribers": {
"foo@bar.com": {
"open": 2,
"send": 1,
"unsub": 0,
"soft_bounce": 0,
"click": 1,
"hard_bounce": 0,
"out_of_band": 0,
"spam": 0
}
}
}
}
}
}
}
}
},
"/campaigns/segment/{segmentId}/stats": {
"get": {
"operationId": "campaignsGetSegmentStats",
"summary": "Get segment stats",
"description": "Retrieves performance statistics for a specific segment across all campaigns it was sent to.",
"tags": [
"Campaigns"
],
"parameters": [
{
"name": "segmentId",
"in": "path",
"required": true,
"description": "Segment ID. Can be retrieved from the [Show list detail](/api-reference/lists/show) endpoint.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"stats": {
"type": "object",
"properties": {
"810": {
"type": "object",
"properties": {
"bounce": {
"type": "integer"
},
"bounce_rate": {
"type": "integer"
},
"click": {
"type": "integer"
},
"click_rate": {
"type": "integer"
},
"conversions": {
"type": "integer"
},
"conversions_value": {
"type": "integer"
},
"delivery": {
"type": "integer"
},
"delivery_rate": {
"type": "integer"
},
"inject": {
"type": "integer"
},
"open": {
"type": "integer"
},
"open_rate": {
"type": "integer"
},
"spam": {
"type": "integer"
},
"spam_rate": {
"type": "integer"
},
"unsub": {
"type": "integer"
},
"unsub_rate": {
"type": "integer"
}
}
}
}
}
}
},
"example": {
"stats": {
"810": {
"bounce": 0,
"bounce_rate": 0,
"click": 3,
"click_rate": 75,
"conversions": 2,
"conversions_value": 2500,
"delivery": 4,
"delivery_rate": 100,
"inject": 4,
"open": 4,
"open_rate": 100,
"spam": 0,
"spam_rate": 0,
"unsub": 1,
"unsub_rate": 25
}
}
}
}
}
}
}
}
},
"/campaigns/{campaignId}/log": {
"get": {
"operationId": "campaignsGetLog",
"summary": "Get campaign log",
"description": "Search and browse the campaign log — sends, opens, clicks, bounces, unsubscribes, complaints, and other events. Filter by subscriber email, event types, and date range.",
"tags": [
"Campaigns"
],
"parameters": [
{
"name": "email",
"in": "query",
"required": false,
"description": "Filter by subscriber email address.",
"schema": {
"type": "string"
}
},
{
"name": "events[]",
"in": "query",
"required": false,
"description": "Filter by event types. Can be specified multiple times. Possible values: `send`, `open`, `click`, `bounce`, `hard_bounce`, `soft_bounce`, `out_of_band`, `unsub`, `spam`, `spam_complaint`, `not_opened`, `not_clicked`, `open_no_click`, `sms_sent`, `sms_inv_nr`, `sms_accepted`, `whatsapp_sent`, `whatsapp_failed`.",
"schema": {
"type": "string"
}
},
{
"name": "date_from",
"in": "query",
"required": false,
"description": "Filter events from this date (inclusive, ISO format e.g. `2025-01-01`).",
"schema": {
"type": "string"
}
},
{
"name": "date_to",
"in": "query",
"required": false,
"description": "Filter events up to this date (inclusive, ISO format e.g. `2025-12-31`). Must be after `date_from` if provided.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Number of results per page. Default `20`, maximum `100`.",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page number.",
"schema": {
"type": "integer"
}
},
{
"name": "sort_by",
"in": "query",
"required": false,
"description": "Column to sort by. Possible values: `occured_at`, `id`, `event`. Default `occured_at`.",
"schema": {
"type": "string"
}
},
{
"name": "sort_dir",
"in": "query",
"required": false,
"description": "Sort direction. Possible values: `asc`, `desc`. Default `desc`.",
"schema": {
"type": "string"
}
},
{
"name": "campaignId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"campaign_log": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"campaign_id": {
"type": "integer"
},
"autoresponder_id": {},
"action_id": {},
"event": {
"type": "string"
},
"msg": {},
"url": {},
"email": {
"type": "string"
},
"occured_at": {
"type": "string"
},
"mail_name": {}
}
}
},
"current_page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"total": {
"type": "integer"
},
"last_page": {
"type": "integer"
}
}
},
"example": {
"campaign_log": [
{
"id": 5678,
"campaign_id": 1,
"autoresponder_id": null,
"action_id": null,
"event": "open",
"msg": null,
"url": null,
"email": "foo@bar.cz",
"occured_at": "2025-03-15T14:30:00.000000Z",
"mail_name": null
},
{
"id": 5677,
"campaign_id": 1,
"autoresponder_id": null,
"action_id": null,
"event": "click",
"msg": null,
"url": "https://example.com/offer",
"email": "foo@bar.cz",
"occured_at": "2025-03-15T14:25:00.000000Z",
"mail_name": null
}
],
"current_page": 1,
"per_page": 10,
"total": 2,
"last_page": 1
}
}
}
}
}
}
},
"/coupons/import": {
"post": {
"operationId": "couponsImport",
"summary": "Import discount coupons",
"description": "Import discount coupons into a default or specific folder.",
"tags": [
"Discount coupons"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"folderId": {
"type": "integer",
"description": "Folder ID. If not provided, coupons are imported into the default folder."
},
"codes": {
"type": "array",
"description": "Array of coupon code strings.",
"items": {}
},
"valid_until": {
"type": "string",
"description": "Expiration date in `YYYY-MM-DD` format."
},
"update_existing": {
"type": "boolean",
"description": "Update existing coupons if they already exist.",
"default": false
}
},
"required": [
"codes"
]
},
"example": {
"folderId": 1,
"codes": [
"kod1",
"kod2",
"kod3",
"kod4"
],
"valid_until": "2025-12-31",
"update_existing": false
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"imported": {
"type": "integer"
},
"duplicated": {
"type": "integer"
},
"totalCount": {
"type": "integer"
}
}
},
"example": {
"imported": 4,
"duplicated": 0,
"totalCount": 4
}
}
}
}
}
}
},
"/coupons/delete": {
"delete": {
"operationId": "couponsDelete",
"summary": "Delete discount coupons",
"description": "Delete discount coupons from a default or specific folder.",
"tags": [
"Discount coupons"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"folderId": {
"type": "integer",
"description": "Folder ID. If not provided, coupons are deleted from the default folder."
},
"codes": {
"type": "array",
"description": "Array of coupon code strings to delete.",
"items": {}
}
},
"required": [
"codes"
]
},
"example": {
"folderId": 1,
"codes": [
"code1",
"code2",
"code3",
"code4"
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "integer"
},
"invalid": {
"type": "integer"
}
}
},
"example": {
"deleted": 4,
"invalid": 0
}
}
}
}
}
}
},
"/domains": {
"get": {
"operationId": "domainsListAll",
"summary": "List all domains",
"description": "Retrieve all domains in your account.",
"tags": [
"Domains"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"valid": {
"type": "boolean"
},
"blocked": {
"type": "boolean"
}
}
}
},
"example": [
{
"name": "foo.cz",
"valid": true,
"blocked": false
},
{
"name": "bar.cz",
"valid": false,
"blocked": false
}
]
}
}
}
}
},
"post": {
"operationId": "domainsCreate",
"summary": "Create a new domain",
"description": "Add a new domain to your account.",
"tags": [
"Domains"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Domain name."
}
},
"required": [
"name"
]
},
"example": {
"name": "newdomain.cz"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"valid": {
"type": "integer"
}
}
},
"example": {
"name": "newdomain.cz",
"valid": 0
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "Invalid URL address"
}
}
}
}
}
}
},
"/domains/{domain}": {
"delete": {
"operationId": "domainsDelete",
"summary": "Delete a domain",
"description": "Remove a domain from your account.",
"tags": [
"Domains"
],
"parameters": [
{
"name": "domain",
"in": "path",
"required": true,
"description": "Domain name.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"valid": {
"type": "boolean"
},
"blocked": {
"type": "boolean"
}
}
},
"example": {
"name": "foo.cz",
"valid": true,
"blocked": false
}
}
}
}
}
}
},
"/feeds": {
"get": {
"operationId": "feedsListAll",
"summary": "List all feeds",
"description": "Retrieve all product feeds in your account. Use the `id` values as `feed_id` for the refresh endpoint. Data feeds are not included.",
"tags": [
"Feeds"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"feeds": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"type": {
"type": "string"
},
"url": {
"type": "string"
},
"products_count": {
"type": "integer",
"nullable": true
},
"error": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
}
}
}
},
"example": {
"feeds": [
{
"id": 1,
"type": "heureka",
"url": "https://www.example.com/feed.xml",
"products_count": 250,
"error": null,
"created_at": "2026-08-01 10:00:00",
"updated_at": "2026-08-31 06:30:00"
}
]
}
}
}
}
}
}
},
"/feeds/{feed_id}/refresh": {
"get": {
"operationId": "feedsRefreshProduct",
"summary": "Refresh product feed",
"description": "Trigger a refresh of a product feed.",
"tags": [
"Feeds"
],
"parameters": [
{
"name": "feed_id",
"in": "path",
"required": true,
"description": "ID of the product feed.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"example": {
"message": "Your feed is being refreshed"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "string"
}
}
},
"example": {
"errors": "Account must be marketer+ tariff"
}
}
}
}
}
}
},
"/data-feeds/{feed_id}/refresh": {
"get": {
"operationId": "feedsRefreshData",
"summary": "Refresh data feed",
"description": "Trigger a refresh of a data feed.",
"tags": [
"Feeds"
],
"parameters": [
{
"name": "feed_id",
"in": "path",
"required": true,
"description": "ID of the data feed.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"example": {
"message": "Your feed is being refreshed"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "string"
}
}
},
"example": {
"errors": "Account must be marketer+ tariff"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "string"
}
}
},
"example": {
"errors": "Feed can be refreshed just once per hour"
}
}
}
}
}
}
},
"/lists": {
"get": {
"operationId": "listsListAll",
"summary": "View all lists",
"description": "Retrieve all subscriber lists in your account.",
"tags": [
"Lists"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"from_name": {
"type": "string"
},
"from_email": {
"type": "string"
},
"reply_to": {
"type": "string"
},
"sub_success_page": {},
"sub_confirmed_page": {},
"unsub_page": {},
"double_optin": {},
"conf_subject": {},
"conf_message": {}
}
}
},
"example": [
{
"id": 29,
"name": "New list name",
"from_name": "Ecomailapp.cz",
"from_email": "test@ecomailapp.cz",
"reply_to": "support@ecomail.cz",
"sub_success_page": null,
"sub_confirmed_page": null,
"unsub_page": null,
"double_optin": null,
"conf_subject": null,
"conf_message": null
}
]
}
}
}
}
},
"post": {
"operationId": "listsAddNew",
"summary": "Add new list",
"description": "Create a new subscriber list in your account.",
"tags": [
"Lists"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "List name."
},
"from_name": {
"type": "string",
"description": "Sender name used in emails sent from this list."
},
"from_email": {
"type": "string",
"description": "Sender email address used in emails sent from this list."
},
"reply_to": {
"type": "string",
"description": "Reply-to email address."
},
"sub_success_page": {
"type": "string",
"description": "URL to redirect to after submitting a sign-up form."
},
"sub_confirmed_page": {
"type": "string",
"description": "URL to redirect to after confirming a sign-up email."
},
"unsub_page": {
"type": "string",
"description": "URL to redirect to after unsubscribing from the list."
},
"double_optin": {
"type": "boolean",
"description": "Whether sign-up confirmation (double opt-in) is required."
},
"conf_subject": {
"type": "string",
"description": "Subject line of the confirmation email."
},
"conf_message": {
"type": "string",
"description": "HTML content of the confirmation email."
}
},
"required": [
"name"
]
},
"example": {
"name": "New list name",
"from_name": "Ecomailapp.cz",
"from_email": "test@ecomailapp.cz",
"reply_to": "support@ecomail.cz"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"id": {
"type": "integer"
}
}
},
"example": {
"name": "New list name",
"id": 2
}
}
}
}
}
}
},
"/lists/{list_id}": {
"get": {
"operationId": "listsShow",
"summary": "Show list detail",
"description": "Retrieve detailed information about a specific list, including custom fields, groups, segments, and subscriber counts.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"list": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"from_name": {
"type": "string"
},
"from_email": {
"type": "string"
},
"reply_to": {
"type": "string"
},
"sub_success_page": {},
"sub_confirmed_page": {
"type": "string"
},
"unsub_page": {},
"double_optin": {
"type": "boolean"
},
"conf_subject": {
"type": "string"
},
"conf_message": {
"type": "string"
},
"custom_fields": {
"type": "object",
"properties": {
"date1": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"size": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
},
"groups": {
"type": "object",
"properties": {
"grp_5e83080ebb988": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"category": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"id": {
"type": "string"
}
}
}
},
"id": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
},
"segments": {
"type": "object",
"properties": {
"5c36008811e45": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"id": {
"type": "string"
}
}
}
}
},
"active_subscribers": {
"type": "integer"
},
"created": {
"type": "string"
}
}
},
"subscribers": {
"type": "object",
"properties": {
"unknown": {
"type": "integer"
},
"subscribed": {
"type": "integer"
},
"unsubscribed": {
"type": "integer"
},
"soft_bounced": {
"type": "integer"
},
"hard_bounced": {
"type": "integer"
},
"complained": {
"type": "integer"
},
"unconfirmed": {
"type": "integer"
}
}
}
}
},
"example": {
"list": {
"id": "1",
"name": "List Name",
"from_name": "Sender Name",
"from_email": "sender@example.com",
"reply_to": "reply@example.com",
"sub_success_page": null,
"sub_confirmed_page": "https://www.example.com/confirm?email=*|EMAIL|*",
"unsub_page": null,
"double_optin": true,
"conf_subject": "Confirmation Subject",
"conf_message": "Please confirm your subscription: *|SUBCONFIRM|*",
"custom_fields": {
"date1": {
"type": "string",
"name": "Date Field"
},
"size": {
"type": "int",
"name": "Size Field"
}
},
"groups": {
"grp_5e83080ebb988": {
"name": "Group 1",
"category": [
{
"name": "Category A",
"id": "plnQNPzCz"
}
],
"id": "grp_1",
"type": "select"
}
},
"segments": {
"5c36008811e45": {
"name": "Segment 1",
"id": "5c36008811e45"
}
},
"active_subscribers": 100,
"created": "26.6.2018"
},
"subscribers": {
"unknown": 0,
"subscribed": 375,
"unsubscribed": 143,
"soft_bounced": 9,
"hard_bounced": 11,
"complained": 1,
"unconfirmed": 25
}
}
}
}
}
}
},
"put": {
"operationId": "listsUpdate",
"summary": "Update list",
"description": "Update an existing subscriber list.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "List name."
},
"from_name": {
"type": "string",
"description": "Sender name used in emails sent from this list."
},
"from_email": {
"type": "string",
"description": "Sender email address used in emails sent from this list."
},
"reply_to": {
"type": "string",
"description": "Reply-to email address."
},
"sub_success_page": {
"type": "string",
"description": "URL to redirect to after submitting a sign-up form."
},
"sub_confirmed_page": {
"type": "string",
"description": "URL to redirect to after confirming a sign-up email."
},
"unsub_page": {
"type": "string",
"description": "URL to redirect to after unsubscribing from the list."
},
"double_optin": {
"type": "boolean",
"description": "Whether sign-up confirmation (double opt-in) is required."
},
"conf_subject": {
"type": "string",
"description": "Subject line of the confirmation email."
},
"conf_message": {
"type": "string",
"description": "HTML content of the confirmation email."
}
},
"required": [
"name"
]
},
"example": {
"name": "Updated name",
"from_name": "Ecomailapp.cz",
"from_email": "test@ecomailapp.cz",
"reply_to": "support@ecomail.cz"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"from_name": {
"type": "string"
},
"from_email": {
"type": "string"
},
"reply_to": {
"type": "string"
},
"sub_success_page": {},
"sub_confirmed_page": {},
"unsub_page": {},
"double_optin": {},
"conf_subject": {},
"conf_message": {}
}
},
"example": {
"id": 2,
"name": "Updated name",
"from_name": "Ecomailapp.cz",
"from_email": "test@ecomailapp.cz",
"reply_to": "support@ecomail.cz",
"sub_success_page": null,
"sub_confirmed_page": null,
"unsub_page": null,
"double_optin": null,
"conf_subject": null,
"conf_message": null
}
}
}
}
}
}
},
"/lists/{list_id}/segments": {
"get": {
"operationId": "listsGetSegments",
"summary": "Get segments",
"description": "Retrieve all segments created in a specific list.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"segments": {
"type": "object",
"properties": {
"5c36008811e45": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"id": {
"type": "string"
},
"count": {
"type": "integer"
}
}
},
"5cbf2405a77ce": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"id": {
"type": "string"
},
"count": {
"type": "integer"
}
}
}
}
}
}
},
"example": {
"segments": {
"5c36008811e45": {
"name": "Segment 1",
"id": "5c36008811e45",
"count": 860
},
"5cbf2405a77ce": {
"name": "Segment 2",
"id": "5cbf2405a77ce",
"count": 540
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"example": {
"message": "Not Found!"
}
}
}
}
}
}
},
"/lists/{list_id}/subscribers": {
"get": {
"operationId": "listsGetSubscribers",
"summary": "Get subscribers",
"description": "Retrieve a paginated list of subscribers from a specific list.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page index.",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Filter by status: `unsubscribed`, `not_confirmed`, `bounced`, `complained`.",
"schema": {
"type": "string",
"default": "subscribed"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Number of subscribers per page, up to 5000. We recommend keeping this at a lower number (e.g. 4000) depending on the amount of data each subscriber has.",
"schema": {
"type": "integer",
"default": 20
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"current_page": {
"type": "integer"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"list_id": {
"type": "integer"
},
"email": {
"type": "string"
},
"status": {
"type": "integer"
},
"subscribed_at": {
"type": "string"
},
"unsubscribed_at": {},
"custom_fields": {
"type": "array",
"items": {}
},
"groups": {},
"source": {
"type": "string"
},
"subscriber": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"surname": {
"type": "string"
},
"email": {
"type": "string"
},
"gender": {
"type": "string"
},
"company": {},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"phone": {}
}
}
}
}
},
"per_page": {
"type": "integer"
},
"total": {
"type": "integer"
}
}
},
"example": {
"current_page": 1,
"data": [
{
"list_id": 75,
"email": "some1@contact.com",
"status": 1,
"subscribed_at": "2024-05-10T12:29:07.000000Z",
"unsubscribed_at": null,
"custom_fields": [],
"groups": null,
"source": "app",
"subscriber": {
"id": 1158595,
"name": "Foo",
"surname": "Bar",
"email": "some1@contact.com",
"gender": "male",
"company": null,
"city": "City",
"country": "CZ",
"phone": null
}
}
],
"per_page": 20,
"total": 2
}
}
}
}
}
}
},
"/lists/{list_id}/subscriber/{email}": {
"get": {
"operationId": "listsGetSubscriber",
"summary": "Get subscriber from list",
"description": "Retrieve a specific subscriber from a list by their email address.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
},
{
"name": "email",
"in": "path",
"required": true,
"description": "Email of the subscriber.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscriber": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"surname": {
"type": "string"
},
"email": {
"type": "string"
},
"company": {
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"phone": {
"type": "string"
},
"gender": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"rating": {
"type": "number"
},
"list_id": {
"type": "integer"
},
"status": {
"type": "integer"
},
"subscribed_at": {
"type": "string"
},
"custom_fields": {
"type": "object",
"properties": {
"field1": {
"type": "string"
}
}
},
"groups": {
"type": "object",
"properties": {
"grp_60ddec46df422": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
},
"example": {
"subscriber": {
"id": 12345,
"name": "John",
"surname": "Doe",
"email": "john.doe@example.com",
"company": "Acme Corporation",
"city": "New York",
"country": "US",
"phone": "+1 (555) 123-4567",
"gender": "male",
"tags": [
"tag1",
"tag2"
],
"rating": 4.5,
"list_id": 42,
"status": 1,
"subscribed_at": "2022-01-01T12:00:00.000000Z",
"custom_fields": {
"field1": "Value 1"
},
"groups": {
"grp_60ddec46df422": [
"a",
"b"
]
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"example": {
"errors": [
"Subscriber with email foo@bar.cz was not found in the list"
]
}
}
}
}
}
}
},
"/lists/{list_id}/subscriber-by-phone/{phone}": {
"get": {
"operationId": "listsGetSubscriberByPhone",
"summary": "Get subscriber by phone",
"description": "Retrieve a specific subscriber from a list by their phone number.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
},
{
"name": "phone",
"in": "path",
"required": true,
"description": "Phone number of the subscriber. Must be a valid international phone number.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscriber": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"list_id": {
"type": "integer"
},
"email": {
"type": "string"
},
"status": {
"type": "integer"
},
"subscribed_at": {
"type": "string"
},
"custom_fields": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
}
},
"source": {
"type": "string"
}
}
}
}
},
"example": {
"subscriber": {
"id": 123456,
"list_id": 789,
"email": "foo@bar.cz",
"status": 1,
"subscribed_at": "2023-01-01T00:00:00.000000Z",
"custom_fields": {
"id": "123"
},
"source": "API"
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"phone": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"example": {
"errors": {
"phone": [
"Invalid phone number"
]
}
}
}
}
}
}
}
},
"/lists/{list_id}/subscribe": {
"post": {
"operationId": "listsSubscribe",
"summary": "Add new subscriber to list",
"description": "Subscribe a new contact to a specific list.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscriber_data": {
"type": "object",
"description": "Information about the subscriber.",
"properties": {
"email": {
"type": "string",
"description": "Subscriber's email address."
},
"name": {
"type": "string",
"description": "First name."
},
"surname": {
"type": "string",
"description": "Last name."
},
"gender": {
"type": "string",
"description": "Gender. Must be `male` or `female`."
},
"status": {
"type": "integer",
"description": "Subscriber status. `1` = subscribed, `2` = unsubscribed, `4` = hard bounce, `5` = spam complaint, `6` = unconfirmed."
},
"company": {
"type": "string",
"description": "Company name."
},
"city": {
"type": "string",
"description": "City."
},
"street": {
"type": "string",
"description": "Street address."
},
"zip": {
"type": "string",
"description": "ZIP or postal code."
},
"country": {
"type": "string",
"description": "Country code."
},
"phone": {
"type": "string",
"description": "Phone number."
},
"pretitle": {
"type": "string",
"description": "Pre-title (e.g. Mr., Mrs.)."
},
"surtitle": {
"type": "string",
"description": "Post-nominal title (e.g. PhD)."
},
"birthday": {
"type": "string",
"description": "Birthday in `YYYY-MM-DD` format."
},
"nameday": {
"type": "string",
"description": "Name day in `MM-DD` format."
},
"source": {
"type": "string",
"description": "Source of the subscriber."
},
"custom_fields": {
"type": "object",
"description": "Custom field values. Limited to 5000 characters total. Reserved system merge tags are ignored. If a field doesn't exist, a new field is created. Supported types: `string`, `date`, `json`, `int`, `float`, `url`. Float precision is limited to 3 decimal places. Keys are case-insensitive — they are trimmed and lowercased on input, so `SHOP`, `shop` and ` Shop ` are treated as the same field. Two keys that differ only in case or whitespace in the same request are rejected as duplicates."
},
"tags": {
"type": "array",
"description": "Subscriber tags. Limited to 2000 characters total and 50 characters per tag. Content overwrites current tags. Only updates if the parameter is present and `update_existing` is `true`. To clear all tags, send an empty array.",
"items": {}
},
"groups": {
"type": "object",
"description": "Group assignments. Overwrites current values. To keep existing selections, send the current values together with new ones."
}
},
"required": [
"email"
]
},
"trigger_autoresponders": {
"type": "boolean",
"description": "Trigger automations when the subscriber is added.",
"default": false
},
"trigger_notification": {
"type": "boolean",
"description": "Send a notification about the new subscriber if configured in list settings.",
"default": false
},
"update_existing": {
"type": "boolean",
"description": "Update the subscriber if they already exist in the list.",
"default": false
},
"skip_confirmation": {
"type": "boolean",
"description": "Skip double opt-in confirmation. If `false`, the system sends a double opt-in email and the subscriber is added with status `6` (unconfirmed).",
"default": false
},
"resubscribe": {
"type": "boolean",
"description": "Force resubscribe if the subscriber was previously unsubscribed (status `2`). If `status` is provided in `subscriber_data`, it takes precedence. For resubscribe to work, the status must be `1`.",
"default": false
}
},
"required": [
"subscriber_data"
]
},
"example": {
"subscriber_data": {
"name": "Jan",
"surname": "Novak",
"email": "jan@novak.cz",
"gender": "male",
"company": "Company name",
"city": "Praha",
"country": "CZ",
"phone": "+420777888999",
"birthday": "1984-01-01",
"custom_fields": {
"shop": "myshop.cz",
"birthday": {
"value": "2022-01-20",
"type": "date"
}
},
"tags": [
"tags"
],
"groups": {
"grp_5a145ee75780f": [
"Category 1",
"Category 2"
]
}
},
"trigger_autoresponders": false,
"update_existing": false,
"resubscribe": false
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"surname": {
"type": "string"
},
"email": {
"type": "string"
},
"gender": {},
"bounce_soft": {
"type": "integer"
},
"bounced_hard": {
"type": "integer"
},
"bounce_message": {},
"inserted_at": {
"type": "string"
},
"already_subscribed": {
"type": "boolean"
}
}
},
"example": {
"id": 259471,
"name": "Jan",
"surname": "Novak",
"email": "jan@novak.cz",
"gender": null,
"bounce_soft": 0,
"bounced_hard": 0,
"bounce_message": null,
"inserted_at": "2015-01-21 10:50:04",
"already_subscribed": true
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"subscriber_data.custom_fields": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"example": {
"success": false,
"message": "Validation errors",
"data": {
"subscriber_data.custom_fields": [
"Custom fields must be an array with unique keys (case-insensitive)",
"Subscriber custom fields must be an array with max 5000 bytes"
]
}
}
}
}
}
}
}
},
"/lists/{list_id}/subscribe-bulk": {
"post": {
"operationId": "listsSubscribeBulk",
"summary": "Add bulk subscribers",
"description": "Subscribe multiple contacts to a specific list in a single request.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscriber_data": {
"type": "array",
"description": "Array of subscriber objects. Limited to 3000 subscribers per call — subscribers above the limit are ignored.",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of the subscriber."
},
"status": {
"type": "integer",
"description": "Subscriber status. `1` = subscribed, `2` = unsubscribed, `4` = hard bounce.",
"default": 1
}
},
"required": [
"email"
]
}
},
"update_existing": {
"type": "boolean",
"description": "Update subscribers that already exist in the list.",
"default": true
},
"resubscribe": {
"type": "boolean",
"description": "Force resubscribe if the subscriber was previously unsubscribed.",
"default": false
},
"trigger_autoresponders": {
"type": "boolean",
"description": "Trigger automations when subscribers are added.",
"default": false
}
},
"required": [
"subscriber_data"
]
},
"example": {
"subscriber_data": [
{
"name": "Foo",
"surname": "Bar",
"email": "foo@bar.cz",
"custom_fields": {
"category": "customer"
}
},
{
"name": "Foo 2",
"email": "foo2@bar.cz"
}
],
"update_existing": true,
"resubscribe": false,
"trigger_autoresponders": false
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"inserts": {
"type": "integer"
}
}
},
"example": {
"inserts": 2
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"subscriber_data.0": {
"type": "object",
"properties": {
"email": {
"type": "array",
"items": {
"type": "string"
}
},
"custom_fields": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"subscriber_data.1": {
"type": "object",
"properties": {
"email": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
},
"example": {
"errors": {
"subscriber_data.0": {
"email": [
"Invalid email address"
],
"custom_fields": [
"Custom fields must be an array with unique keys (case-insensitive)",
"Subscriber custom fields must be an array with max 5000 bytes"
]
},
"subscriber_data.1": {
"email": [
"Invalid email address"
]
}
}
}
}
}
}
}
}
},
"/lists/{list_id}/unsubscribe": {
"delete": {
"operationId": "listsUnsubscribe",
"summary": "Unsubscribe subscriber from list",
"description": "Unsubscribe a subscriber from a specific list.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of the subscriber to unsubscribe."
}
},
"required": [
"email"
]
},
"example": {
"email": "foo@bar.cz"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"list_id": {
"type": "integer"
},
"email": {
"type": "string"
},
"status": {
"type": "integer"
},
"subscribed_at": {
"type": "string"
},
"unsubscribed_at": {
"type": "string"
},
"custom_fields": {
"type": "object",
"properties": {
"mergetag": {
"type": "string"
}
}
},
"source": {
"type": "string"
}
}
},
"example": {
"id": 4,
"list_id": 1,
"email": "foo@bar.cz",
"status": 2,
"subscribed_at": "2024-11-27T11:18:00.000000Z",
"unsubscribed_at": "2024-11-27T11:39:16.000000Z",
"custom_fields": {
"mergetag": "content"
},
"source": "api"
}
}
}
}
}
}
},
"/lists/{list_id}/update-subscriber": {
"put": {
"operationId": "listsUpdateSubscriber",
"summary": "Update subscriber",
"description": "Update an existing subscriber in a specific list.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of the subscriber to update."
},
"subscriber_data": {
"type": "object",
"description": "Updated subscriber information.",
"properties": {
"name": {
"type": "string",
"description": "First name."
},
"surname": {
"type": "string",
"description": "Last name."
},
"gender": {
"type": "string",
"description": "Gender. Must be `male` or `female`."
},
"company": {
"type": "string",
"description": "Company name."
},
"city": {
"type": "string",
"description": "City."
},
"street": {
"type": "string",
"description": "Street address."
},
"zip": {
"type": "string",
"description": "ZIP or postal code."
},
"country": {
"type": "string",
"description": "Country code."
},
"phone": {
"type": "string",
"description": "Phone number."
},
"pretitle": {
"type": "string",
"description": "Pre-title (e.g. Mr., Mrs.)."
},
"surtitle": {
"type": "string",
"description": "Post-nominal title (e.g. PhD)."
},
"birthday": {
"type": "string",
"description": "Birthday in `YYYY-MM-DD` format."
},
"nameday": {
"type": "string",
"description": "Name day in `MM-DD` format."
},
"source": {
"type": "string",
"description": "Source of the subscriber."
},
"custom_fields": {
"type": "object",
"description": "Custom field values. Limited to 5000 characters total. Keys are case-insensitive — they are trimmed and lowercased on input, so `SHOP`, `shop` and ` Shop ` are treated as the same field. Two keys that differ only in case or whitespace in the same request are rejected as duplicates."
},
"tags": {
"type": "array",
"description": "Subscriber tags. Limited to 2000 characters total and 50 characters per tag. Content overwrites current tags.",
"items": {}
},
"groups": {
"type": "object",
"description": "Group assignments. Overwrites current values."
}
}
}
},
"required": [
"email"
]
},
"example": {
"email": "foo@bar.cz",
"subscriber_data": {
"name": "Jan",
"surname": "Novak",
"gender": "male",
"company": "Company name",
"city": "Praha",
"custom_fields": {
"shop": "myshop.cz"
},
"tags": [
"tags"
],
"groups": {
"grp_5a145ee75780f": [
"Category 1",
"Category 2"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"surname": {
"type": "string"
},
"email": {
"type": "string"
},
"gender": {
"type": "string"
},
"bounce_soft": {
"type": "integer"
},
"bounce_hard": {},
"bounce_message": {},
"inserted_at": {
"type": "string"
}
}
},
"example": {
"id": 12345,
"name": "Jan",
"surname": "Novak",
"email": "foo@bar.cz",
"gender": "male",
"bounce_soft": 0,
"bounce_hard": null,
"bounce_message": null,
"inserted_at": "2022-11-15 13:59:21"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"subscriber_data.custom_fields": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"example": {
"errors": {
"subscriber_data.custom_fields": [
"Custom fields must be an array with unique keys (case-insensitive)",
"Subscriber custom fields must be an array with max 5000 bytes"
]
}
}
}
}
}
}
}
},
"/lists/{list_id}/update-subscribers-bulk": {
"put": {
"operationId": "listsUpdateSubscribersBulk",
"summary": "Update bulk subscribers",
"description": "Update multiple existing subscribers in a specific list in a single request.",
"tags": [
"Lists"
],
"parameters": [
{
"name": "list_id",
"in": "path",
"required": true,
"description": "ID of the list.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscriber_data": {
"type": "array",
"description": "Array of subscriber objects to update. Limited to 3000 subscribers per call.",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of the subscriber to update."
},
"name": {
"type": "string",
"description": "First name."
},
"surname": {
"type": "string",
"description": "Last name."
},
"status": {
"type": "integer",
"description": "Subscriber status. `1` = subscribed, `2` = unsubscribed, `4` = hard bounce."
},
"custom_fields": {
"type": "object",
"description": "Custom field values. Limited to 5000 characters total. Keys are case-insensitive — they are trimmed and lowercased on input, so `SHOP`, `shop` and ` Shop ` are treated as the same field. Two keys that differ only in case or whitespace within the same subscriber are rejected as duplicates."
},
"tags": {
"type": "array",
"description": "Subscriber tags. Limited to 2000 characters total and 50 characters per tag. Content overwrites current tags.",
"items": {}
}
},
"required": [
"email"
]
}
},
"allow_resubscribe": {
"type": "boolean",
"description": "Allow resubscribing previously unsubscribed contacts when `status` is set to `1`.",
"default": false
}
},
"required": [
"subscriber_data"
]
},
"example": {
"subscriber_data": [
{
"email": "foo@bar.cz",
"name": "Jan",
"surname": "Novak",
"custom_fields": {
"shop": "myshop.cz"
},
"tags": [
"vip"
]
},
{
"email": "foo2@bar.cz",
"name": "Jana"
}
],
"allow_resubscribe": false
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"updates": {
"type": "integer"
}
}
},
"example": {
"updates": 2
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"subscriber_data.0.email": {
"type": "array",
"items": {
"type": "string"
}
},
"subscriber_data.0.custom_fields": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"example": {
"errors": {
"subscriber_data.0.email": [
"Invalid email address"
],
"subscriber_data.0.custom_fields": [
"Custom fields must be an array with unique keys (case-insensitive)",
"Subscriber custom fields must be an array with max 5000 bytes"
]
}
}
}
}
}
}
}
},
"/recommenders": {
"get": {
"operationId": "recommendersListAll",
"summary": "List all recommenders",
"description": "Retrieve all Spark recommenders configured for your account.",
"tags": [
"Recommenders"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recommender_id": {
"type": "string"
},
"feed_id": {
"type": "integer"
},
"shop_id": {
"type": "string"
},
"last_trained_timestamp": {
"type": "integer"
},
"status": {
"type": "string"
},
"settings": {
"type": "object",
"properties": {
"filtered_products": {
"type": "array",
"items": {}
},
"filtered_categories": {
"type": "array",
"items": {}
},
"included_months": {
"type": "array",
"items": {}
}
}
},
"sequence_number": {
"type": "integer"
},
"name": {
"type": "string"
}
}
}
},
"example": [
{
"recommender_id": "6789abc123def",
"feed_id": 1,
"shop_id": "my-shop",
"last_trained_timestamp": 1710000000,
"status": "ready",
"settings": {
"filtered_products": [],
"filtered_categories": [],
"included_months": []
},
"sequence_number": 1,
"name": "Christmas 2026"
}
]
}
}
}
}
},
"post": {
"operationId": "recommendersCreate",
"summary": "Create recommender",
"description": "Create a new Spark recommender for a specific shop and product feed. Training starts automatically after creation.",
"tags": [
"Recommenders"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"shop_id": {
"type": "string",
"description": "The shop (e-commerce platform) identifier. Max 64 characters, allowed characters: letters, digits, `.`, `_`, `-`."
},
"feed_id": {
"type": "integer",
"description": "The product feed ID to use for recommendations."
},
"name": {
"type": "string",
"description": "Optional human-readable name of the recommender. Max 191 characters."
},
"filtered_products": {
"type": "string",
"description": "Optional list of product identifiers (SKUs) to exclude from the recommendations. Max 1000 items, each unique and max 255 characters. Omit the field for no product filter."
},
"filtered_categories": {
"type": "string",
"description": "Optional list of category names to exclude from the recommendations. Max 1000 items, each unique and max 255 characters. Omit the field for no category filter."
},
"included_months": {
"type": "string",
"description": "Optional list of calendar month numbers (`1`–`12`) that restrict which purchase history is used for training. Values must be unique, max 12 items. Omit the field to use the full purchase history."
}
},
"required": [
"shop_id",
"feed_id"
]
},
"example": {
"shop_id": "my-shop",
"feed_id": 1,
"name": "Christmas 2026",
"filtered_products": [
"SKU-A",
"SKU-B"
],
"filtered_categories": [
"Sale"
],
"included_months": [
11,
12
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recommender_id": {
"type": "string"
},
"feed_id": {
"type": "integer"
},
"shop_id": {
"type": "string"
},
"last_trained_timestamp": {},
"status": {
"type": "string"
},
"settings": {
"type": "object",
"properties": {
"filtered_products": {
"type": "array",
"items": {
"type": "string"
}
},
"filtered_categories": {
"type": "array",
"items": {
"type": "string"
}
},
"included_months": {
"type": "array",
"items": {
"type": "integer"
}
}
}
},
"sequence_number": {
"type": "integer"
},
"name": {
"type": "string"
}
}
}
},
"example": [
{
"recommender_id": "6789abc123def",
"feed_id": 1,
"shop_id": "my-shop",
"last_trained_timestamp": null,
"status": "created",
"settings": {
"filtered_products": [
"SKU-A",
"SKU-B"
],
"filtered_categories": [
"Sale"
],
"included_months": [
11,
12
]
},
"sequence_number": 1,
"name": "Christmas 2026"
}
]
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"recommender": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"example": {
"errors": {
"recommender": [
"There is not enough purchase data to train a recommender yet."
]
}
}
}
}
}
}
}
},
"/recommenders/{recommender_id}": {
"get": {
"operationId": "recommendersShow",
"summary": "Get recommender",
"description": "Retrieve a single Spark recommender by its ID.",
"tags": [
"Recommenders"
],
"parameters": [
{
"name": "recommender_id",
"in": "path",
"required": true,
"description": "The unique identifier of the recommender to retrieve.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"recommender_id": {
"type": "string"
},
"feed_id": {
"type": "integer"
},
"shop_id": {
"type": "string"
},
"last_trained_timestamp": {
"type": "integer"
},
"status": {
"type": "string"
},
"settings": {
"type": "object",
"properties": {
"filtered_products": {
"type": "array",
"items": {
"type": "string"
}
},
"filtered_categories": {
"type": "array",
"items": {
"type": "string"
}
},
"included_months": {
"type": "array",
"items": {
"type": "integer"
}
}
}
},
"sequence_number": {
"type": "integer"
},
"name": {
"type": "string"
}
}
},
"example": {
"recommender_id": "6789abc123def",
"feed_id": 1,
"shop_id": "my-shop",
"last_trained_timestamp": 1710000000,
"status": "ready",
"settings": {
"filtered_products": [
"SKU-A",
"SKU-B"
],
"filtered_categories": [
"Sale"
],
"included_months": [
11,
12
]
},
"sequence_number": 1,
"name": "Christmas 2026"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"example": {
"message": "Recommender not found."
}
}
}
}
}
},
"put": {
"operationId": "recommendersUpdate",
"summary": "Update recommender",
"description": "Update the name and settings (filters) of an existing Spark recommender. Returns the updated list of recommenders.",
"tags": [
"Recommenders"
],
"parameters": [
{
"name": "recommender_id",
"in": "path",
"required": true,
"description": "The unique identifier of the recommender to update.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Optional human-readable name of the recommender. Max 191 characters."
},
"filtered_products": {
"type": "string",
"description": "List of product identifiers (SKUs) to exclude from the recommendations. Max 1000 items, each unique and max 255 characters. Omit the field for no product filter."
},
"filtered_categories": {
"type": "string",
"description": "List of category names to exclude from the recommendations. Max 1000 items, each unique and max 255 characters. Omit the field for no category filter."
},
"included_months": {
"type": "string",
"description": "List of calendar month numbers (`1`–`12`) that restrict which purchase history is used for training. Values must be unique, max 12 items. Omit the field to use the full purchase history."
}
}
},
"example": {
"name": "Christmas 2026",
"filtered_products": [
"SKU-A"
],
"filtered_categories": [
"Sale"
],
"included_months": [
11,
12
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recommender_id": {
"type": "string"
},
"feed_id": {
"type": "integer"
},
"shop_id": {
"type": "string"
},
"last_trained_timestamp": {
"type": "integer"
},
"status": {
"type": "string"
},
"settings": {
"type": "object",
"properties": {
"filtered_products": {
"type": "array",
"items": {
"type": "string"
}
},
"filtered_categories": {
"type": "array",
"items": {
"type": "string"
}
},
"included_months": {
"type": "array",
"items": {
"type": "integer"
}
}
}
},
"sequence_number": {
"type": "integer"
},
"name": {
"type": "string"
}
}
}
},
"example": [
{
"recommender_id": "6789abc123def",
"feed_id": 1,
"shop_id": "my-shop",
"last_trained_timestamp": 1710000000,
"status": "ready",
"settings": {
"filtered_products": [
"SKU-A"
],
"filtered_categories": [
"Sale"
],
"included_months": [
11,
12
]
},
"sequence_number": 1,
"name": "Christmas 2026"
}
]
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"example": {
"message": "Recommender not found."
}
}
}
}
}
},
"delete": {
"operationId": "recommendersDelete",
"summary": "Delete recommender",
"description": "Remove a Spark recommender by its ID. Returns the updated list of remaining recommenders.",
"tags": [
"Recommenders"
],
"parameters": [
{
"name": "recommender_id",
"in": "path",
"required": true,
"description": "The unique identifier of the recommender to delete.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recommender_id": {
"type": "string"
},
"feed_id": {
"type": "integer"
},
"shop_id": {
"type": "string"
},
"last_trained_timestamp": {
"type": "integer"
},
"status": {
"type": "string"
},
"settings": {
"type": "object",
"properties": {
"filtered_products": {
"type": "array",
"items": {}
},
"filtered_categories": {
"type": "array",
"items": {}
},
"included_months": {
"type": "array",
"items": {}
}
}
},
"sequence_number": {
"type": "integer"
},
"name": {}
}
}
},
"example": [
{
"recommender_id": "abcd1234ef5678",
"feed_id": 2,
"shop_id": "my-shop",
"last_trained_timestamp": 1710000000,
"status": "ready",
"settings": {
"filtered_products": [],
"filtered_categories": [],
"included_months": []
},
"sequence_number": 2,
"name": null
}
]
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"example": {
"message": "Recommender not found."
}
}
}
}
}
}
},
"/search": {
"post": {
"operationId": "searchFindContact",
"summary": "Find contact",
"description": "Search for a subscriber globally across the account by email address.",
"tags": [
"Search"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Must be a valid email address."
}
},
"required": [
"query"
]
},
"example": {
"query": "foo@bar.cz"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string"
},
"list_id": {
"type": "integer"
},
"status": {
"type": "integer"
},
"name": {
"type": "string"
},
"surname": {
"type": "string"
},
"custom_fields": {
"type": "object",
"properties": {
"some_field": {
"type": "string"
}
}
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "string"
},
"subscribed_at": {
"type": "string"
},
"unsubscribed_at": {
"type": "string"
}
}
}
},
"example": [
{
"email": "foo@bar.cz",
"list_id": 1,
"status": 2,
"name": "Foo",
"surname": "Bar",
"custom_fields": {
"some_field": "text"
},
"tags": [
"tags"
],
"source": "app",
"subscribed_at": "2022-11-15T12:59:21.000000Z",
"unsubscribed_at": "2023-09-21T10:36:38.000000Z"
}
]
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"query": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"example": {
"errors": {
"query": [
"Invalid email address"
]
}
}
}
}
}
}
}
},
"/subscribers/{email}": {
"get": {
"operationId": "subscribersGet",
"summary": "Get subscriber",
"description": "Get subscriber details globally across all lists in the account.",
"tags": [
"Subscribers"
],
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Subscriber's email address.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscriber": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"surname": {
"type": "string"
},
"email": {
"type": "string"
},
"gender": {
"type": "string"
},
"bounce_soft": {
"type": "integer"
},
"bounced_hard": {
"type": "integer"
},
"inserted_at": {
"type": "string"
},
"rating": {
"type": "number"
},
"country": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"lists": {
"type": "object",
"properties": {
"1": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"list_id": {
"type": "integer"
},
"email": {
"type": "string"
},
"status": {
"type": "integer"
},
"subscribed_at": {
"type": "string"
},
"source": {
"type": "string"
}
}
}
}
}
}
}
}
},
"example": {
"subscriber": {
"name": "Foo",
"surname": "Bar",
"email": "foo@bar.cz",
"gender": "male",
"bounce_soft": 0,
"bounced_hard": 0,
"inserted_at": "2018-11-15 13:59:21",
"rating": 2.5,
"country": "CZ",
"tags": [
"Completed",
"SomeTag"
],
"lists": {
"1": {
"id": 407704,
"list_id": 1,
"email": "foo@bar.cz",
"status": 1,
"subscribed_at": "2018-11-15T12:59:21.000000Z",
"source": "app"
}
}
}
}
}
}
}
}
}
},
"/subscribers/{email}/transactions": {
"get": {
"operationId": "subscribersTransactions",
"summary": "Get transactions",
"description": "Retrieve a paginated list of transactions (purchases) for a given subscriber email address, sorted by timestamp descending. Each transaction includes its items.",
"tags": [
"Subscribers"
],
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Subscriber's email address.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Number of results per page. Default `100`, maximum `500`.",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page number.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"transactions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"order_id": {
"type": "string"
},
"email": {
"type": "string"
},
"shop": {
"type": "string"
},
"amount": {
"type": "integer"
},
"tax": {
"type": "integer"
},
"shipping": {
"type": "integer"
},
"city": {
"type": "string"
},
"county": {},
"country": {
"type": "string"
},
"timestamp": {
"type": "string"
},
"props": {},
"status": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"order_id": {
"type": "string"
},
"code": {
"type": "string"
},
"title": {
"type": "string"
},
"category": {
"type": "string"
},
"price": {
"type": "integer"
},
"amount": {
"type": "integer"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
},
"current_page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"total": {
"type": "integer"
},
"last_page": {
"type": "integer"
}
}
},
"example": {
"transactions": [
{
"id": 2220,
"order_id": "5301",
"email": "foo@bar.cz",
"shop": "mujshop.cz",
"amount": 2000,
"tax": 420,
"shipping": 99,
"city": "Praha",
"county": null,
"country": "CZ",
"timestamp": "2025-03-15 14:30:00",
"props": null,
"status": "completed",
"items": [
{
"order_id": "5301",
"code": "SKU-001",
"title": "Product name",
"category": "Electronics",
"price": 1901,
"amount": 1,
"categories": [
"Electronics",
"Gadgets"
]
}
]
}
],
"current_page": 1,
"per_page": 50,
"total": 128,
"last_page": 3
}
}
}
}
}
}
},
"/subscribers/{email}/events": {
"get": {
"operationId": "subscribersEvents",
"summary": "Get events for subscriber",
"description": "Retrieve a paginated list of tracker events for a given subscriber email address, sorted by ID descending.",
"tags": [
"Subscribers"
],
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Subscriber's email address.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Number of results per page. Default `20`, maximum `100`.",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page number.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"current_page": {
"type": "integer"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"category": {
"type": "string"
},
"action": {
"type": "string"
},
"label": {
"type": "string"
},
"property": {},
"value": {
"type": "string"
},
"timestamp": {
"type": "string"
}
}
}
},
"per_page": {
"type": "integer"
},
"total": {
"type": "integer"
}
}
},
"example": {
"current_page": 1,
"data": [
{
"id": 1234,
"email": "foo@bar.cz",
"category": "ue",
"action": "Basket",
"label": "Basket",
"property": null,
"value": "{\"data\":{\"data\":{\"action\":\"Basket\",\"products\":[]}}}",
"timestamp": "2025-03-15T14:30:00.000000Z"
}
],
"per_page": 10,
"total": 1
}
}
}
}
}
}
},
"/subscribers/{email}/email-log": {
"get": {
"operationId": "subscribersEmailLog",
"summary": "Get email log",
"description": "Retrieve a paginated list of campaign log entries for a given subscriber email address, sorted by occurrence date descending.",
"tags": [
"Subscribers"
],
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Subscriber's email address.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Number of results per page. Default `20`, maximum `100`.",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page number.",
"schema": {
"type": "integer"
}
},
{
"name": "events[]",
"in": "query",
"required": false,
"description": "Filter by event types. Can be specified multiple times. Possible values: `send`, `open`, `click`, `hard_bounce`, `soft_bounce`, `out_of_band`, `unsub`, `spam`, `spam_complaint`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"current_page": {
"type": "integer"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"campaign_id": {
"type": "integer"
},
"autoresponder_id": {},
"action_id": {},
"event": {
"type": "string"
},
"msg": {},
"url": {},
"email": {
"type": "string"
},
"occured_at": {
"type": "string"
},
"mail_name": {}
}
}
},
"per_page": {
"type": "integer"
},
"total": {
"type": "integer"
}
}
},
"example": {
"current_page": 1,
"data": [
{
"campaign_id": 100,
"autoresponder_id": null,
"action_id": null,
"event": "open",
"msg": null,
"url": null,
"email": "foo@bar.cz",
"occured_at": "2025-03-15T14:30:00.000000Z",
"mail_name": null
},
{
"campaign_id": 100,
"autoresponder_id": null,
"action_id": null,
"event": "click",
"msg": null,
"url": "https://example.com/offer",
"email": "foo@bar.cz",
"occured_at": "2025-03-15T14:25:00.000000Z",
"mail_name": null
}
],
"per_page": 10,
"total": 2
}
}
}
}
}
}
},
"/subscribers/{email}/automation-log": {
"get": {
"operationId": "subscribersAutomationLog",
"summary": "Get automation log",
"description": "Retrieve a paginated list of automation (pipeline) log entries for a given subscriber email address, sorted by timestamp descending by default.",
"tags": [
"Subscribers"
],
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Subscriber's email address.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Number of results per page. Default `20`, maximum `100`.",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page number.",
"schema": {
"type": "integer"
}
},
{
"name": "sort_by",
"in": "query",
"required": false,
"description": "Column to sort by. Possible values: `timestamp`, `id`, `pipeline_id`. Default `timestamp`.",
"schema": {
"type": "string"
}
},
{
"name": "sort_dir",
"in": "query",
"required": false,
"description": "Sort direction. Possible values: `asc`, `desc`. Default `desc`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"automation_log": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"user_id": {
"type": "integer"
},
"pipeline_id": {
"type": "integer"
},
"action_id": {
"type": "string"
},
"trigger_id": {
"type": "string"
},
"email": {
"type": "string"
},
"props": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
}
},
"next": {},
"timestamp": {
"type": "string"
}
}
}
},
"current_page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"total": {
"type": "integer"
},
"last_page": {
"type": "integer"
}
}
},
"example": {
"automation_log": [
{
"id": 5678,
"user_id": 1,
"pipeline_id": 42,
"action_id": "node_abc123",
"trigger_id": "trigger_xyz",
"email": "foo@bar.cz",
"props": {
"key": "value"
},
"next": null,
"timestamp": "2025-03-15T14:30:00.000000Z"
}
],
"current_page": 1,
"per_page": 10,
"total": 1,
"last_page": 1
}
}
}
}
}
}
},
"/subscribers/{email}/delete": {
"delete": {
"operationId": "subscribersDelete",
"summary": "Delete subscriber",
"description": "Permanently delete a subscriber from the database.",
"tags": [
"Subscribers"
],
"parameters": [
{
"name": "email",
"in": "path",
"required": true,
"description": "Subscriber's email address.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
}
}
},
"example": {
"deleted": true
}
}
}
}
}
}
},
"/templates": {
"get": {
"operationId": "templatesListAll",
"summary": "List all templates",
"description": "Retrieve all email templates in your account.",
"tags": [
"Templates"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"folder": {
"type": "integer"
},
"name": {
"type": "string"
},
"html": {
"type": "string"
},
"campaign_id": {
"type": "integer"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
}
},
"example": [
{
"id": 1234,
"folder": 0,
"name": "Some Template Name",
"html": "Html code here...",
"campaign_id": 5678,
"created_at": "2024-02-12 15:13:16",
"updated_at": "2024-02-12 15:13:26"
}
]
}
}
}
}
},
"post": {
"operationId": "templatesCreate",
"summary": "Create a new template",
"description": "Create a new email template from raw HTML or from an MJML definition. Send exactly one of `html` and `mjml`. A template created from an MJML definition is compiled to HTML by Ecomail and stays editable in the drag-and-drop editor.",
"tags": [
"Templates"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Template name."
},
"html": {
"type": "string",
"description": "Template HTML content. Required when `mjml` is not sent. Do not combine with `mjml`."
},
"mjml": {
"type": "object",
"description": "MJML definition of the template, in the same JSON format the Ecomail editor uses. Required when `html` is not sent. Each node has a `tagName` (an MJML component such as `mj-section`, `mj-column`, `mj-text`, `mj-image`, or `mj-button`), optional `attributes`, and either `children` or `content`.",
"properties": {
"tagName": {
"type": "string"
},
"attributes": {
"type": "object"
},
"children": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [
"children"
]
}
},
"required": [
"name"
]
},
"example": {
"name": "New MJML Template",
"mjml": {
"tagName": "mj-body",
"attributes": {},
"children": [
{
"tagName": "mj-section",
"children": [
{
"tagName": "mj-column",
"children": [
{
"tagName": "mj-text",
"content": "Hello from the API"
}
]
}
]
}
]
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"html": {
"type": "string"
}
}
},
"example": {
"id": 1,
"name": "New Template",
"html": "Template HTML"
}
}
}
},
"422": {
"description": "The MJML definition could not be rendered to HTML.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "The mjml definition could not be rendered to html."
}
}
}
}
}
}
},
"/templates/{template_id}": {
"get": {
"operationId": "templatesGet",
"summary": "Get template",
"description": "Retrieve a specific template by its ID.",
"tags": [
"Templates"
],
"parameters": [
{
"name": "template_id",
"in": "path",
"required": true,
"description": "Template ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"folder": {
"type": "integer"
},
"name": {
"type": "string"
},
"html": {
"type": "string"
},
"campaign_id": {
"type": "integer"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
},
"example": {
"id": 1234,
"folder": 0,
"name": "Some Template Name",
"html": "Html code here...",
"campaign_id": 5678,
"created_at": "2024-02-12 15:13:16",
"updated_at": "2024-02-12 15:13:26"
}
}
}
}
}
},
"put": {
"operationId": "templatesUpdate",
"summary": "Update template",
"description": "Update an existing email template by its ID.",
"tags": [
"Templates"
],
"parameters": [
{
"name": "template_id",
"in": "path",
"required": true,
"description": "Template ID.",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"html": {
"type": "string",
"description": "Template HTML content."
},
"name": {
"type": "string",
"description": "Template name."
},
"inline_css": {
"type": "boolean",
"description": "Whether to inline CSS styles into the HTML."
}
},
"required": [
"html"
]
},
"example": {
"name": "Update Template",
"inline_css": true,
"html": "Template HTML"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"html": {
"type": "string"
},
"folder": {
"type": "integer"
},
"campaign_id": {},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
},
"example": {
"id": 1234,
"name": "Update Template",
"html": "Template HTML",
"folder": 0,
"campaign_id": null,
"created_at": "2024-02-12 15:13:16",
"updated_at": "2024-02-12 16:45:30"
}
}
}
}
}
}
},
"/tracker/events": {
"post": {
"operationId": "trackerCreateEvent",
"summary": "Create an event",
"description": "Track a custom event for a subscriber. Supplements the JavaScript tracker.",
"tags": [
"Tracker events"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"event": {
"type": "object",
"description": "Event details.",
"properties": {
"email": {
"type": "string",
"description": "Subscriber's email address. The subscriber must already exist in your contact list. Maximum length is **150 characters** — longer values are rejected with a `422` error, not truncated."
},
"category": {
"type": "string",
"description": "Event category (e.g. `\"shopping\"`, `\"engagement\"`, `\"support\"`). Maximum length is **255 bytes**; longer values are truncated."
},
"action": {
"type": "string",
"description": "Event action (e.g. `\"product_viewed\"`, `\"form_submitted\"`, `\"review_left\"`). Maximum length is **255 bytes**; longer values are truncated."
},
"label": {
"type": "string",
"description": "Event label — a human-readable name or identifier (e.g. a product name, page title). Maximum length is **255 bytes**; longer values are truncated."
},
"property": {
"type": "string",
"description": "Event property — a custom key or identifier (e.g. a product SKU, category slug). Maximum length is **300 bytes**; longer values are truncated."
},
"value": {
"type": [
"string",
"object",
"array"
],
"description": "Event value. Can be a plain string, a JSON-encoded string, or a JSON object/array (objects and arrays will be JSON-encoded automatically on our side). Maximum length is **20,000 characters** (after JSON encoding, if applicable) — longer values are rejected with a `422` error, not truncated.",
"items": {}
}
},
"required": [
"email"
]
}
},
"required": [
"event"
]
},
"example": {
"event": {
"email": "john@example.com",
"category": "shopping",
"action": "product_viewed",
"label": "Nike Air Max 90",
"property": "nike-air-max-90",
"value": {
"product_id": 12345,
"price": 139.99,
"currency": "EUR",
"variant": "Black/White",
"url": "https://example.com/products/nike-air-max-90"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"category": {
"type": "string"
},
"action": {
"type": "string"
},
"label": {
"type": "string"
},
"property": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"example": {
"id": 1234,
"email": "john@example.com",
"category": "shopping",
"action": "product_viewed",
"label": "Nike Air Max 90",
"property": "nike-air-max-90",
"value": "{\"product_id\":12345,\"price\":139.99,\"currency\":\"EUR\",\"variant\":\"Black/White\",\"url\":\"https://example.com/products/nike-air-max-90\"}"
}
}
}
}
}
}
},
"/tracker/events/{id}": {
"get": {
"operationId": "trackerGetEvent",
"summary": "Get event by ID",
"description": "Retrieve a single tracker event by its ID.",
"tags": [
"Tracker events"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Event ID.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"duid": {},
"email": {
"type": "string"
},
"category": {
"type": "string"
},
"action": {
"type": "string"
},
"label": {
"type": "string"
},
"property": {},
"value": {
"type": "string"
},
"timestamp": {
"type": "string"
},
"campaign_attr": {},
"pipeline_attr": {}
}
},
"example": {
"id": 1234,
"duid": null,
"email": "foo@bar.cz",
"category": "ue",
"action": "Basket",
"label": "Basket",
"property": null,
"value": "{\"data\":{\"data\":{\"action\":\"Basket\",\"products\":[]}}}",
"timestamp": "2025-03-15T14:30:00.000000Z",
"campaign_attr": null,
"pipeline_attr": null
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"example": {
"message": "Event not found"
}
}
}
}
}
}
},
"/transactional/send-message": {
"post": {
"operationId": "transactionalSendMessage",
"summary": "Send transactional email",
"description": "Send a transactional email with custom content.",
"tags": [
"Transactional emails"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "object",
"description": "The message object containing all email details.",
"properties": {
"subject": {
"type": "string",
"description": "Email subject line."
},
"from_name": {
"type": "string",
"description": "Sender's display name."
},
"from_email": {
"type": "string",
"description": "Sender's email address. Must be from a verified domain."
},
"reply_to": {
"type": "string",
"description": "Reply-to email address."
},
"text": {
"type": "string",
"description": "Plain text content. Either `text` or `html` is required."
},
"html": {
"type": "string",
"description": "HTML content. Either `text` or `html` is required."
},
"amp_html": {
"type": "string",
"description": "AMP HTML content."
},
"to": {
"type": "array",
"description": "Array of recipient objects.",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Recipient's email address."
},
"name": {
"type": "string",
"description": "Recipient's display name."
},
"cc": {
"type": "string",
"description": "CC email address."
},
"bcc": {
"type": "string",
"description": "BCC email address."
}
},
"required": [
"email"
]
}
},
"global_merge_vars": {
"type": "array",
"description": "Array of merge tag objects for personalization.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merge tag name."
},
"content": {
"type": "string",
"description": "Merge tag value."
}
}
}
},
"attachments": {
"type": "array",
"description": "Array of attachment objects.",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "MIME type of the attachment."
},
"name": {
"type": "string",
"description": "File name of the attachment."
},
"content": {
"type": "string",
"description": "Base64 encoded file content."
}
}
}
},
"options": {
"type": "object",
"description": "Tracking options.",
"properties": {
"click_tracking": {
"type": "boolean",
"description": "Enable click tracking."
},
"open_tracking": {
"type": "boolean",
"description": "Enable open tracking."
}
}
}
},
"required": [
"subject",
"from_name",
"from_email",
"to"
]
}
},
"required": [
"message"
]
},
"example": {
"message": {
"subject": "Email subject",
"from_name": "Sender's name",
"from_email": "foo@bar.cz",
"reply_to": "foo@bar.cz",
"text": "Plain text content",
"html": "Email HTML content",
"to": [
{
"email": "to@me.com",
"name": "Recipient's name",
"cc": "cc@me.com",
"bcc": "bcc@me.com"
}
],
"global_merge_vars": [
{
"name": "mergeTagName",
"content": "mergeTagValue"
}
],
"attachments": [
{
"type": "mime/type",
"name": "attachment-name.pdf",
"content": "base64encodedcontent"
}
],
"options": {
"click_tracking": true,
"open_tracking": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "object",
"properties": {
"total_rejected_recipients": {
"type": "integer"
},
"total_accepted_recipients": {
"type": "integer"
},
"id": {
"type": "integer"
}
}
}
}
},
"example": {
"results": {
"total_rejected_recipients": 0,
"total_accepted_recipients": 2,
"id": 11668787484950528
}
}
}
}
}
}
}
},
"/transactional/send-template": {
"post": {
"operationId": "transactionalSendTemplate",
"summary": "Send transactional template",
"description": "Send a transactional email using a pre-defined template.",
"tags": [
"Transactional emails"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "object",
"description": "The message object containing all email details.",
"properties": {
"template_id": {
"type": "integer",
"description": "ID of the template to use."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"from_name": {
"type": "string",
"description": "Sender's display name."
},
"from_email": {
"type": "string",
"description": "Sender's email address. Must be from a verified domain."
},
"reply_to": {
"type": "string",
"description": "Reply-to email address."
},
"to": {
"type": "array",
"description": "Array of recipient objects.",
"items": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Recipient's email address."
},
"name": {
"type": "string",
"description": "Recipient's display name."
},
"cc": {
"type": "string",
"description": "CC email address."
},
"bcc": {
"type": "string",
"description": "BCC email address."
}
},
"required": [
"email"
]
}
},
"global_merge_vars": {
"type": "array",
"description": "Array of merge tag objects for personalization.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merge tag name."
},
"content": {
"type": "string",
"description": "Merge tag value."
}
}
}
},
"attachments": {
"type": "array",
"description": "Array of attachment objects.",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "MIME type of the attachment."
},
"name": {
"type": "string",
"description": "File name of the attachment."
},
"content": {
"type": "string",
"description": "Base64 encoded file content."
}
}
}
},
"options": {
"type": "object",
"description": "Tracking options.",
"properties": {
"click_tracking": {
"type": "boolean",
"description": "Enable click tracking."
},
"open_tracking": {
"type": "boolean",
"description": "Enable open tracking."
}
}
}
},
"required": [
"template_id",
"subject",
"from_name",
"from_email",
"to"
]
}
},
"required": [
"message"
]
},
"example": {
"message": {
"template_id": 1,
"subject": "Email subject",
"from_name": "Sender's name",
"from_email": "foo@bar.cz",
"reply_to": "foo@bar.cz",
"to": [
{
"email": "to@me.com",
"name": "Recipient's name"
}
],
"global_merge_vars": [
{
"name": "mergeTagName",
"content": "mergeTagValue"
}
],
"options": {
"click_tracking": true,
"open_tracking": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "object",
"properties": {
"total_rejected_recipients": {
"type": "integer"
},
"total_accepted_recipients": {
"type": "integer"
},
"id": {
"type": "integer"
}
}
}
}
},
"example": {
"results": {
"total_rejected_recipients": 0,
"total_accepted_recipients": 2,
"id": 11668787484950528
}
}
}
}
}
}
}
},
"/transactional/stats": {
"get": {
"operationId": "transactionalStats",
"summary": "Transactional email stats",
"description": "Get statistics for transactional emails for the past 6 months.",
"tags": [
"Transactional emails"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"stats": {
"type": "object",
"properties": {
"open_rate": {
"type": "number"
},
"click_rate": {
"type": "integer"
},
"bounce_rate": {
"type": "integer"
},
"count_injected": {
"type": "integer"
},
"count_accepted": {
"type": "integer"
},
"count_delivered": {
"type": "integer"
},
"count_unique_rendered": {
"type": "integer"
},
"count_rendered": {
"type": "integer"
},
"count_clicked": {
"type": "integer"
},
"count_unique_clicked": {
"type": "integer"
},
"count_bounce": {
"type": "integer"
},
"count_hard_bounce": {
"type": "integer"
},
"count_soft_bounce": {
"type": "integer"
},
"count_rejected": {
"type": "integer"
},
"count_spam_complaint": {
"type": "integer"
}
}
}
}
},
"example": {
"stats": {
"open_rate": 85.71,
"click_rate": 0,
"bounce_rate": 0,
"count_injected": 21,
"count_accepted": 21,
"count_delivered": 21,
"count_unique_rendered": 18,
"count_rendered": 126,
"count_clicked": 0,
"count_unique_clicked": 0,
"count_bounce": 0,
"count_hard_bounce": 0,
"count_soft_bounce": 0,
"count_rejected": 0,
"count_spam_complaint": 0
}
}
}
}
}
}
}
},
"/transactional/stats/doi": {
"get": {
"operationId": "transactionalDoiStats",
"summary": "Double opt-in stats",
"description": "Get statistics for double opt-in emails for the past 6 months.",
"tags": [
"Transactional emails"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"stats": {
"type": "object",
"properties": {
"open_rate": {
"type": "number"
},
"click_rate": {
"type": "number"
},
"bounce_rate": {
"type": "number"
},
"count_injected": {
"type": "integer"
},
"count_accepted": {
"type": "integer"
},
"count_delivered": {
"type": "integer"
},
"count_unique_rendered": {
"type": "integer"
},
"count_rendered": {
"type": "integer"
},
"count_clicked": {
"type": "integer"
},
"count_unique_clicked": {
"type": "integer"
},
"count_bounce": {
"type": "integer"
},
"count_hard_bounce": {
"type": "integer"
},
"count_soft_bounce": {
"type": "integer"
},
"count_rejected": {
"type": "integer"
},
"count_spam_complaint": {
"type": "integer"
}
}
}
}
},
"example": {
"stats": {
"open_rate": 69.34,
"click_rate": 81.01,
"bounce_rate": 2.52,
"count_injected": 449,
"count_accepted": 437,
"count_delivered": 437,
"count_unique_rendered": 303,
"count_rendered": 545,
"count_clicked": 417,
"count_unique_clicked": 354,
"count_bounce": 11,
"count_hard_bounce": 4,
"count_soft_bounce": 1,
"count_rejected": 0,
"count_spam_complaint": 0
}
}
}
}
}
}
}
},
"/tracker/transaction": {
"post": {
"operationId": "transactionsCreate",
"summary": "Create a transaction",
"description": "Create a new transaction for a subscriber.",
"tags": [
"Transactions"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"transaction": {
"type": "object",
"description": "Transaction details.",
"properties": {
"order_id": {
"type": "string",
"description": "Your unique transaction ID."
},
"email": {
"type": "string",
"description": "Subscriber's email address."
},
"shop": {
"type": "string",
"description": "Name of your shop, used in conditionals in the app. Case sensitive. An empty value results in not being able to select the shop in segments."
},
"amount": {
"type": "number",
"description": "Total amount including tax and shipping."
},
"tax": {
"type": "number",
"description": "Tax amount only."
},
"shipping": {
"type": "number",
"description": "Shipping amount only."
},
"city": {
"type": "string",
"description": "Delivery city."
},
"county": {
"type": "string",
"description": "Delivery county."
},
"country": {
"type": "string",
"description": "Delivery country."
},
"timestamp": {
"type": "integer",
"description": "Unix timestamp of the transaction."
},
"props": {
"type": [
"string",
"object"
],
"description": "Optional properties, used in conditionals."
},
"status": {
"type": "string",
"description": "Transaction status. Accepted values: `processing`, `canceled`, `pending`, `completed`, `null`."
}
},
"required": [
"order_id",
"email"
]
},
"transaction_items": {
"type": "array",
"description": "Array of transaction items.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Product code."
},
"title": {
"type": "string",
"description": "Product name."
},
"category": {
"type": "string",
"description": "Deprecated. Use `categories` instead."
},
"categories": {
"type": "array",
"description": "List of product categories. Limited to 100 characters per category and 20 categories per item. Currently not visible in the Ecomail app — use the `category` parameter for now.",
"items": {}
},
"price": {
"type": "number",
"description": "Total price for the given quantity."
},
"amount": {
"type": "number",
"description": "Quantity of the product."
},
"tags": {
"type": "array",
"description": "Optional item tags. Limited to 5000 characters per account.",
"items": {}
}
}
}
}
},
"required": [
"transaction",
"transaction_items"
]
},
"example": {
"transaction": {
"order_id": "transaction_1234",
"email": "foo@bar.cz",
"shop": "myshop.cz",
"amount": 1500,
"tax": 200,
"shipping": 100,
"city": "Praha",
"timestamp": 1441905935,
"status": "completed"
},
"transaction_items": [
{
"code": "product code",
"title": "product name",
"categories": [
"my category 1",
"my category 2"
],
"price": 1500,
"amount": 1,
"tags": [
"M",
"3+",
"puzzle"
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string"
},
"email": {
"type": "string"
},
"shop": {
"type": "string"
},
"amount": {
"type": "integer"
},
"timestamp": {
"type": "string"
},
"id": {
"type": "integer"
},
"status": {
"type": "string"
}
}
},
"example": {
"order_id": "transaction_1234",
"email": "foo@bar.cz",
"shop": "myshop.cz",
"amount": 1500,
"timestamp": "2015-09-10 17:25:35",
"id": 1,
"status": "completed"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"transaction.order_id": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"example": {
"errors": {
"transaction.order_id": [
"The transaction.order id has already been taken."
]
}
}
}
}
}
}
},
"get": {
"operationId": "transactionsGet",
"summary": "Get transactions",
"description": "Retrieve a paginated list of transactions with optional filters.",
"tags": [
"Transactions"
],
"parameters": [
{
"name": "shop",
"in": "query",
"required": false,
"description": "Filter by exact shop name.",
"schema": {
"type": "string"
}
},
{
"name": "email",
"in": "query",
"required": false,
"description": "Filter by email address.",
"schema": {
"type": "string"
}
},
{
"name": "date_from",
"in": "query",
"required": false,
"description": "Start date filter in `YYYY-MM-DD` format.",
"schema": {
"type": "string"
}
},
{
"name": "date_to",
"in": "query",
"required": false,
"description": "End date filter in `YYYY-MM-DD` format.",
"schema": {
"type": "string"
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"description": "Number of results per page. Maximum `500`.",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page number.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"current_page": {
"type": "integer"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"order_id": {
"type": "string"
},
"email": {
"type": "string"
},
"shop": {
"type": "string"
},
"amount": {
"type": "integer"
},
"timestamp": {
"type": "string"
},
"status": {},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"title": {
"type": "string"
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"price": {
"type": "integer"
},
"amount": {
"type": "string"
}
}
}
}
}
}
},
"per_page": {
"type": "integer"
},
"total": {
"type": "integer"
}
}
},
"example": {
"current_page": 1,
"data": [
{
"id": 2220,
"order_id": "5301",
"email": "foo@bar.cz",
"shop": "mujshop.cz",
"amount": 2000,
"timestamp": "2023-02-15 09:40:56",
"status": null,
"items": [
{
"code": "product code 1",
"title": "product name 1",
"categories": [
"product category 1"
],
"price": 400,
"amount": "1"
}
]
}
],
"per_page": 100,
"total": 234
}
}
}
}
}
}
},
"/tracker/transaction-bulk": {
"post": {
"operationId": "transactionsCreateBulk",
"summary": "Create bulk transactions",
"description": "Create multiple transactions in a single request.",
"tags": [
"Transactions"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"transaction_data": {
"type": "array",
"description": "Array of transaction objects, each containing a `transaction` and `transaction_items` object with the same structure as the [single create endpoint](/api-reference/transactions/create).",
"items": {
"type": "object",
"properties": {
"transaction": {
"type": "object",
"description": "Transaction details. See [Create a transaction](/api-reference/transactions/create) for all available properties."
},
"transaction_items": {
"type": "array",
"description": "Array of transaction items. See [Create a transaction](/api-reference/transactions/create) for all available properties.",
"items": {}
}
},
"required": [
"transaction",
"transaction_items"
]
}
}
},
"required": [
"transaction_data"
]
},
"example": {
"transaction_data": [
{
"transaction": {
"order_id": "transaction_1001",
"email": "foo@bar.cz",
"shop": "myshop.cz",
"amount": 1000,
"timestamp": 1673342224,
"status": "completed"
},
"transaction_items": [
{
"code": "product code 1",
"title": "product name 1",
"price": 400,
"amount": "1"
}
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"inserts": {
"type": "integer"
}
}
},
"example": {
"inserts": 2
}
}
}
}
}
}
},
"/tracker/transaction/{order_id}": {
"put": {
"operationId": "transactionsUpdate",
"summary": "Update a transaction",
"description": "Overwrite an existing transaction with new data.",
"tags": [
"Transactions"
],
"parameters": [
{
"name": "order_id",
"in": "path",
"required": true,
"description": "Order ID of the transaction to update.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"transaction": {
"type": "object",
"description": "Transaction details. Same structure as the [Create a transaction](/api-reference/transactions/create) endpoint.",
"properties": {
"order_id": {
"type": "string",
"description": "Your unique transaction ID."
},
"email": {
"type": "string",
"description": "Subscriber's email address."
},
"shop": {
"type": "string",
"description": "Name of your shop."
},
"amount": {
"type": "number",
"description": "Total amount including tax and shipping."
},
"tax": {
"type": "number",
"description": "Tax amount only."
},
"shipping": {
"type": "number",
"description": "Shipping amount only."
},
"city": {
"type": "string",
"description": "Delivery city."
},
"county": {
"type": "string",
"description": "Delivery county."
},
"country": {
"type": "string",
"description": "Delivery country."
},
"timestamp": {
"type": "integer",
"description": "Unix timestamp of the transaction."
},
"props": {
"type": [
"string",
"object"
],
"description": "Optional properties, used in conditionals."
},
"status": {
"type": "string",
"description": "Transaction status. Accepted values: `processing`, `canceled`, `pending`, `completed`, `null`."
}
},
"required": [
"order_id",
"email"
]
},
"transaction_items": {
"type": "array",
"description": "Array of transaction items. Same structure as the [Create a transaction](/api-reference/transactions/create) endpoint.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Product code."
},
"title": {
"type": "string",
"description": "Product name."
},
"category": {
"type": "string",
"description": "Deprecated. Use `categories` instead."
},
"categories": {
"type": "array",
"description": "List of product categories.",
"items": {}
},
"price": {
"type": "number",
"description": "Total price for the given quantity."
},
"amount": {
"type": "number",
"description": "Quantity of the product."
},
"tags": {
"type": "array",
"description": "Optional item tags.",
"items": {}
}
}
}
}
},
"required": [
"transaction",
"transaction_items"
]
},
"example": {
"transaction": {
"order_id": "transaction_1234",
"email": "foo@bar.cz",
"shop": "myshop.cz",
"amount": 1500,
"tax": 200,
"shipping": 100,
"city": "Praha",
"timestamp": 1441905935,
"status": "completed"
},
"transaction_items": [
{
"code": "product code",
"title": "product name",
"categories": [
"my category 1",
"my category 2"
],
"price": 1500,
"amount": 1,
"tags": [
"M",
"3+",
"puzzle"
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {}
},
"example": {}
}
}
}
}
}
},
"/tracker/transaction/{order_id}/delete": {
"delete": {
"operationId": "transactionsDelete",
"summary": "Delete a transaction",
"description": "Delete a single transaction by order ID.",
"tags": [
"Transactions"
],
"parameters": [
{
"name": "order_id",
"in": "path",
"required": true,
"description": "Order ID from your shop.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"transaction_data": {
"type": "object",
"description": "Optional filter to match the transaction by shop.",
"properties": {
"shop": {
"type": "string",
"description": "If provided, the transaction is only deleted if it matches this shop value."
}
}
}
}
},
"example": {
"transaction_data": {
"shop": "someshop.com"
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
}
}
},
"example": {
"deleted": true
}
}
}
}
}
}
},
"/tracker/transaction/delete-bulk": {
"delete": {
"operationId": "transactionsDeleteBulk",
"summary": "Delete bulk transactions",
"description": "Delete multiple transactions in a single request.",
"tags": [
"Transactions"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"transaction_data": {
"type": "array",
"description": "Array of transaction identifiers to delete.",
"items": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "Order ID of the transaction to delete."
},
"shop": {
"type": "string",
"description": "If provided, the transaction is only deleted if it matches this shop value."
}
},
"required": [
"order_id"
]
}
}
},
"required": [
"transaction_data"
]
},
"example": {
"transaction_data": [
{
"order_id": "1000001"
},
{
"order_id": "1000025",
"shop": "someshop.com"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deleted": {
"type": "integer"
}
}
},
"example": {
"deleted": 2
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "object",
"properties": {
"transaction_data": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"example": {
"errors": {
"transaction_data": [
"The transaction data may not have more than 1000 items."
]
}
}
}
}
}
}
}
},
"/account/settings/webhook": {
"post": {
"operationId": "webhooksSetUrl",
"summary": "Set webhook URL",
"description": "Set the target webhook URL for campaign statistics.",
"tags": [
"Webhooks"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Target webhook URL."
}
},
"required": [
"url"
]
},
"example": {
"url": "https://your-webhook-url.com"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
},
"example": {
"success": true
}
}
}
}
}
},
"get": {
"operationId": "webhooksGetUrl",
"summary": "Get webhook URL",
"description": "Get the currently configured webhook URL.",
"tags": [
"Webhooks"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"webhook": {
"type": "object",
"properties": {
"url": {
"type": "string"
}
}
}
}
},
"example": {
"webhook": {
"url": "https://your-webhook-url.com"
}
}
}
}
}
}
},
"delete": {
"operationId": "webhooksDeleteUrl",
"summary": "Delete webhook URL",
"description": "Remove the currently configured webhook URL.",
"tags": [
"Webhooks"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
},
"example": {
"success": true
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "key"
}
}
}
}