{ "openapi": "3.0.3", "info": { "title": "Ecomail.cz v2.0 API", "version": "2.0.0", "description": "A powerful and flexible RESTful API for integrating with the Ecomail email marketing and automation platform. Manage campaigns, subscribers, lists, transactional emails, and more." }, "servers": [ { "url": "https://api2.ecomailapp.cz/" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Lists", "description": "Working with subscriber lists. Lists are the primary way to organize your contacts for targeted campaigns." }, { "name": "List Subscribers", "description": "Manage subscribers within a specific list - subscribe, unsubscribe, update, and query." }, { "name": "Subscribers (Global)", "description": "Endpoints for working with subscribers globally across an account, independent of a specific list." }, { "name": "Campaigns", "description": "Endpoints for working with campaigns. Status codes: 0=Draft, 1=Preparing, 2=Sending, 3=Sent, 4=Errored, 7=Scheduled." }, { "name": "Automations", "description": "Endpoints for working with automations (pipelines) in the application." }, { "name": "Templates", "description": "Endpoints for working with email templates." }, { "name": "Domains", "description": "Endpoints for managing sending domains linked to your account." }, { "name": "Transactional Emails", "description": "Send transactional emails. Only for paid accounts with a verified sending domain.Merge tags data limit: 100,000 bytes. Message size limit (including attachments): 4 MB." }, { "name": "Transactions", "description": "Endpoints for managing e-commerce transactions. Timestamps are saved and returned in UTC+0." }, { "name": "Feeds", "description": "Refresh product and data feeds. Marketer+ accounts only." }, { "name": "Tracker / Events", "description": "Events tracker, supplements the JavaScript tracker." }, { "name": "Search", "description": "Search for a subscriber globally across an account." }, { "name": "Discount Coupons", "description": "Import and manage discount coupon codes." }, { "name": "Webhook", "description": "Configure webhooks for receiving campaign events (opens, deliveries, clicks, etc.). Webhook sends POST requests as JSON with a 10-second timeout." } ], "paths": { "/lists": { "get": { "summary": "View all lists", "description": "Returns an array of all subscriber lists in your account.", "tags": [ "Lists" ], "operationId": "list-all", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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": { "summary": "Add new list", "description": "Creates a new subscriber list.", "tags": [ "Lists" ], "operationId": "list-create", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "name": "New list name", "id": 2 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "List name" }, "from_name": { "type": "string", "description": "From name" }, "from_email": { "type": "string", "description": "From email address" }, "reply_to": { "type": "string", "description": "Reply-to email" }, "double_optin": { "type": "boolean", "description": "Sign-up confirmation required?" }, "conf_subject": { "type": "string", "description": "Subject of confirmation email" }, "conf_message": { "type": "string", "description": "Content of confirmation email" } }, "required": [ "name" ] } } } } } }, "/lists/{list_id}": { "get": { "summary": "Show list", "description": "Returns detailed information about a specific list, including custom fields, groups, segments, form settings, and subscriber counts by status.", "tags": [ "Lists" ], "operationId": "list-show", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "list": { "id": "1", "name": "List Name", "from_name": "Sender Name", "from_email": "sender@example.com", "reply_to": "reply@example.com", "double_optin": true, "conf_subject": "Confirmation Subject", "conf_message": "Please confirm: *|SUBCONFIRM|*", "active_subscribers": 100, "custom_fields": { "size": { "type": "int", "name": "Size Field" }, "url": { "type": "url", "name": "URL Field" } }, "groups": { "grp_5e83080ebb988": { "name": "Group 1", "category": [ { "name": "Category A", "id": "plnQNPzCz" } ], "type": "select" } }, "segments": { "5c36008811e45": { "name": "Segment 1", "id": "5c36008811e45" } } }, "subscribers": { "unknown": 0, "subscribed": 375, "unsubscribed": 143, "soft_bounced": 9, "hard_bounced": 11, "complained": 1, "unconfirmed": 25 } } } } } }, "parameters": [ { "name": "list_id", "in": "path", "required": true, "description": "ID of the list", "schema": { "type": "integer" } } ] }, "put": { "summary": "Update list", "description": "Updates the properties of an existing list.", "tags": [ "Lists" ], "operationId": "list-update", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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 } } } } }, "parameters": [ { "name": "list_id", "in": "path", "required": true, "description": "ID of the list", "schema": { "type": "integer" } } ] } }, "/lists/{list_id}/subscribers": { "get": { "summary": "Get subscribers", "description": "Returns a paginated list of subscribers for the given list.", "tags": [ "List Subscribers" ], "operationId": "list-subscribers", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "current_page": 1, "data": [ { "list_id": 75, "email": "some1@contact.com", "status": 1, "sms_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", "rating": 2.5, "city": "City", "country": "CZ" } } ], "per_page": 20, "total": 2 } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page index.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "Filter: subscribed, unsubscribed, not_confirmed, bounced, complained.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Limit up to 5000 per page. Recommended <4000.", "schema": { "type": "integer" } } ] } }, "/lists/{list_id}/subscriber/{email}": { "get": { "summary": "Get subscriber", "description": "Returns detailed subscriber information from a specific list.", "tags": [ "List Subscribers" ], "operationId": "list-get-subscriber", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "subscriber": { "id": 12345, "name": "John", "surname": "Doe", "email": "john.doe@example.com", "company": "Acme Corporation", "street": "123 Main Street", "city": "New York", "zip": "10001", "country": "US", "phone": "+1 (555) 123-4567", "gender": "male", "birthday": "1990-01-15", "tags": [ "tag1", "tag2", "tag3" ], "rating": 4.5, "status": 1, "custom_fields": { "field1": "Value 1", "field2": "Value 2" }, "groups": { "grp_60ddec46df422": [ "a", "b" ] }, "sms_status": 1 } } } } }, "404": { "description": "404 Not Found", "content": { "application/json": { "example": { "errors": [ "Subscriber with email foo@bar.cz was not found in the list" ] } } } } }, "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" } } ] } }, "/lists/{list_id}/subscriber-by-phone/{phone}": { "get": { "summary": "Get subscriber by phone", "description": "Looks up a subscriber by phone number. Must be a valid international phone number.", "tags": [ "List Subscribers" ], "operationId": "list-get-subscriber-phone", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "subscriber": { "id": 123456, "list_id": 789, "email": "foo@bar.cz", "status": 1, "subscribed_at": "2023-01-01T00:00:00.000000Z", "unsubscribed_at": "2023-07-01T00:00:00.000000Z", "custom_fields": { "ID": "123", "key": "value", "url": "https://example.com" }, "groups": null, "source": "API", "sms_status": 0 } } } } }, "422": { "description": "422 Validation Error", "content": { "application/json": { "example": { "errors": { "phone": [ "Invalid phone number" ] } } } } } }, "parameters": [ { "name": "list_id", "in": "path", "required": true, "description": "ID of the list", "schema": { "type": "integer" } }, { "name": "phone", "in": "path", "required": true, "description": "International phone number, e.g. +420111222333", "schema": { "type": "string" } } ] } }, "/lists/{list_id}/subscribe": { "post": { "summary": "Add new subscriber to list", "description": "Adds a new subscriber to a list. If the subscriber already exists, returns already_subscribed: true.", "tags": [ "List Subscribers" ], "operationId": "list-subscribe", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber_data.email": { "type": "string", "description": "Subscriber's email" }, "subscriber_data.name": { "type": "string", "description": "First name" }, "subscriber_data.surname": { "type": "string", "description": "Last name" }, "subscriber_data.gender": { "type": "string", "description": "male or female" }, "subscriber_data.status": { "type": "integer", "description": "1: subscribed, 2: unsubscribed, 4: hard bounce, 5: spam, 6: unconfirmed" }, "subscriber_data.custom_fields": { "type": "object", "description": "Custom fields (max 5000 chars total). Types: string, date, json, int, float, url" }, "subscriber_data.tags": { "type": "array", "description": "Tags (max 2000 chars total, 50/tag). Overwrites current tags!" }, "subscriber_data.groups": { "type": "object", "description": "Groups. Overwrites current values" }, "trigger_autoresponders": { "type": "boolean", "description": "Trigger automations on subscribe.", "default": "false" }, "update_existing": { "type": "boolean", "description": "Update already existing subscriber.", "default": "false" }, "skip_confirmation": { "type": "boolean", "description": "Skip double opt-in. If false, contact added as status 6.", "default": "false" }, "resubscribe": { "type": "boolean", "description": "Force re-subscribe for unsubscribed contacts.", "default": "false" } }, "required": [ "subscriber_data.email" ] } } } } } }, "/lists/{list_id}/unsubscribe": { "delete": { "summary": "Unsubscribe from list", "description": "Unsubscribes a subscriber from a specific list.", "tags": [ "List Subscribers" ], "operationId": "list-unsubscribe", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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" }, "groups": null, "source": "api", "sms_status": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email to unsubscribe" } }, "required": [ "email" ] } } } } } }, "/lists/{list_id}/update-subscriber": { "put": { "summary": "Update subscriber", "description": "Updates an existing subscriber's information in a list.", "tags": [ "List Subscribers" ], "operationId": "list-update-subscriber", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Subscriber email to update" }, "subscriber_data": { "type": "object", "description": "Updated subscriber information (name, surname, custom_fields, tags, groups, etc.)" } }, "required": [ "email" ] } } } } } }, "/lists/{list_id}/subscribe-bulk": { "post": { "summary": "Subscribe bulk", "description": "Adds multiple subscribers to a list at once. Subscribers always skip confirmation.", "tags": [ "List Subscribers" ], "operationId": "list-subscribe-bulk", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "example": { "inserts": 2 } } } }, "422": { "description": "422 Error", "content": { "application/json": { "example": { "errors": { "subscriber_data.0": { "email": [ "Invalid email address" ] }, "subscriber_data.1": { "email": [ "Invalid email address" ] } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriber_data": { "type": "array", "description": "Array of subscriber objects, each with email (required)" }, "update_existing": { "type": "boolean", "description": "Update existing subscribers.", "default": "true" }, "resubscribe": { "type": "boolean", "description": "Force re-subscribe.", "default": "false" }, "trigger_autoresponders": { "type": "boolean", "description": "Trigger automations.", "default": "false" } }, "required": [ "subscriber_data" ] } } } } } }, "/lists/{list_id}/segments": { "get": { "summary": "Get segments", "description": "Returns all segments for the specified list. Empty list returns {\"segments\":[]}.", "tags": [ "List Subscribers" ], "operationId": "list-segments", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "segments": { "5c36008811e45": { "name": "Segment 1", "id": "5c36008811e45", "count": 860 }, "5cbf2405a77ce": { "name": "Segment 2", "id": "5cbf2405a77ce", "count": 540 } } } } } } } } }, "/subscribers/{email}": { "get": { "summary": "Get subscriber details", "description": "Returns detailed subscriber information across all lists, including tags, ratings, last activity, and list-level details.", "tags": [ "Subscribers (Global)" ], "operationId": "sub-get", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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", "sms_status": 1 } } } } } } } } } }, "/subscribers/{email}/delete": { "delete": { "summary": "Delete subscriber", "description": "Permanently removes a subscriber from the database.", "tags": [ "Subscribers (Global)" ], "operationId": "sub-delete", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "deleted": true } } } } } } }, "/campaigns": { "get": { "summary": "List all campaigns", "description": "Returns all campaigns with pagination and filtering.", "tags": [ "Campaigns" ], "operationId": "camp-list", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": [ { "id": 1, "from_name": "From name", "from_email": "from@foo.cz", "reply_to": "reply@bar.cz", "title": "My first campaign", "subject": "First hello", "ga": "2014_09_08_My_first_campaign", "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", "attachments": null } ] } } } }, "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 (format: YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "filters[date_from]", "in": "query", "required": false, "description": "Filter campaigns updated from date (format: YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "filters[date_to]", "in": "query", "required": false, "description": "Filter campaigns updated to date (format: YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "filters[id]", "in": "query", "required": false, "description": "Filter by campaign ID", "schema": { "type": "integer" } } ] }, "post": { "summary": "Add new campaign", "description": "Creates a new campaign. For segment selection use: \"recepient_lists\":{\"segments\":[{\"id\":\"...\",\"list\":14}]}", "tags": [ "Campaigns" ], "operationId": "camp-create", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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", "archive_url": null } } } } } } }, "/campaigns/{id}": { "get": { "summary": "Get campaign detail", "description": "Returns full detail for a single campaign including aggregate stats.", "tags": [ "Campaigns" ], "operationId": "camp-get", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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 } ] }, "ga": "ga_tracking_code", "sent_at": "2025-01-10 08:30:00", "updated_at": "2025-01-10 07:15:00", "recipients": 100, "status": 3, "scheduled_at": null, "template_id": 62, "attachments": null, "campaign_type": "email", "headers": "x-header:header-value", "utm_source": null, "utm_medium": null, "archive_url": "https://foo.ecomailapp.cz/campaigns/render/1/randomhashhere", "stats": { "inject": 100, "send": 99, "delivered": 99, "sms_sent": 0, "sms_inv_nr": 0, "open": 40, "total_open": 45, "click": 12, "total_click": 15, "soft_bounce": 0, "hard_bounce": 1, "out_of_band": 0, "bounce": 1, "spam": 0, "unsub": 2, "conversions": 0, "conversions_value": 0, "conversions_average": 0, "clickrate": 12.12, "spamrate": 0, "unsubrate": 2.02, "delivery_rate": 99, "bouncerate": 1.01, "openrate": 40.4, "ctr": 30, "conversionrate": 0, "account": "foo", "campaign_id": 1, "not_opened": 59 } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID", "schema": { "type": "integer" } } ] } }, "/campaigns/{campaign_id}": { "put": { "summary": "Update campaign", "description": "Updates an existing campaign's properties.", "tags": [ "Campaigns" ], "operationId": "camp-update", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "id": 1, "from_name": "From name", "from_email": "from@foo.cz", "reply_to": "reply@bar.cz", "title": "My first campaign", "subject": "First hello", "ga": "ga_tracking_code", "status": 0, "template_id": 62, "archive_url": "https://foo.ecomailapp.cz/campaigns/render/1" } } } } } } }, "/campaign/{campaign_id}/send": { "get": { "summary": "Send campaign", "description": "Puts the campaign into the sending queue immediately. Only draft campaigns can be sent.", "tags": [ "Campaigns" ], "operationId": "camp-send", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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", "updated_at": "2022-08-24T09:37:36.454443Z", "archive_url": null } ] } } } } } }, "/campaigns/{campaign_id}/stats": { "get": { "summary": "Get campaign stats", "description": "Returns delivery, open, click, bounce, spam, and conversion statistics for a campaign.", "tags": [ "Campaigns" ], "operationId": "camp-stats", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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": { "summary": "Campaign stats detail", "description": "Returns per-subscriber event statistics (open, send, click, bounce, etc.) for a sent campaign.", "tags": [ "Campaigns" ], "operationId": "camp-stats-detail", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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, "spam_complaint": 0 }, "foo2@bar.com": { "open": 4, "send": 1, "unsub": 0, "soft_bounce": 0, "click": 2, "hard_bounce": 0, "out_of_band": 0, "spam": 0, "spam_complaint": 0 } } } } } } }, "parameters": [ { "name": "event", "in": "query", "required": false, "description": "Filter: open, send, unsub, soft_bounce, click, hard_bounce, out_of_band, spam", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Filter by email", "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "required": false, "description": "UTC format YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page, max 100.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer" } } ] } }, "/campaigns/segment/{segmentId}/stats": { "get": { "summary": "Segment stats across campaigns", "description": "Retrieves performance statistics for a segment across all campaigns it was sent to. Get the segment ID from the Show List endpoint.", "tags": [ "Campaigns" ], "operationId": "camp-segment-stats", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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, "total_click": 3, "total_open": 4, "unsub": 1, "unsub_rate": 25 } } } } } } } } }, "/pipelines": { "get": { "summary": "List all automations", "description": "Returns a list of all automations in the account.", "tags": [ "Automations" ], "operationId": "auto-list", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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/{pipeline_id}/trigger/": { "post": { "summary": "Trigger automation", "description": "Runs a specific automation for a subscriber.", "tags": [ "Automations" ], "operationId": "auto-trigger", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "email": "foo@bar.cz" } } } } } } }, "/pipelines/{pipeline_id}/stats": { "get": { "summary": "Get automation stats", "description": "Returns statistics for a specific automation, including sends, opens, clicks, bounces, and conversions.", "tags": [ "Automations" ], "operationId": "auto-stats", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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, "ctr": 0, "inject": 2, "soft_bounce": 0, "hard_bounce": 0, "bounce": 0, "bounce_rate": 0, "conversions": 0, "conversions_value": 0, "spam": 0, "unsub": 0, "sms_sent": 0, "delivery_rate": 100, "pipeline_id": 4, "account": "mujucet" } } } } } } } }, "/pipelines/{pipeline_id}/stats-detail": { "get": { "summary": "Automation stats detail", "description": "Returns per-subscriber event statistics for an automation.", "tags": [ "Automations" ], "operationId": "auto-stats-detail", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "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, "spam_complaint": 0 }, "foo2@bar.com": { "open": 5, "send": 3, "unsub": 0, "soft_bounce": 0, "click": 1, "hard_bounce": 0, "out_of_band": 0, "spam": 0, "spam_complaint": 0 } } } } } } }, "parameters": [ { "name": "event", "in": "query", "required": false, "description": "open, send, unsub, soft_bounce, click, hard_bounce, out_of_band, spam", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Filter by email", "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "required": false, "description": "YYYY-MM-DD (UTC)", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Max 5000 per page.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer" } } ] }, "post": { "summary": "Stats for multiple emails", "description": "Fetches detailed engagement statistics for multiple email addresses in an automation.", "tags": [ "Automations" ], "operationId": "auto-stats-emails", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "next_page_url": null, "total": 2, "per_page": 100, "subscribers": { "foo@bar.cz": { "open": 6, "send": 5, "unsub": 1, "click": 7, "hard_bounce": 0, "spam": 0, "mail_name": null }, "foo2@bar.cz": { "open": 4, "send": 4, "unsub": 0, "click": 8, "hard_bounce": 0, "spam": 0, "mail_name": null } } } } } } } } }, "/template": { "post": { "summary": "Create template", "description": "Creates a new email template.", "tags": [ "Templates" ], "operationId": "tmpl-create", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "id": 1, "name": "New Template", "html": "Template HTML" } } } } } } }, "/template/{id}": { "get": { "summary": "Get template", "description": "Returns a specific template with its HTML content.", "tags": [ "Templates" ], "operationId": "tmpl-get", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "id": 1234, "folder": 0, "name": "Some Template Name", "html": "Html code here...", "created_at": "2024-02-12 15:13:16", "updated_at": "2024-02-12 15:13:26" } } } } } } }, "/domains": { "get": { "summary": "List all domains", "description": "Returns all domains linked to the account.", "tags": [ "Domains" ], "operationId": "dom-list", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": [ { "id": 1, "name": "foo.cz", "valid": 1 }, { "id": 2, "name": "bar.cz", "valid": 0 } ] } } } } }, "post": { "summary": "Create domain", "description": "Adds a new sending domain.", "tags": [ "Domains" ], "operationId": "dom-create", "responses": { "201": { "description": "Response 201", "content": { "application/json": { "example": { "id": 1, "name": "newdomain.cz", "valid": 0 } } } } } } }, "/domains/{domain_id}": { "delete": { "summary": "Delete domain", "description": "Removes a sending domain.", "tags": [ "Domains" ], "operationId": "dom-delete", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "id": 1, "name": "newdomain.cz", "valid": 0 } } } } } } }, "/transactional/send-message": { "post": { "summary": "Send transactional email", "description": "Sends a transactional email with custom HTML content.", "tags": [ "Transactional Emails" ], "operationId": "tx-send", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "results": { "total_rejected_recipients": 0, "total_accepted_recipients": 2, "id": 11668787484950529 } } } } } } } }, "/transactional/send-template": { "post": { "summary": "Send transactional template", "description": "Sends a transactional email using a pre-built template.", "tags": [ "Transactional Emails" ], "operationId": "tx-template", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "results": { "total_rejected_recipients": 0, "total_accepted_recipients": 2, "id": 11668787484950529 } } } } } } } }, "/transactional/stats": { "get": { "summary": "Transactional email stats", "description": "Statistics for transactional emails for the past 6 months.", "tags": [ "Transactional Emails" ], "operationId": "tx-stats", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "stats": { "open_rate": 85.71, "click_rate": 0, "ctr": 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": { "summary": "Double opt-in stats", "description": "Statistics for double opt-in emails for the past 6 months.", "tags": [ "Transactional Emails" ], "operationId": "tx-doi-stats", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "stats": { "open_rate": 69.34, "click_rate": 81.01, "ctr": 116.83, "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": { "summary": "Add transaction", "description": "Creates a new e-commerce transaction with items.", "tags": [ "Transactions" ], "operationId": "trx-create", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "example": { "order_id": "transaction_1234", "email": "foo@bar.cz", "shop": "myshop.cz", "amount": 1500, "tax": 200, "shipping": 100, "city": "Praha", "county": "Hlavni mesto Praha", "country": "Ceska republika", "timestamp": "2015-09-10 17:25:35", "id": 1, "status": "completed" } } } }, "422": { "description": "422 Error", "content": { "application/json": { "example": { "errors": { "transaction.order_id": [ "The transaction.order id has already been taken." ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Transaction ID" }, "email": { "type": "string", "description": "Subscriber's email" }, "shop": { "type": "string", "description": "Shop name (case sensitive, required for segmentation)" }, "amount": { "type": "integer", "description": "Quantity" }, "status": { "type": "string", "description": "processing, canceled, pending, completed, null" }, "timestamp": { "type": "integer", "description": "Unix timestamp" }, "props": { "type": "string", "description": "Custom properties for conditionals" }, "code": { "type": "string", "description": "Product code" }, "title": { "type": "string", "description": "Product name" }, "categories": { "type": "array", "description": "Product categories (max 100 chars each, 20 per item)" }, "price": { "type": "number", "description": "Total price for quantity" }, "tags": { "type": "array", "description": "Product tags (max 5000 chars/account)" } }, "required": [ "order_id", "email" ] } } } } }, "get": { "summary": "Get transactions", "description": "Returns a paginated list of transactions with optional filters.", "tags": [ "Transactions" ], "operationId": "trx-get", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "current_page": 1, "data": [ { "id": 2220, "order_id": "5301", "email": "foo@bar.cz", "shop": "mujshop.cz", "amount": 2000, "tax": 200, "shipping": 100, "city": "Praha", "timestamp": "2023-02-15 09:40:56", "status": null, "items": [ { "code": "product code 1", "title": "product name 1", "categories": [ "product category 1", "Size S" ], "price": 400, "amount": "1", "tags": [ "S", "3+", "puzzle" ] } ] } ], "per_page": 100, "total": 234 } } } } }, "parameters": [ { "name": "shop", "in": "query", "required": false, "description": "Exact shop name match", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Filter by email", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Max 500 per page", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer" } } ] } }, "/tracker/transaction-bulk": { "post": { "summary": "Add bulk transactions", "description": "Creates multiple transactions at once.", "tags": [ "Transactions" ], "operationId": "trx-bulk", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "inserts": 2 } } } } } } }, "/tracker/transaction/{order_id}": { "put": { "summary": "Update transaction", "description": "Overwrites the order with new data from the request.", "tags": [ "Transactions" ], "operationId": "trx-update", "responses": { "200": { "description": "Success" } } } }, "/tracker/transaction/{order_id}/delete": { "delete": { "summary": "Delete transaction", "description": "Deletes a single transaction. Optionally specify a shop to target.", "tags": [ "Transactions" ], "operationId": "trx-delete", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "deleted": true } } } } } } }, "/tracker/transaction/delete-bulk": { "delete": { "summary": "Delete bulk transactions", "description": "Deletes multiple transactions at once.", "tags": [ "Transactions" ], "operationId": "trx-delete-bulk", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "example": { "deleted": 2 } } } }, "422": { "description": "422 Error", "content": { "application/json": { "example": { "errors": { "transaction_data": [ "The transaction data may not have more than 1000 items." ] } } } } } } } }, "/feeds/{feed_id}/refresh": { "get": { "summary": "Refresh product feed", "description": "Refreshes a product feed. Limited to 1 refresh/hour, only for feeds <50,000 products.", "tags": [ "Feeds" ], "operationId": "feed-product", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "example": { "message": "Your feed is being refreshed" } } } }, "403": { "description": "403 Forbidden", "content": { "application/json": { "example": { "errors": "Account must be marketer+ tariff" } } } } } } }, "/data-feeds/{feed_id}/refresh": { "get": { "summary": "Refresh data feed", "description": "Refreshes a data feed. Limited to 1 refresh/hour, only for feeds <50,000 items.", "tags": [ "Feeds" ], "operationId": "feed-data", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "example": { "message": "Your feed is being refreshed" } } } }, "403": { "description": "403", "content": { "application/json": { "example": { "errors": "Account must be marketer+ tariff" } } } }, "422": { "description": "422", "content": { "application/json": { "example": { "errors": "Feed can be refreshed just once per hour" } } } } } } }, "/tracker/events": { "post": { "summary": "Create event", "description": "Creates a new tracking event for a subscriber.", "tags": [ "Tracker / Events" ], "operationId": "tracker-event", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "id": 1234, "email": "foo@bar.cz", "category": "category", "action": "action", "label": "label", "property": "property", "value": "value" } } } } } } }, "/search": { "post": { "summary": "Find contact", "description": "Searches for a subscriber by email across all lists. The query field must contain a valid email address.", "tags": [ "Search" ], "operationId": "search-contact", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": [ { "email": "foo@bar.cz", "list_id": 1, "status": 2, "name": "Foo", "surname": "Bar", "city": "Praha", "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" }, { "email": "foo@bar.cz", "list_id": 2, "status": 1, "name": "Foo", "surname": "Bar", "source": "API", "subscribed_at": "2024-02-27T10:58:37.000000Z", "unsubscribed_at": null } ] } } } } } }, "/coupons/import": { "post": { "summary": "Import coupons", "description": "Import discount coupons into a default or specific folder.", "tags": [ "Discount Coupons" ], "operationId": "coupon-import", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "imported": 4, "duplicated": 0, "totalCount": 4 } } } } } } }, "/coupons/delete": { "delete": { "summary": "Delete coupons", "description": "Delete discount coupons from a default or specific folder.", "tags": [ "Discount Coupons" ], "operationId": "coupon-delete", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "deleted": 4, "invalid": 0 } } } } } } }, "/account/settings/webhook": { "post": { "summary": "Set webhook URL", "description": "Sets the target webhook URL. An example request is sent to the URL upon creation.", "tags": [ "Webhook" ], "operationId": "wh-set", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "success": true } } } } } }, "get": { "summary": "Get webhook URL", "description": "Returns the currently configured webhook URL.", "tags": [ "Webhook" ], "operationId": "wh-get", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "webhook": { "url": "https://your-webhook-url.com" } } } } } } }, "delete": { "summary": "Delete webhook URL", "description": "Removes the configured webhook URL.", "tags": [ "Webhook" ], "operationId": "wh-delete", "responses": { "200": { "description": "Response 200", "content": { "application/json": { "example": { "success": true } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "key", "description": "API key obtained from Ecomail account settings." } } } }