{ "openapi": "3.1.0", "info": { "title": "Mailercloud Marketing API", "version": "1.0.0", "description": "Campaigns, contacts, lists, segments, automations, and webhooks for the Mailercloud Marketing Platform." }, "servers": [ { "url": "https://cloudapi.mailercloud.com/v1" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Your Mailercloud API key (plain text, no Bearer prefix). Create keys in Settings \u2192 API." } } }, "paths": { "/campaign": { "post": { "summary": "Create Campaign", "operationId": "create-campaign", "description": "> A newer version of this endpoint with more options is available: [Create Campaign (v2)](/api-reference/campaigns/create-campaign-v2).\n\nAPI for creating an email campaign. For creating a campaign, HTML or plain text and list id or segment are mandatory.", "tags": [ "Campaigns" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "list_ids", "name", "sender", "subject" ], "properties": { "email_preheader": { "type": "string", "minLength": 1, "description": "Email preheader is the summary text that follows a subject line when the email is viewed in an inbox. In many cases, it\u2019s used to provide a short summary of the email, and is typically one sentence long.\n\nMinimum: 1\n\nMaximum: 150" }, "html": { "type": "string", "minLength": 1, "description": "HTML template content for your email campaign." }, "list_ids": { "type": "array", "description": "Recipients of your email campaign.", "items": { "type": "string", "description": "List of contact lists ids, to which you want to send your campaign. \n\nFormat: Array of strings." } }, "mailing_preference": { "type": "boolean", "description": "true - Mailing preference option will be displayed in footer of email campaign template.\n\nfalse - Mailing preference option will not be dispalyed.", "default": true }, "name": { "type": "string", "minLength": 1, "description": "Name of the campaign.\n\nMinimum: 1\n\nMaximum: 150" }, "pause_rules": { "type": "object", "description": "Optional\n\nIf you want to set a rule for sending a campaign, use this option. Based on the configured rule, the campaign will be sent.", "required": [ "pause_condition", "pause_criteria", "pause_limit", "pause_target", "wait_time" ], "properties": { "pause_condition": { "type": "string", "minLength": 1, "description": "Rule for setting open or click percentage greater than or less than pause target.\n\nSupported pause_condition - greater than, less than" }, "pause_criteria": { "type": "string", "minLength": 1, "description": "Supported pause_criteria - open, click" }, "pause_limit": { "type": "number", "description": "The percentage of list contacts to which we want to send campaigns first. In the order we set in rules.\n\nMinimum: 1\n\nMaximum: 50" }, "pause_target": { "type": "number", "description": "Value of open/click (in percentage) to be achieved.\n\nMinimum: 1\n\nMaximum: 100" }, "wait_time": { "type": "number", "description": "After getting click rate or open rate grater than or less than pause limit , How many time we have to wait to send campaign to other contacts in the list.\n\nWait time in minutes .\n\nMinimum: 1\n\nMaximum: 43200" } } }, "permission_reminder": { "type": "string", "minLength": 1, "description": "The email disclaimer content in your email campaign. If you want give unsubscribe link give %%unsubscribe%%\n\nMinimum: 1\n\nMaximum: 150" }, "plain_text": { "type": "string", "minLength": 1, "description": "Plain text content of your email campaign." }, "reply_email": { "type": "string", "minLength": 1, "description": "Email on which the campaign recipients will be able to reply to. If replay_email empty then sender email will be the reply email." }, "report_spam": { "type": "boolean", "description": "Spam reporting enable or disable.", "default": true }, "rules": { "type": "object", "properties": { "limit": { "type": "number", "description": "Count of subscribers in list to which campaign sends based on the contacts_order." }, "contacts_order": { "type": "string", "description": "The order of contact list in which you want to send your email campaign.\n\nSupported: first,last" } } }, "scheduled_at": { "type": "string", "minLength": 1, "description": "Schedule time for your email campaign. Pass your timezone date-time format for accurate results.\n\nFormat: 2021-04-23 15:04:05" }, "segments": { "type": "string", "minLength": 1, "description": "Your recipient segment id." }, "sender": { "type": "object", "required": [ "sender_email", "sender_name" ], "properties": { "sender_email": { "type": "string", "minLength": 1, "description": "From email for your email campaign." }, "sender_name": { "type": "string", "minLength": 1, "description": "From name for email campaign.\n\nMaximum: 100" } } }, "subject": { "type": "string", "minLength": 1, "description": "Subject of the campaign.\n\nMinimum: 1\n\nMaximum: 150" }, "viewin_browser": { "type": "boolean", "description": "true: Enable the \"View this email in your browser\" in Campaign preview page.\n\nfalse: Disable the \"View this email in your browser\" in Campaign preview page.", "default": true } } }, "examples": { "example-1": { "value": { "html": " Sample HTML ", "list_ids": [ "sCVJ", "ghy" ], "name": "Campaign name", "sender": { "sender_email": "sender@yourdomain.com", "sender_name": "Sender Name" }, "scheduled_at": "2021-04-17 15:48:00", "subject": "Prime member notification." } }, "example-2": { "value": { "email_preheader": "Prime member: You have an unused Prime benefit", "rules": { "contacts_order": "last", "limit": 5 }, "report_spam": false, "mailing_preference": false, "name": "Campaign name", "pause_rules": { "pause_limit": 1, "pause_criteria": "open", "pause_condition": "greater than", "pause_target": 1, "wait_time": 10 }, "permission_reminder": "If you wish to opt out of all type of emails, click Unsubscribe. ", "plain_text": "plain text", "reply_email": "sender@yourdomain.com", "sender": { "sender_email": "sender@yourdomain.com", "sender_name": "Sender Name" }, "segments": "hju", "subject": "Prime member notification.", "viewin_browser": false } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {} }, "examples": { "example-1": { "value": { "id": "hdjh" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "sender_email", "message": "sender_email must be a valid email address" }, { "field": "reply_email", "message": "reply_email must be a valid email address" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/campaign/save": { "post": { "summary": "Create Campaign (v2)", "operationId": "create-campaign-v2", "description": "**The newer version of Create Campaign with additional options \u2014 prefer this endpoint for new integrations.**\n\n**Required:** `name`, `subject`, and `sender` (with `sender_name` + `sender_email`). **Content:** provide `html` or `plain_text`. **Audience:** provide at least one of `list_ids`, `segments`, or `tag_ids`.", "tags": [ "Campaigns" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email_preheader": { "type": "string" }, "exclude_list_ids": { "type": "array", "items": { "type": "string" } }, "exclude_segments": { "type": "array", "items": { "type": "string" } }, "exclude_tag_ids": { "type": "array", "items": { "type": "string" } }, "frequency_cap": { "type": "string" }, "html": { "type": "string" }, "is_publish": { "type": "string", "enum": [ "0", "1" ], "description": "`\"1\"` publishes/schedules the campaign; `\"0\"` saves it as a draft." }, "list_ids": { "type": "array", "items": { "type": "string" } }, "mailing_preference": { "type": "boolean" }, "name": { "type": "string", "maxLength": 150, "minLength": 1 }, "pause_rules": { "type": "object", "properties": { "pause_condition": { "type": "string", "enum": [ "greater than", "less than" ] }, "pause_criteria": { "type": "string", "enum": [ "open", "click" ] }, "pause_limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "pause_target": { "type": "integer", "minimum": 1, "maximum": 100 }, "wait_time": { "type": "integer", "minimum": 1, "maximum": 43200, "description": "Minutes to wait before evaluating pause rules (max 30 days)." } } }, "permission_reminder": { "type": "string" }, "plain_text": { "type": "string" }, "reply_email": { "type": "string" }, "reply_id": { "type": "string" }, "report_spam": { "type": "boolean" }, "rules": { "type": "object", "properties": { "contacts_order": { "type": "string", "enum": [ "first", "last" ] }, "limit": { "type": "integer" } } }, "scheduled_at": { "type": "string", "description": "Schedule time in `YYYY-MM-DD HH:MM:SS` format. Omit to send according to `is_publish`." }, "segments": { "type": "array", "items": { "type": "string" } }, "sender": { "type": "object", "properties": { "sender_email": { "type": "string", "format": "email" }, "sender_name": { "type": "string", "maxLength": 100 } }, "required": [ "sender_name", "sender_email" ] }, "sender_id": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string", "maxLength": 65000, "minLength": 1 }, "tag_id": { "type": "string" }, "tag_ids": { "type": "array", "items": { "type": "string" } }, "tag_name": { "type": "string" } }, "x-examples": { "Example 1": { "email_preheader": "string", "exclude_list_ids": [ "string" ], "exclude_segments": [ "string" ], "exclude_tag_ids": [ "string" ], "frequency_cap": "string", "html": "string", "is_publish": "string", "list_ids": [ "string" ], "mailing_preference": true, "name": "string", "pause_rules": { "pause_condition": "string", "pause_criteria": "string", "pause_limit": 0, "pause_target": 0, "wait_time": 0 }, "permission_reminder": "string", "plain_text": "string", "reply_email": "string", "reply_id": "string", "report_spam": true, "rules": { "contacts_order": "string", "limit": 0 }, "scheduled_at": "string", "segments": [ "string" ], "sender": { "sender_email": "string", "sender_name": "string" }, "sender_id": [ "string" ], "subject": "string", "tag_id": "string", "tag_ids": [ "string" ], "tag_name": "string" } }, "required": [ "name", "subject", "sender" ] }, "examples": { "example-1": { "value": { "email_preheader": "Prime member: You have an unused Prime benefit", "exclude_list_ids": [ "123", "456" ], "exclude_segments": [ "segment1", "segment2" ], "exclude_tag_ids": [ "tag1", "tag2" ], "frequency_cap": "daily", "html": "Sample HTML", "is_publish": "1", "list_ids": [ "sCVJ", "ghy" ], "mailing_preference": true, "name": "Campaign name", "pause_rules": { "pause_condition": "greater than", "pause_criteria": "open", "pause_limit": 1, "pause_target": 1, "wait_time": 10 }, "permission_reminder": "If you wish to opt out of all types of emails, click Unsubscribe.", "plain_text": "Plain text content", "reply_email": "sender@yourdomain.com", "reply_id": "reply-id-1", "report_spam": false, "rules": { "contacts_order": "last", "limit": 5 }, "scheduled_at": "2021-04-17 15:48:00", "segments": [ "hju" ], "sender": { "sender_email": "sender@yourdomain.com", "sender_name": "Sender Name" }, "sender_id": [ "sender-123" ], "subject": "Prime member notification.", "tag_id": "prime-tag", "tag_ids": [ "tag-123", "tag-456" ], "tag_name": "Prime Campaign Tag" } }, "example-2": { "value": { "email_preheader": "Your weekly newsletter is here!", "exclude_list_ids": [ "exclude-list-1" ], "exclude_segments": [ "exclude-segment-1" ], "exclude_tag_ids": [ "exclude-tag-1" ], "frequency_cap": "weekly", "html": "Weekly newsletter content", "is_publish": "0", "list_ids": [ "list1", "list2" ], "mailing_preference": false, "name": "Weekly Newsletter", "pause_rules": { "pause_condition": "less than", "pause_criteria": "click", "pause_limit": 3, "pause_target": 2, "wait_time": 20 }, "permission_reminder": "You are receiving this email because you subscribed to our newsletter.", "plain_text": "Plain text newsletter content", "reply_email": "newsletter@yourdomain.com", "reply_id": "reply-id-2", "report_spam": true, "rules": { "contacts_order": "first", "limit": 10 }, "scheduled_at": "2022-01-10 10:00:00", "segments": [ "segment1", "segment2" ], "sender": { "sender_email": "newsletter@yourdomain.com", "sender_name": "MailerCloud Team" }, "sender_id": [ "sender-456" ], "subject": "Weekly Newsletter", "tag_id": "newsletter-tag", "tag_ids": [ "tag-789", "tag-101" ], "tag_name": "Newsletter Tag" } } } } } }, "responses": { "201": { "description": "{\n \"id\": \"a\"\n}", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the created campaign." } } }, "examples": { "created": { "value": { "id": "aBc12" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "sender_email", "message": "sender_email must be a valid email address" }, { "field": "reply_email", "message": "reply_email must be a valid email address" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } }, "servers": [ { "url": "https://cloudapi.mailercloud.com/v2" } ] } }, "/campaign/domain/report/{id}": { "post": { "summary": "Campaign Domain Report", "operationId": "get-statistics-for-the-top-performing-email-domains-in-a-campaign", "description": "This report contains statistics for the top-performing email domains in a campaign. The domains report allows you to break down your customers into groups according to their mailbox service provider.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum number of elements to return.\n\nMaximum: 100 Minimum: 10" }, "page": { "type": "number", "description": "You can retrieve a subset of records starting from the page value you have specified. You can add a limit, which will determine the number of records you can retrieve on a single page.\n\nStarts From: 1" }, "sort_field": { "type": "string", "minLength": 1, "description": "Sort list data based on this field\n\nAvailable sort fields\n\ndomain,sent,soft_bounce,hard_bounce,opens,\nclicks,unsubscribe,abuse,spam_complaints" }, "sort_order": { "type": "string", "minLength": 1, "description": "Sorting order for sort field\n\nAvailable sort orders\n\nasc, ASC, desc, DESC" } }, "required": [ "limit", "page" ] }, "examples": { "example-1": { "value": { "limit": 10, "page": 1, "sort_field": "sent", "sort_order": "asc" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "count": { "type": "number" }, "data": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "abuse": { "type": "number" }, "abuse_pct": { "type": "string", "minLength": 1 }, "clicks": { "type": "number" }, "clicks_pct": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "minLength": 1 }, "hard_bounce": { "type": "number" }, "hard_bounce_pct": { "type": "string", "minLength": 1 }, "opens": { "type": "number" }, "opens_pct": { "type": "string", "minLength": 1 }, "sent": { "type": "number" }, "sent_pct": { "type": "string", "minLength": 1 }, "soft_bounce": { "type": "number" }, "soft_bounce_pct": { "type": "string", "minLength": 1 }, "spam_complaints": { "type": "number" }, "spam_complaints_pct": { "type": "string", "minLength": 1 }, "unsubscribe": { "type": "number" }, "unsubscribe_pct": { "type": "string", "minLength": 1 } } } }, "name": { "type": "string", "minLength": 1 } } }, "examples": { "example-1": { "value": { "count": 1, "data": [ { "abuse": 0, "abuse_pct": "0.00", "clicks": 0, "clicks_pct": "0.00", "domain": "bulk.regalwork.com", "hard_bounce": 0, "hard_bounce_pct": "0.00", "opens": 15548, "opens_pct": "15.54", "sent": 100000, "sent_pct": "100.00", "soft_bounce": 0, "soft_bounce_pct": "0.00", "spam_complaints": 0, "spam_complaints_pct": "0.00", "unsubscribe": 307, "unsubscribe_pct": "1.97" } ], "name": "Campaign name" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "sort_order", "message": "Invalid sort_order" } } } } } } }, "401": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/campaign/list": { "post": { "summary": "Campaign List", "operationId": "campaign-list", "description": "Get the details of all the campaigns you have created.", "tags": [ "Campaigns" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "date_from": { "type": "string", "minLength": 1, "description": "When the campaign type is a draft or duplicate, date_from checks modified date; otherwise, date_from checks your scheduled date.\n\nFormat Y-m-d." }, "date_to": { "type": "string", "minLength": 1, "description": "When the campaign type is a draft or duplicate, date_to checks modified date; otherwise, date_to checks your scheduled date.\n\nFormat Y-m-d." }, "limit": { "type": "number", "description": "Maximum number of elements to return.\n\nMaximum: 100 Minimum: 10" }, "page": { "type": "number", "description": "You can retrieve a subset of records starting from the page value you have specified. You can add a limit, which will determine the number of records you can retrieve on a single page.\n\nStarts From: 1" }, "search": { "type": "string", "minLength": 1, "description": "Filter campaign list by campaign name" }, "sender_email": { "type": "string", "minLength": 1, "description": "Filter campaign list by sender email." }, "sort_field": { "type": "string", "minLength": 1, "description": "Sort list data based on the following field.\n\nAvailable sort fields\nname,schedule_date,open_percentage,\nmodified_date,clicks,opens,sent,unsubscribe" }, "sort_order": { "type": "string", "minLength": 1, "description": "Sorting order for sort field\n\nAvailable sort orders\n\nasc, ASC, desc, DESC " }, "status": { "type": "string", "minLength": 1, "description": "Filter campaign list by campaign status\n\nAvailable statuses\n\nProcessing,Queued,Sending,Paused,Finished,\nAborted,Duplicate,Draft,Scheduled,Rescheduled,Failed\n" } }, "required": [ "limit", "page" ] }, "examples": { "example-1": { "value": { "date_from": "2021-03-01", "date_to": "2021-04-30", "limit": 10, "page": 1, "search": "", "sender_email": "", "sort_field": "name", "sort_order": "asc", "status": "" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "count": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "count": { "type": "number" } } } }, "data": { "type": "object", "properties": { "0": { "type": "object", "properties": { "blacklisted_domains": { "type": "object" }, "broken_links": { "type": "object" }, "conversion_tracking": { "type": "object" }, "created_date": { "type": "string", "minLength": 1 }, "email_preheader": { "type": "string", "minLength": 1 }, "finish_date": { "type": "string", "minLength": 1 }, "html": { "type": "string" }, "modified_date": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "pause_rules": { "type": "object" }, "permission_reminder": { "type": "string" }, "plain_text": { "type": "string" }, "recepiant": { "type": "object", "properties": { "lists": { "type": "string", "minLength": 1 }, "lists_contact_count": { "type": "number" }, "segments": { "type": "string" }, "segments_contact_count": { "type": "number" }, "total_lists": { "type": "number" } } }, "reply_email": { "type": "string", "minLength": 1 }, "report_abuse": { "type": "boolean" }, "report_summary": { "type": "object", "properties": { "abuse": { "type": "number" }, "abuse_percentage": { "type": "string", "minLength": 1 }, "clicks": { "type": "number" }, "clicks_percentage": { "type": "string", "minLength": 1 }, "conversions": { "type": "number" }, "conversions_percentage": { "type": "string", "minLength": 1 }, "delivered": { "type": "number" }, "delivered_percentage": { "type": "string", "minLength": 1 }, "hard_bounce": { "type": "number" }, "hard_bounce_percentage": { "type": "string", "minLength": 1 }, "open_percentage": { "type": "string", "minLength": 1 }, "opens": { "type": "number" }, "queue": { "type": "number" }, "queue_percentage": { "type": "string", "minLength": 1 }, "queued_total": { "type": "number" }, "sent": { "type": "number" }, "sent_percentage": { "type": "string", "minLength": 1 }, "soft_bounce": { "type": "number" }, "soft_bounce_percentage": { "type": "string", "minLength": 1 }, "spam_complaints_count": { "type": "number" }, "spam_complaints_percentage": { "type": "string", "minLength": 1 }, "unsubscribe": { "type": "number" }, "unsubscribe_percentage": { "type": "string", "minLength": 1 } } }, "rule": { "type": "object", "properties": { "contacts_order": { "type": "string", "minLength": 1 }, "limit": { "type": "string" } } }, "scheduled_date": { "type": "object", "properties": { "date": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 } } }, "sender": { "type": "object", "properties": { "sender_email": { "type": "string", "minLength": 1 }, "sender_name": { "type": "string", "minLength": 1 } } }, "start_date": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "status_change_date": { "type": "string", "minLength": 1 }, "status_change_message": { "type": "string" }, "subject": { "type": "string", "minLength": 1 }, "tag": { "type": "string", "minLength": 1 }, "time_rule": { "type": "object" }, "type": { "type": "string", "minLength": 1 } } }, "1": { "type": "object", "properties": { "blacklisted_domains": { "type": "object" }, "broken_links": { "type": "object" }, "conversion_tracking": { "type": "object" }, "created_date": { "type": "string", "minLength": 1 }, "email_preheader": { "type": "string", "minLength": 1 }, "finish_date": { "type": "string", "minLength": 1 }, "html": { "type": "string" }, "modified_date": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "pause_rules": { "type": "object" }, "permission_reminder": { "type": "string" }, "plain_text": { "type": "string" }, "recepiant": { "type": "object", "properties": { "lists": { "type": "string", "minLength": 1 }, "lists_contact_count": { "type": "number" }, "segments": { "type": "string" }, "segments_contact_count": { "type": "number" }, "total_lists": { "type": "number" } } }, "reply_email": { "type": "string", "minLength": 1 }, "report_abuse": { "type": "boolean" }, "report_summary": { "type": "object", "properties": { "abuse": { "type": "number" }, "abuse_percentage": { "type": "string", "minLength": 1 }, "clicks": { "type": "number" }, "clicks_percentage": { "type": "string", "minLength": 1 }, "conversions": { "type": "number" }, "conversions_percentage": { "type": "string", "minLength": 1 }, "delivered": { "type": "number" }, "delivered_percentage": { "type": "string", "minLength": 1 }, "hard_bounce": { "type": "number" }, "hard_bounce_percentage": { "type": "string", "minLength": 1 }, "open_percentage": { "type": "string", "minLength": 1 }, "opens": { "type": "number" }, "queue": { "type": "number" }, "queue_percentage": { "type": "string", "minLength": 1 }, "queued_total": { "type": "number" }, "sent": { "type": "number" }, "sent_percentage": { "type": "string", "minLength": 1 }, "soft_bounce": { "type": "number" }, "soft_bounce_percentage": { "type": "string", "minLength": 1 }, "spam_complaints_count": { "type": "number" }, "spam_complaints_percentage": { "type": "string", "minLength": 1 }, "unsubscribe": { "type": "number" }, "unsubscribe_percentage": { "type": "string", "minLength": 1 } } }, "rule": { "type": "object", "properties": { "contacts_order": { "type": "string", "minLength": 1 }, "limit": { "type": "string" } } }, "scheduled_date": { "type": "object", "properties": { "date": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 } } }, "sender": { "type": "object", "properties": { "sender_email": { "type": "string", "minLength": 1 }, "sender_name": { "type": "string", "minLength": 1 } } }, "start_date": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "status_change_date": { "type": "string", "minLength": 1 }, "status_change_message": { "type": "string" }, "subject": { "type": "string", "minLength": 1 }, "tag": { "type": "string", "minLength": 1 }, "time_rule": { "type": "object" }, "type": { "type": "string", "minLength": 1 } } } } } } }, "examples": { "example-1": { "value": { "count": [ { "count": 2 } ], "data": { "0": { "blacklisted_domains": {}, "broken_links": {}, "conversion_tracking": {}, "created_date": "2021-04-27 11:31:04", "email_preheader": "Save more on your Home & Kitchen shopping", "finish_date": "2021-04-27 15:07:02", "html": "", "id": "BBBghIFI", "modified_date": "2021-04-27 11:44:15", "name": "Offer Of The Day", "pause_rules": {}, "permission_reminder": "", "plain_text": "", "recepiant": { "lists": "Subscriber list", "lists_contact_count": 100000, "segments": "", "segments_contact_count": 0, "total_lists": 1 }, "reply_email": "sender@yourdomain.com", "report_abuse": true, "report_summary": { "abuse": 0, "abuse_percentage": "0.00", "clicks": 0, "clicks_percentage": "0.00", "conversions": 0, "conversions_percentage": "0.00", "delivered": 100000, "delivered_percentage": "100.00", "hard_bounce": 0, "hard_bounce_percentage": "0.00", "open_percentage": "15.55", "opens": 15548, "queue": 0, "queue_percentage": "0.00", "queued_total": 100000, "sent": 100000, "sent_percentage": "100.00", "soft_bounce": 0, "soft_bounce_percentage": "0.00", "spam_complaints_count": 0, "spam_complaints_percentage": "0.00", "unsubscribe": 307, "unsubscribe_percentage": "1.97" }, "rule": { "contacts_order": "first", "limit": "" }, "scheduled_date": { "date": "2021-04-27 17:14:15", "timezone": "Asia/Kolkata" }, "sender": { "sender_email": "sender@yourdomain.com", "sender_name": "Sender Name Shan" }, "start_date": "2021-04-27 11:47:04", "status": "Finished", "status_change_date": "2021-04-27 15:07:02", "status_change_message": "", "subject": "Amazon offers", "tag": "Amazon offers", "time_rule": {}, "type": "Normal campaign" }, "1": { "blacklisted_domains": {}, "broken_links": {}, "conversion_tracking": {}, "created_date": "2021-04-27 11:31:04", "email_preheader": "How To Make Veg Pizza", "finish_date": "2021-04-27 15:07:02", "html": "", "id": "BBBghIFI", "modified_date": "2021-04-27 11:44:15", "name": "Offer Of The Day", "pause_rules": {}, "permission_reminder": "", "plain_text": "", "recepiant": { "lists": "newsletter subscriber list", "lists_contact_count": 100000, "segments": "", "segments_contact_count": 0, "total_lists": 1 }, "reply_email": "sender@yourdomain.com", "report_abuse": true, "report_summary": { "abuse": 0, "abuse_percentage": "0.00", "clicks": 0, "clicks_percentage": "0.00", "conversions": 0, "conversions_percentage": "0.00", "delivered": 100000, "delivered_percentage": "100.00", "hard_bounce": 0, "hard_bounce_percentage": "0.00", "open_percentage": "15.55", "opens": 15548, "queue": 0, "queue_percentage": "0.00", "queued_total": 100000, "sent": 100000, "sent_percentage": "100.00", "soft_bounce": 0, "soft_bounce_percentage": "0.00", "spam_complaints_count": 0, "spam_complaints_percentage": "0.00", "unsubscribe": 307, "unsubscribe_percentage": "1.97" }, "rule": { "contacts_order": "first", "limit": "" }, "scheduled_date": { "date": "2021-04-27 17:14:15", "timezone": "Asia/Kolkata" }, "sender": { "sender_email": "sender@yourdomain.com", "sender_name": "Sender Name Shan" }, "start_date": "2021-04-27 11:47:04", "status": "Finished", "status_change_date": "2021-04-27 15:07:02", "status_change_message": "", "subject": "Pizza", "tag": "Pizz noodles", "time_rule": {}, "type": "Normal campaign" } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "sort_order", "message": "Invalid sort_order" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/campaign/testmail-groups/list": { "post": { "summary": "Testmail Group List", "operationId": "testmail-group-list", "description": "Get the details of all the testmail groups you have created.", "tags": [ "Campaigns" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string" } }, "x-examples": { "Example 1": { "search": "dkjdkjdkjdss" } } }, "examples": { "example-1": { "value": { "search": "group_name/email" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "group_name": { "type": "string" } } } } }, "x-examples": { "Example 1": { "data": [ { "emails": [ "test@vinmail.io", "hii@vinmail.io", "bii@vinmail.io", "sdjfhjk@vinmail.io", "nii@vinmail.io", "live@vinmail.io" ], "group_name": "Most" }, { "emails": [ "test@vinmail.io", "hii@vinmail.io", "bii@vinmail.io", "sdjfhjk@vinmail.io" ], "group_name": "Name" }, { "emails": [ "test@vinmail.io", "hii@vinmail.io", "bii@vinmail.io" ], "group_name": "Group" }, { "emails": [ "test@vinmail.io", "hii@vinmail.io" ], "group_name": "New" }, { "emails": [ "test@vinmail.io" ], "group_name": "Test" }, { "emails": [ "test@vinmail.io" ], "group_name": "dkjdkjdkjdss" } ] } } }, "examples": { "example-1": { "value": { "data": [ { "emails": [ "sender@yourdomain.com", "jacobwilson@gmail.com", "harrybrook@yahoo.com" ], "group_name": "Demo Group", "id": "SS" }, { "emails": [ "sender@yourdomain.com" ], "group_name": "Demo", "id": "SK" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "-", "message": "Invalid input" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/campaign/schedule/{id}": { "post": { "summary": "Schedule Campaign", "operationId": "schedule-campaign", "description": "API for scheduling campaign. If the schedule_at is not given, the campaign will schedule for the current time.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign Id", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "scheduled_at": { "type": "string", "minLength": 1, "description": "Schedule time for your email campaign. Pass your timezone date-time format for accurate results.\n\nFormat: 2021-04-23 15:04:05" } } }, "examples": { "example-1": { "value": { "scheduled_at": "2021-04-17 15:48:00" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "message": "Campaign has been scheduled" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "scheduled_at", "message": "scheduled_at does not match the YYYY-MM-DD hh:mm:ss format" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } } }, "/campaign/testmail/{id}": { "post": { "summary": "Send a Test Email", "operationId": "send-a-test-email", "description": "Send a test email.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign Id", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "testmail_group": { "type": "string" } }, "x-examples": { "Example 1": { "email": "qa1@vinmail.io", "testmail_group": "dkjdkjdkjdss" } } }, "examples": { "example-1": { "value": { "email": "sender@yourdomain.com", "testmail_group": "group_name/group_id" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "message": { "type": "string", "minLength": 1 } } }, "examples": { "example-1": { "value": { "message": "Test mail was successfully sent" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "email", "message": "Email must be a valid email address" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "id", "message": "Record not found with the given Id" } } } } } } } } } }, "/campaign/{id}": { "get": { "summary": "Get Single Campaign Details", "operationId": "get-single-campaign-details", "description": "Get the details of a single campaign.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign Id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "data": { "type": "object", "properties": { "0": { "type": "object", "properties": { "blacklisted_domains": { "type": "object" }, "broken_links": { "type": "object" }, "conversion_tracking": { "type": "object" }, "created_date": { "type": "string", "minLength": 1 }, "email_preheader": { "type": "string", "minLength": 1 }, "finish_date": { "type": "string", "minLength": 1 }, "html": { "type": "string" }, "modified_date": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "pause_rules": { "type": "object" }, "permission_reminder": { "type": "string" }, "plain_text": { "type": "string" }, "recepiant": { "type": "object", "properties": { "lists": { "type": "string", "minLength": 1 }, "lists_contact_count": { "type": "number" }, "segments": { "type": "string" }, "segments_contact_count": { "type": "number" }, "total_lists": { "type": "number" } } }, "reply_email": { "type": "string", "minLength": 1 }, "report_abuse": { "type": "boolean" }, "report_summary": { "type": "object", "properties": { "abuse": { "type": "number" }, "abuse_percentage": { "type": "string", "minLength": 1 }, "clicks": { "type": "number" }, "clicks_percentage": { "type": "string", "minLength": 1 }, "conversions": { "type": "number" }, "conversions_percentage": { "type": "string", "minLength": 1 }, "delivered": { "type": "number" }, "delivered_percentage": { "type": "string", "minLength": 1 }, "hard_bounce": { "type": "number" }, "hard_bounce_percentage": { "type": "string", "minLength": 1 }, "open_percentage": { "type": "string", "minLength": 1 }, "opens": { "type": "number" }, "queue": { "type": "number" }, "queue_percentage": { "type": "string", "minLength": 1 }, "queued_total": { "type": "number" }, "sent": { "type": "number" }, "sent_percentage": { "type": "string", "minLength": 1 }, "soft_bounce": { "type": "number" }, "soft_bounce_percentage": { "type": "string", "minLength": 1 }, "spam_complaints_count": { "type": "number" }, "spam_complaints_percentage": { "type": "string", "minLength": 1 }, "unsubscribe": { "type": "number" }, "unsubscribe_percentage": { "type": "string", "minLength": 1 } } }, "rule": { "type": "object", "properties": { "contacts_order": { "type": "string", "minLength": 1 }, "limit": { "type": "string" } } }, "scheduled_date": { "type": "object", "properties": { "date": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 } } }, "sender": { "type": "object", "properties": { "sender_email": { "type": "string", "minLength": 1 }, "sender_name": { "type": "string", "minLength": 1 } } }, "start_date": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "status_change_date": { "type": "string", "minLength": 1 }, "status_change_message": { "type": "string" }, "subject": { "type": "string", "minLength": 1 }, "tag": { "type": "string", "minLength": 1 }, "time_rule": { "type": "object" }, "type": { "type": "string", "minLength": 1 } } } } } } }, "examples": { "example-1": { "value": { "data": { "0": { "blacklisted_domains": {}, "broken_links": {}, "conversion_tracking": {}, "created_date": "2021-04-27 11:31:04", "email_preheader": "Save more on your Home & Kitchen shopping", "finish_date": "2021-04-27 15:07:02", "html": "", "id": "BBBghIFI", "modified_date": "2021-04-27 11:44:15", "name": "Offer Of The Day", "pause_rules": {}, "permission_reminder": "", "plain_text": "", "recepiant": { "lists": "Subscriber list", "lists_contact_count": 100000, "segments": "", "segments_contact_count": 0, "total_lists": 1 }, "reply_email": "sender@yourdomain.com", "report_abuse": true, "report_summary": { "abuse": 0, "abuse_percentage": "0.00", "clicks": 0, "clicks_percentage": "0.00", "conversions": 0, "conversions_percentage": "0.00", "delivered": 100000, "delivered_percentage": "100.00", "hard_bounce": 0, "hard_bounce_percentage": "0.00", "open_percentage": "15.55", "04\"": null, "status": "Finished", "opens": 15548, "queue": 0, "queue_percentage": "0.00", "queued_total": 100000, "sent": 100000, "sent_percentage": "100.00", "soft_bounce": 0, "soft_bounce_percentage": "0.00", "spam_complaints_count": 0, "spam_complaints_percentage": "0.00", "unsubscribe": 307, "unsubscribe_percentage": "1.97" }, "rule": { "contacts_order": "first", "limit": "" }, "scheduled_date": { "date": "2021-04-27 17:14:15", "timezone": "Asia/Kolkata" }, "sender": { "sender_email": "sender@yourdomain.com", "sender_name": "Sender Name Shan" }, "start_date": "2021-04-27 11:47:04", "status": "Finished", "status_change_date": "2021-04-27 15:07:02", "status_change_message": "", "subject": "Amazon offers", "tag": "Amazon offers", "time_rule": {}, "type": "Normal campaign" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "string", "message": "string" } } } } } } } } }, "put": { "summary": "Update Campaign", "operationId": "update-campaign", "description": "API for updating the campaign. Can't change or edit the list, segments, pause_rule, rules for the campaigns in sending status. Pause the campaign to edit the scheduled date.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign Id", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email_preheader": { "type": "string", "minLength": 1, "description": "Email preheader is the summary text that follows a subject line when the email is viewed in an inbox. In many cases, it\u2019s used to provide a short summary of the email, and is typically one sentence long.\n\nMinimum: 1\n\nMaximum: 150" }, "html": { "type": "string", "minLength": 1, "description": "HTML template content for your email campaign." }, "list_ids": { "type": "array", "description": "Recipients of your email campaign.", "items": { "type": "string", "description": "Contact list id. Before setting list id please check your contact count in list." } }, "mailing_preference": { "type": "boolean", "description": "true - Mailing preference option will be displayed in footer of email campaign template.\n\nfalse - Mailing preference option will not be dispalyed." }, "name": { "type": "string", "minLength": 1, "description": "Name of the campaign.\n\nMinimum: 1\n\nMaximum: 150" }, "pause_rules": { "type": "object", "description": "Optional\n\nIf you want to set a rule for sending a campaign, use this option. Based on the configured rule, the campaign will be sent.", "properties": { "pause_condition": { "type": "string", "minLength": 1, "description": "Rule for setting open or click percentage greater than or less than pause target.\n\nSupported pause_condition - greater than, less than" }, "pause_criteria": { "type": "string", "minLength": 1, "description": "Supported pause_criteria - open, click" }, "pause_limit": { "type": "number", "description": "The percentage of list contacts to which we want to send campaigns first. In the order we set in rules.\n\nMinimum: 1\n\nMaximum: 50" }, "pause_target": { "type": "number", "description": "After achieving pause condition how many percentage of subscribers we have to send campaign.\n\nMinimum: 1\n\nMaximum: 100" }, "wait_time": { "type": "number", "description": "After getting click rate or open rate grater than or less than pause limit , How many time we have to wait to send campaign to other contacts in the list.\n\nWait time in minutes .\n\nMinimum: 1\n\nMaximum: 43200" } } }, "permission_reminder": { "type": "string", "minLength": 1, "description": "The permission reminder content in your email campaign. If you want give unsubscribe link give %%unsubscribe%%\n\nMinimum: 1\n\nMaximum: 150" }, "plain_text": { "type": "string", "minLength": 1, "description": "Plain text content of your email campaign." }, "reply_email": { "type": "string", "minLength": 1, "description": "Email on which the campaign recipients will be able to reply to. If replay_email empty then sender email will be the reply email " }, "report_spam": { "type": "boolean", "description": "Spam reporting enable or disable. " }, "rules": { "type": "object", "description": "Supported contacts_order : first, last.", "properties": { "contacts_order": { "type": "string", "minLength": 1, "description": "The order of contact list in which you want to send your email campaign.\n\nSupported: first,last" }, "limit": { "type": "number", "description": "count of subscribers in list to which campaign sends based on the contacts_order. " } } }, "scheduled_at": { "type": "string", "minLength": 1, "description": "Schedule time for your email campaign. Pass your timezone date-time format for accurate results.\n\nFormat: 2021-04-23 15:04:05" }, "segments": { "type": "string", "minLength": 1, "description": "Your recipient segment id." }, "sender": { "type": "object", "properties": { "sender_email": { "type": "string", "minLength": 1, "description": "From email for your email campaign." }, "sender_name": { "type": "string", "minLength": 1, "description": "From name for email campaign.\n\nMaximum: 100" } } }, "subject": { "type": "string", "minLength": 1, "description": "Subject of the campaign.\n\nMinimum: 1\n\nMaximum: 150" }, "viewin_browser": { "type": "boolean", "description": "true: Enable the \"View this email in your browser\" in Campaign preview page.\n\nfalse: Disable the \"View this email in your browser\" in Campaign preview page." } } }, "examples": { "example-1": { "value": { "email_preheader": "Prime member: You have an unused Prime benefit", "html": " Edited Sample HTML " } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "message": { "type": "string", "minLength": 1 } } }, "examples": { "example-1": { "value": { "message": "Campaign has been updated" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "string", "message": "string" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } } }, "/campaign/{id}/opens": { "post": { "summary": "List Campaign Opens", "operationId": "list-campaign-opens", "description": "Get a paginated list of contacts who opened a specific campaign.\n\nEach row carries the contact's encrypted id, email, name, the tags currently assigned to the contact, the lists the contact currently belongs to (with their ids and names), and the time of the open in your account timezone.\n\nEach contact appears at most once in the response. If a contact opened the campaign multiple times, the time shown is the most recent open.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Encrypted campaign id", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "page", "limit" ], "properties": { "page": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed).\n\nMinimum: 1" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum rows per page.\n\nMinimum: 1\nMaximum: 100" }, "date_from": { "type": "string", "description": "Optional. Only return opens on or after this date. Format `YYYY-MM-DD`, interpreted in your account timezone." }, "date_to": { "type": "string", "description": "Optional. Only return opens on or before this date. Format `YYYY-MM-DD`, interpreted in your account timezone. Must be on or after `date_from`." } } }, "examples": { "Example-1---Default": { "value": { "page": 1, "limit": 25 } }, "Example-2---With-date-filter": { "value": { "page": 1, "limit": 50, "date_from": "2026-01-01", "date_to": "2026-01-31" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "name": { "type": "string", "description": "Campaign name." }, "subject_line": { "type": "string", "description": "Campaign subject line." }, "created_date": { "type": "string", "description": "Campaign creation date and time. Format: `YYYY-MM-DD HH:mm:ss` in your account timezone." } } }, "data": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Encrypted contact id (use with `GET /v1/contacts/{id}`)." }, "email": { "type": "string", "description": "Contact email." }, "first_name": { "type": "string", "description": "Contact first name." }, "last_name": { "type": "string", "description": "Contact last name." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Names of the tags currently assigned to the contact. Empty array when the contact has no tags." }, "lists": { "type": "string", "description": "Comma-separated encrypted ids of the lists the contact currently belongs to. The literal string `\"no lists\"` when the contact belongs to no lists." }, "list_name": { "type": "string", "description": "Comma-separated names of the lists the contact currently belongs to. Each list appears only once. The literal string `\"no lists\"` when the contact belongs to no lists." }, "created_date": { "type": "string", "description": "Time of the open. Format: `YYYY-MM-DD HH:mm:ss` in your account timezone." } } } }, "total": { "type": "integer", "description": "Total number of contacts who opened the campaign, ignoring pagination." } } }, "examples": { "Example-1---With-rows": { "value": { "campaign": { "name": "May newsletter", "subject_line": "Big update inside", "created_date": "2026-05-10 11:30:00" }, "data": [ { "contact_id": "SuwESEuwZZ", "email": "alice@example.com", "first_name": "Alice", "last_name": "Anderson", "tags": [ "VIP", "Newsletter" ], "lists": "SuSwZS,KkfHZw", "list_name": "Newsletter Subscribers, Beta Testers", "created_date": "2026-05-15 08:42:11" }, { "contact_id": "SuwESEuwZf", "email": "bob@example.com", "first_name": "Bob", "last_name": "", "tags": [], "lists": "no lists", "list_name": "no lists", "created_date": "2026-05-15 09:14:02" } ], "total": 1234 } }, "Example-2---Empty-result": { "value": { "campaign": { "name": "May newsletter", "subject_line": "Big update inside", "created_date": "2026-05-10 11:30:00" }, "data": [], "total": 0 } } } } } }, "400": { "description": "Bad Request - validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Page-required": { "value": { "errors": [ { "field": "page", "message": "Page is a required field" } ] } }, "Limit-out-of-range": { "value": { "errors": [ { "field": "limit", "message": "Limit must be 100 or less" } ] } }, "Bad-date-format": { "value": { "errors": [ { "field": "date_from", "message": "Invalid date_from" } ] } }, "Date-range-invalid": { "value": { "errors": [ { "field": "date_to", "message": "date_to must be on or after date_from" } ] } }, "Malformed-JSON": { "value": { "errors": [ { "field": "", "message": "Invalid json" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found - the campaign id does not exist in your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "id", "message": "Campaign not found" } ] } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "Example-1": { "value": { "message": "Too Many Requests" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "Example-1": { "value": { "message": "Sorry, we are experiencing some technical difficulties. Please try after some time." } } } } } } } } }, "/campaign/{id}/clicks": { "post": { "summary": "List Campaign Clicks", "operationId": "list-campaign-clicks", "description": "Get a paginated list of contacts who clicked a link in a specific campaign.\n\nEach row carries the contact's encrypted id, email, name, the tags currently assigned to the contact, the lists the contact currently belongs to (with their ids and names), and the time of the click in your account timezone.\n\nEach contact appears at most once in the response. If a contact clicked more than once, the time shown is the most recent click.", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Encrypted campaign id", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "page", "limit" ], "properties": { "page": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed).\n\nMinimum: 1" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum rows per page.\n\nMinimum: 1\nMaximum: 100" }, "date_from": { "type": "string", "description": "Optional. Only return clicks on or after this date. Format `YYYY-MM-DD`, interpreted in your account timezone." }, "date_to": { "type": "string", "description": "Optional. Only return clicks on or before this date. Format `YYYY-MM-DD`, interpreted in your account timezone. Must be on or after `date_from`." } } }, "examples": { "Example-1---Default": { "value": { "page": 1, "limit": 25 } }, "Example-2---With-date-filter": { "value": { "page": 1, "limit": 50, "date_from": "2026-01-01", "date_to": "2026-01-31" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "name": { "type": "string", "description": "Campaign name." }, "subject_line": { "type": "string", "description": "Campaign subject line." }, "created_date": { "type": "string", "description": "Campaign creation date and time. Format: `YYYY-MM-DD HH:mm:ss` in your account timezone." } } }, "data": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Encrypted contact id (use with `GET /v1/contacts/{id}`)." }, "email": { "type": "string", "description": "Contact email." }, "first_name": { "type": "string", "description": "Contact first name." }, "last_name": { "type": "string", "description": "Contact last name." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Names of the tags currently assigned to the contact. Empty array when the contact has no tags." }, "lists": { "type": "string", "description": "Comma-separated encrypted ids of the lists the contact currently belongs to. The literal string `\"no lists\"` when the contact belongs to no lists." }, "list_name": { "type": "string", "description": "Comma-separated names of the lists the contact currently belongs to. Each list appears only once. The literal string `\"no lists\"` when the contact belongs to no lists." }, "created_date": { "type": "string", "description": "Time of the click. Format: `YYYY-MM-DD HH:mm:ss` in your account timezone." } } } }, "total": { "type": "integer", "description": "Total number of contacts who clicked the campaign, ignoring pagination." } } }, "examples": { "Example-1": { "value": { "campaign": { "name": "May newsletter", "subject_line": "Big update inside", "created_date": "2026-05-10 11:30:00" }, "data": [ { "contact_id": "SuwESEuwZy", "email": "alice@example.com", "first_name": "Alice", "last_name": "Anderson", "tags": [ "VIP" ], "lists": "SuSwZS", "list_name": "Newsletter Subscribers", "created_date": "2026-05-15 08:50:33" } ], "total": 217 } }, "Example-2---Empty-result": { "value": { "campaign": { "name": "May newsletter", "subject_line": "Big update inside", "created_date": "2026-05-10 11:30:00" }, "data": [], "total": 0 } } } } } }, "400": { "description": "Bad Request - validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Limit-too-high": { "value": { "errors": [ { "field": "limit", "message": "Limit must be 100 or less" } ] } }, "Bad-date-format": { "value": { "errors": [ { "field": "date_from", "message": "Invalid date_from" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found - the campaign id does not exist in your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "id", "message": "Campaign not found" } ] } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "Example-1": { "value": { "message": "Too Many Requests" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "Example-1": { "value": { "message": "Sorry, we are experiencing some technical difficulties. Please try after some time." } } } } } } } } }, "/campaign/{id}/unsubs": { "post": { "summary": "List Campaign Unsubscribes", "operationId": "list-campaign-unsubscribes", "description": "Get a paginated list of contacts who unsubscribed via a specific campaign.\n\nEach row carries the contact's encrypted id, email, name, the tags currently assigned to the contact, the lists the contact currently belongs to (with their ids and names), the time of the unsubscribe in your account timezone, and the reason the contact gave (if any).", "tags": [ "Campaigns" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Encrypted campaign id", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "page", "limit" ], "properties": { "page": { "type": "integer", "minimum": 1, "description": "Page number (1-indexed).\n\nMinimum: 1" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum rows per page.\n\nMinimum: 1\nMaximum: 100" }, "date_from": { "type": "string", "description": "Optional. Only return unsubscribes on or after this date. Format `YYYY-MM-DD`, interpreted in your account timezone." }, "date_to": { "type": "string", "description": "Optional. Only return unsubscribes on or before this date. Format `YYYY-MM-DD`, interpreted in your account timezone. Must be on or after `date_from`." } } }, "examples": { "Example-1---Default": { "value": { "page": 1, "limit": 25 } }, "Example-2---With-date-filter": { "value": { "page": 1, "limit": 50, "date_from": "2026-01-01", "date_to": "2026-01-31" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": "object", "properties": { "name": { "type": "string", "description": "Campaign name." }, "subject_line": { "type": "string", "description": "Campaign subject line." }, "created_date": { "type": "string", "description": "Campaign creation date and time. Format: `YYYY-MM-DD HH:mm:ss` in your account timezone." } } }, "data": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Encrypted contact id (use with `GET /v1/contacts/{id}`)." }, "email": { "type": "string", "description": "Contact email." }, "first_name": { "type": "string", "description": "Contact first name." }, "last_name": { "type": "string", "description": "Contact last name." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Names of the tags currently assigned to the contact. Empty array when the contact has no tags." }, "lists": { "type": "string", "description": "Comma-separated encrypted ids of the lists the contact currently belongs to. The literal string `\"no lists\"` when the contact belongs to no lists." }, "list_name": { "type": "string", "description": "Comma-separated names of the lists the contact currently belongs to. Each list appears only once. The literal string `\"no lists\"` when the contact belongs to no lists." }, "created_date": { "type": "string", "description": "Time of the unsubscribe. Format: `YYYY-MM-DD HH:mm:ss` in your account timezone." }, "reason": { "type": "string", "description": "Reason the contact gave when unsubscribing. Empty string when no reason was provided. The literal string `\"Abuse\"` when the contact reported the campaign as spam instead of unsubscribing." } } } }, "total": { "type": "integer", "description": "Total number of contacts who unsubscribed from the campaign, ignoring pagination." } } }, "examples": { "Example-1---With-rows": { "value": { "campaign": { "name": "May newsletter", "subject_line": "Big update inside", "created_date": "2026-05-10 11:30:00" }, "data": [ { "contact_id": "SuwESEuwZZ", "email": "alice@example.com", "first_name": "Alice", "last_name": "Anderson", "tags": [ "VIP" ], "lists": "SuSwZS", "list_name": "Newsletter Subscribers", "created_date": "2026-05-15 09:24:11", "reason": "no longer interested" }, { "contact_id": "SuwESEuHaa", "email": "bob@example.com", "first_name": "Bob", "last_name": "", "tags": [], "lists": "no lists", "list_name": "no lists", "created_date": "2026-05-15 11:02:47", "reason": "Abuse" } ], "total": 42 } }, "Example-2---Empty-result": { "value": { "campaign": { "name": "May newsletter", "subject_line": "Big update inside", "created_date": "2026-05-10 11:30:00" }, "data": [], "total": 0 } } } } } }, "400": { "description": "Bad Request - validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Limit-too-high": { "value": { "errors": [ { "field": "limit", "message": "Limit must be 100 or less" } ] } }, "Date-range-invalid": { "value": { "errors": [ { "field": "date_to", "message": "date_to must be on or after date_from" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found - the campaign id does not exist in your account", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "id", "message": "Campaign not found" } ] } } } } } }, "429": { "description": "Too Many Requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "Example-1": { "value": { "message": "Too Many Requests" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "Example-1": { "value": { "message": "Sorry, we are experiencing some technical difficulties. Please try after some time." } } } } } } } } }, "/contact/property": { "post": { "summary": "Create Property", "operationId": "create-property", "description": "API for creating custom property of contacts. Custom properties store specific information for contact records in Mailercloud. You are allowed to create a maximum of 100 properties.", "tags": [ "Custom Properties" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "description": { "type": "string", "description": "Description for your property\n\nMinimum: 3\n \nMaximum: 500 ", "minLength": 3, "maxLength": 500 }, "name": { "type": "string", "description": "Your name for your property \n\nMinimum: 3\n \nMaximum: 30 ", "minLength": 3, "maxLength": 30 }, "type": { "type": "string", "description": "Your property type\n \n supported types\n \n text,number,date,textarea" } }, "required": [ "name", "type" ] }, "examples": { "example-1": { "value": { "description": "string", "name": "string", "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {}, "required": [ "id" ] }, "examples": { "example-1": { "value": { "id": "xyz" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "field", "message" ] } }, "required": [ "error" ] }, "examples": { "example-1": { "value": { "error": { "field": "name", "message": "The name field must be at least 3 characters" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/contact/property/{id}": { "delete": { "summary": "Delete Property", "operationId": "delete-property", "description": "API for deleting custom property of contacts. If the property is used in a webform you won't be able to delete it.", "tags": [ "Custom Properties" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Custom property Id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "message": { "type": "string", "minLength": 1 } }, "required": [ "message" ] }, "examples": { "example-1": { "value": { "message": "Custom property deleted successfully" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_code": { "type": "integer" }, "message": { "type": "string" } } }, "examples": { "example-1": { "value": {} } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } }, "patch": { "summary": "Update Property", "operationId": "update-property", "description": "API for updating custom property of contacts. Editing custom property type using this API is not possible. You can only edit the name and description.", "tags": [ "Custom Properties" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Custom Property Id", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "description": { "type": "string", "description": "Description for your property\n\nMinimum: 3\n \nMaximum: 500 ", "minLength": 3, "maxLength": 500 }, "name": { "type": "string", "description": "Your name for your property \n\nMinimum: 3\n \nMaximum: 30 ", "minLength": 3, "maxLength": 30 } }, "required": [ "name" ] }, "examples": { "example-1": { "value": { "description": "Gender of your contact", "name": "Gender" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {}, "required": [ "id" ] }, "examples": { "example-1": { "value": { "id": "YCJ" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "field", "message" ] } }, "required": [ "error" ] }, "examples": { "example-1": { "value": { "error": { "field": "name", "message": "The name field must be at least 3 characters" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } } }, "/contact/property/search": { "post": { "summary": "List Property", "operationId": "list-property", "description": "Using this API, you can list all the properties of your contacts in your Mailercloud account. You can also make segments based on these properties", "tags": [ "Custom Properties" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": false, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum number of elements to return. \n\nMaximum: 100\nMinimum: 10", "minimum": 10, "maximum": 100 }, "page": { "type": "number", "description": "You can retrieve a subset of records starting from the page value you have specified. You can add a limit, which will determine the number of records you can retrieve on a single page.\n\nStarts From: 1" }, "search": { "type": "string", "minLength": 1, "description": "Filter property list by name , giving name as search keyword " }, "type": { "type": "string", "description": "Filter property based on type.\n \nAvailable types - default,custom" } }, "required": [ "limit", "page" ] }, "examples": { "example-1": { "value": { "limit": 0, "page": 0, "search": "string", "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "count": { "type": "number" }, "data": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field_description", "field_name", "field_type", "field_value", "id", "is_default" ], "properties": { "field_description": { "type": "string", "minLength": 1 }, "field_name": { "type": "string", "minLength": 1 }, "field_type": { "type": "string", "minLength": 1 }, "field_value": { "type": "string", "minLength": 1 }, "is_default": { "type": "number" } } } } }, "required": [ "count", "data" ] }, "examples": { "example-1": { "value": { "count": 20, "data": [ { "field_description": "Created via webform as a template property.", "field_name": "Message", "field_type": "Textarea", "field_value": "message", "id": "dcK", "is_default": 0 }, { "field_description": " ", "field_name": "Countryin", "field_type": "Text", "field_value": "countryin", "id": "szB", "is_default": 0 }, { "field_description": "IP address of the subscriber", "field_name": "IP", "field_type": "Text", "field_value": "userip", "id": "Bg", "is_default": 1 }, { "field_description": "Lead source", "field_name": "Lead source", "field_type": "Text", "field_value": "lead_source", "id": "BF", "is_default": 1 }, { "field_description": "Salary of the subscriber", "field_name": "Salary", "field_type": "Number", "field_value": "salary", "id": "kv", "is_default": 1 }, { "field_description": "Job of the subscriber", "field_name": "Job title", "field_type": "Text", "field_value": "job_title", "id": "Ku", "is_default": 1 }, { "field_description": "Department of the subscriber", "field_name": "Department", "field_type": "Text", "field_value": "department", "id": "bC", "is_default": 1 }, { "field_description": "company name of the subscriber", "field_name": "company_name", "field_type": "Text", "field_value": "organization", "id": "kb", "is_default": 1 } ] } }, "example-2": { "value": { "count": 0, "data": [ { "field_description": "string", "field_name": "string", "field_type": "string", "field_value": "string", "id": "string", "is_default": 0 } ] } } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Invalid input" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/contacts": { "post": { "summary": "Create Contact", "operationId": "create-contact", "description": "API for creating contact. For creating a contact, email and list id is required. If you try to create a contact that already exists, it gives an \"already exists\" message . You can add custom property data by mapping the property id : value. You can add contacts until your contact quota limit is reached. If you create a contact in a suppressed list and if this contact is also present in the active list, the contact will be removed from the active list to the suppressed list.", "tags": [ "Contacts" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "list_id" ], "properties": { "city": { "type": "string", "description": "The city of the contact\n\nMaximum: 100 ", "maxLength": 100 }, "country": { "type": "string", "description": "The country of the contact\n\nMaximum: 50", "maxLength": 50 }, "custom_fields": { "type": "object", "description": "Json for custom property\n \nText - maximum: 100\n\nTextarea - maximum: 500\n\nNumber - Numeric values only\n\nDate - maximum: 10,format = 2006-01-02 ", "properties": { "enc_id1": { "type": "string", "minLength": 1, "description": " property id : value of property\n string can store upto 100 characters" }, "enc_id2": { "type": "number", "description": " property id : value of property\n Number field can store numbers with 30 characters long" } } }, "department": { "type": "string", "minLength": 1, "description": "The department of contact\n\nMaximum: 100" }, "email": { "type": "string", "maxLength": 200, "description": "The email for the contact. This is required to be a valid email.\n\nMaximum: 200" }, "industry": { "type": "string", "description": "The industry of the contact\n\nMaximum: 100", "maxLength": 100 }, "job_title": { "type": "string", "description": "The job title of the contact \n\nMaximum: 100", "maxLength": 100 }, "last_name": { "type": "string", "description": "The last name for the contact\n\nMaximum: 25", "maxLength": 25 }, "lead_source": { "type": "string", "description": "The lead sorce of contact\n\nMaximum: 50", "maxLength": 50 }, "list_id": { "type": "string", "minLength": 1, "description": "The contact list id to which you want to add this contact" }, "middle_name": { "type": "string", "maxLength": 25, "description": "The middle name of contact\n\nMaximum: 25" }, "first_name": { "type": "string", "maxLength": 25, "description": "Name of your contact\n\nMaximum: 25" }, "company_name": { "type": "string", "description": "The company name of your contact\n\nMaximum: 150", "maxLength": 150 }, "phone": { "type": "string", "minLength": 1, "description": "The phone number of your contact\n\nMaximum: 25" }, "salary": { "type": "number", "description": "The salary of your contact\n\nMaximum: 15" }, "state": { "type": "string", "description": "The state of your contact\n\nMaximum: 100", "maxLength": 100 }, "postal_code": { "type": "string", "description": "The postal code of your contact\n\nMaximum: 25", "maxLength": 25 }, "contact_type": { "type": "string", "description": "Allowed values - active, bounce, abuse, unsubscribe, suppressed, spam complaints\n\nDefault: active", "default": "active" }, "tags": { "type": "array", "description": "The tags of your contact\n", "items": {} } } }, "examples": { "example-1": { "value": { "city": "string", "country": "string", "custom_fields": { "enc_id1": "string", "enc_id2": 0 }, "department": "string", "email": "string", "industry": "string", "job_title": "string", "last_name": "string", "lead_source": "string", "list_id": "string", "middle_name": "string", "first_name": "string", "company_name": "string", "phone": "string", "salary": 0, "state": "string", "postal_code": "string", "contact_type": "active", "tags": [ "string" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {} }, "examples": { "example-1": { "value": { "id": "xc" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "email", "message": "Invalid email" } } } } } } }, "401": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/contacts/upsert": { "post": { "summary": "Create or Update Contact", "operationId": "create-or-update-contact", "description": "API to manage your contacts, allowing you to either create new contacts or update existing ones based on your needs.\n\nWhen you send a request, the API first checks if the contact already exists in your database.\nIf the contact is found, the API will automatically update the existing contact with the new information provided. This ensures that your contact list remains up-to-date without creating duplicates.\n\n**Custom Property Data:**\nThe API allows you to add custom properties to each contact. You can do this in two ways:\n- By Property ID: Map the property ID to its corresponding value. \n- By Personalization Tag: Alternatively, you can use personalization tag for that property to specify values.\n\n**Contact Quota Limit:**\nPlease note that you can continue adding or updating contacts until you reach your designated contact quota limit. \nIf you reach your quota limit, further attempts to add new contacts will be rejected until you either remove some existing contacts or increase your quota.", "tags": [ "Contacts" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "enc_id1": { "type": "string" }, "personalisation_tag_4": { "type": "integer" } } }, "department": { "type": "string" }, "email": { "type": "string" }, "industry": { "type": "string" }, "job_title": { "type": "string" }, "last_name": { "type": "string" }, "lead_source": { "type": "string" }, "list_id": { "type": "string" }, "middle_name": { "type": "string" }, "first_name": { "type": "string" }, "company_name": { "type": "string" }, "phone": { "type": "string" }, "salary": { "type": "integer" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "contact_type": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "x-examples": { "Example 1": { "city": "San Francisco", "country": "USA", "custom_fields": { "enc_id1": "ABC123", "personalisation_tag_4": 456 }, "department": "Engineering", "email": "john.doe@example.com", "industry": "Software Development", "job_title": "Software Engineer", "last_name": "Doe", "lead_source": "Website", "list_id": "KYHH", "middle_name": "A.", "first_name": "John A. Doe", "company_name": "Tech Innovations Inc.", "phone": "+1-234-567-8901", "salary": 95000, "state": "California", "postal_code": "94105", "contact_type": "active", "tags": [ "prospect", "customer", "lead" ] } } }, "examples": { "Example-1": { "value": { "city": "San Francisco", "country": "USA", "custom_fields": { "enc_id1": "ABC123", "personalisation_tag_4": 456 }, "department": "Engineering", "email": "john.doe@example.com", "industry": "Software Development", "job_title": "Software Engineer", "last_name": "Doe", "lead_source": "Website", "list_id": "KYHH", "middle_name": "A.", "first_name": "John A. Doe", "company_name": "Tech Innovations Inc.", "phone": "+1-234-567-8901", "salary": 95000, "state": "California", "postal_code": "94105", "contact_type": "active", "tags": [ "prospect", "customer", "lead" ] } }, "Example-2": { "value": { "city": "San Francisco", "country": "USA", "custom_fields": { "enc_id1": "ABC123", "personalisation_tag_4": 456 }, "department": "Engineering", "email": "john.doe@example.com", "industry": "Software Development", "job_title": "Software Engineer", "last_name": "Doe", "lead_source": "Website", "list_id": "KYHH", "middle_name": "A.", "first_name": "John A. Doe", "company_name": "Tech Innovations Inc.", "phone": "+1-234-567-8901", "salary": 95000, "state": "California", "postal_code": "94105", "contact_type": "active", "tags": [ "prospect", "customer", "lead" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string" }, "status": { "type": "string" } }, "x-examples": { "Example 1": { "contact_id": "fZuKHSuwK", "status": "updated" } } }, "examples": { "Example-1": { "value": { "contact_id": "fZuKHSuwK", "status": "updated" } }, "Example-2": { "value": { "contact_id": "fZuKHSuwK", "status": "created" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } }, "x-examples": { "Example 1": { "error": { "field": "email", "message": "Invalid email" } } } }, "examples": { "Example-1": { "value": { "error": { "field": "email", "message": "Invalid email" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "x-examples": { "Example 1": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/contacts/{id}": { "put": { "summary": "Update Contact", "operationId": "update-contact", "description": "Update contact details based on contact ID or Email using this API. However, you can't update the list ID and email.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact Id or Email", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "city": { "type": "string", "description": "The city of the contact\n\nMaximum: 100 ", "maxLength": 100 }, "country": { "type": "string", "description": "The country of the contact\n\nMaximum: 50", "maxLength": 50 }, "custom_fields": { "type": "object", "description": "Json for custom property\n \nText - maximum: 100\n\nTextarea - maximum: 500\n\nNumber - Numeric values only\n\nDate - maximum: 10,format = 2006-01-02 ", "properties": { "enc_id1": { "type": "string", "minLength": 1, "description": " property id : value of property" }, "enc_id2": { "type": "number", "description": " property id : value of property" } }, "required": [ "enc_id1", "enc_id2" ] }, "department": { "type": "string", "description": "The department of contact\n\nMaximum: 100", "maxLength": 100 }, "industry": { "type": "string", "description": "The industry of the contact\n\nMaximum: 100", "maxLength": 100 }, "job_title": { "type": "string", "description": "The job title of the contact \n\nMaximum: 100", "maxLength": 100 }, "last_name": { "type": "string", "description": "The last name for the contact\n\nMaximum: 25", "maxLength": 25 }, "lead_source": { "type": "string", "description": "The lead sorce of contact\n\nMaximum: 50", "maxLength": 50 }, "middle_name": { "type": "string", "description": "The middle name of contact\n\nMaximum: 25", "maxLength": 25 }, "first_name": { "type": "string", "description": "Name of your contact\n\nMaximum: 25", "maxLength": 25 }, "company_name": { "type": "string", "description": "The company name of your contact\n\nMaximum: 150", "maxLength": 150 }, "phone": { "type": "string", "description": "The phone number of your contact\n\nMaximum: 25", "maxLength": 25 }, "salary": { "type": "number", "description": "The salary of your contact\n\nMaximum: 15" }, "state": { "type": "string", "description": "The state of your contact\n\nMaximum: 100", "maxLength": 100 }, "postal_code": { "type": "string", "description": "The postal code of your contact\n\nMaximum: 25", "maxLength": 25 }, "contact_type": { "type": "string", "description": "Allowed values - active, bounce, abuse, unsubscribe, suppressed, spam complaints" }, "tags": { "type": "array", "description": "The tags of your contact", "items": {} } } }, "examples": { "example-1": { "value": { "city": "string", "country": "string", "custom_fields": { "xyz": "string", "ncx": 0 }, "department": "string", "industry": "string", "job_title": "string", "last_name": "string", "lead_source": "string", "middle_name": "string", "first_name": "string", "company_name": "string", "phone": "string", "salary": 0, "state": "string", "postal_code": "string", "tags": [ "string" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "message": { "type": "string", "minLength": 1 } } }, "examples": { "example-1": { "value": { "message": "Contact updated" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "name", "message": "Invalid name" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } }, "delete": { "summary": "Delete Contact", "operationId": "delete-contact", "description": "Delete a contact based on their ID", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact id or Email", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "message": { "type": "string", "minLength": 1 } } }, "examples": { "example-1": { "value": { "message": "Contact deleted successfully" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } }, "get": { "summary": "Get Contact Details", "operationId": "get-contact-details", "description": "Get contact details based on their Contact ID or Email", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact id or Email", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "city", "country", "custom_fields", "department", "dob", "email", "firstname", "id", "industry", "job_title", "last_name", "lead_source", "list_id", "middle_name", "name", "company_name", "phone", "salary", "state", "user_ip", "postal_code" ], "properties": { "city": { "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 1 }, "custom_fields": { "type": "object" }, "department": { "type": "string", "minLength": 1 }, "dob": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "firstname": { "type": "string", "minLength": 1 }, "industry": { "type": "string", "minLength": 1 }, "job_title": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "lead_source": { "type": "string", "minLength": 1 }, "list_id": { "type": "string", "minLength": 1 }, "middle_name": { "type": "string", "minLength": 1 }, "first_name": { "type": "string", "minLength": 1 }, "company_name": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 }, "salary": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 }, "user_ip": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "tags": { "type": "string" } } } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } } }, "/contact/tag/remove": { "post": { "summary": "Remove Contact Tag", "operationId": "remove-contact-tag", "description": "API to remove contact-tags from individual contacts\n\nWhen you send a request, the API first checks if the contact already exists in your database.\nIf the contact is found, the API will check if the tags you provided are valid. You can give both tag names or tag ids.\n\nThe API allows you to remove contact-tags. You can do this in two ways:\n- By Contact ID: You can add the **contact ID** from your panel to remove tags.\n- By Email: Alternatively, you can use the **email ID** of the contact whose tag you want to update.", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_ids": { "type": "array", "items": { "type": "string" } }, "tag_names": { "type": "array", "items": { "type": "string" } } }, "x-examples": { "Example 1": { "tag_ids": [ "ccj", "ddg" ], "tag_names": [ "my tag", "new tag" ] } } }, "examples": { "Example-1": { "value": { "id": "example@example.com", "tag_ids": [ "ccj", "ddg" ], "tag_names": [ "my tag", "new tag" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "x-examples": { "Example 1": { "message": "Contact tag removed successfully" } } }, "examples": { "Example-1": { "value": { "message": "Contact tag removed successfully" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "x-examples": { "Example 1": { "error": "provide tag does not exists" } } }, "examples": { "Example-1": { "value": { "error": "Contact Id is a required field" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "x-examples": { "Example 1": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/contact/search/{id}": { "post": { "summary": "Get Contacts in a List", "operationId": "get-contacts-in-a-list", "description": "You can collect all your contacts on a single list.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List id", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum number of elements to return. \n\nMaximum: 100\nMinimum: 10", "minimum": 10, "maximum": 100 }, "page": { "type": "number", "description": "You can retrieve a subset of records starting from the page value you have specified. You can add a limit, which will determine the number of records you can retrieve on a single page.\n\nStarts From: 1" }, "search": { "type": "string", "description": "Filter contact list by name , giving name as search keyword " } }, "required": [ "limit", "page" ] }, "examples": { "example-1": { "value": { "limit": 10, "page": 1, "search": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "count": { "type": "number" }, "data": { "type": "object", "properties": { "city": { "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 1 }, "custom_fields": { "type": "object" }, "department": { "type": "string", "minLength": 1 }, "dob": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "firstname": { "type": "string", "minLength": 1 }, "industry": { "type": "string", "minLength": 1 }, "job_title": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "lead_source": { "type": "string", "minLength": 1 }, "middle_name": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "company_name": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 }, "salary": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 }, "user_ip": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "count": 0, "data": { "city": "string", "country": "string", "custom_fields": {}, "department": "string", "dob": "string", "email": "string", "firstname": "string", "id": "string", "industry": "string", "job_title": "string", "last_name": "string", "lead_source": "string", "middle_name": "string", "first_name": "string", "company_name": "string", "phone": "string", "salary": "string", "state": "string", "user_ip": "string", "postal_code": "string" } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Invalid input" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } } }, "/contacts/batch": { "post": { "summary": "Create Batch Contact", "operationId": "create-batch-contact", "description": "Create a Batch contact. You can create a maximum of 50 contact through this API.", "tags": [ "Contacts" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 50, "description": "Batches of contact", "items": { "type": "object", "properties": { "city": { "type": "string", "description": "The city of the contact\n\nMaximum: 100", "maxLength": 100 }, "country": { "type": "string", "description": "The country of the contact\n\nMaximum: 50", "maxLength": 50 }, "custom_fields": { "type": "object", "description": "Json for custom property\n \nText - maximum: 100\n\nTextarea - maximum: 500\n\nNumber - Numeric values only\n\nDate - maximum: 10,format = 2006-01-02 ", "properties": { "enc_id1": { "type": "string", "minLength": 1, "description": "property id : value of property" }, "enc_id2": { "type": "number", "description": "property id : value of property" } } }, "department": { "type": "string", "description": "The department of contact\n\nMaximum: 100", "maxLength": 100 }, "email": { "type": "string", "description": "The email for the contact. This is required to be a valid email.\n\nMaximum: 200", "maxLength": 200 }, "industry": { "type": "string", "description": "The industry of the contact\n\nMaximum: 100", "maxLength": 100 }, "job_title": { "type": "string", "description": "The job title of the contact \n\nMaximum: 100", "maxLength": 100 }, "last_name": { "type": "string", "description": "The last name for the contact\n\nMaximum: 25", "maxLength": 25 }, "lead_source": { "type": "string", "description": "The lead sorce of contact\n\nMaximum: 50", "maxLength": 50 }, "middle_name": { "type": "string", "description": "The middle name of contact\n\nMaximum: 25", "maxLength": 25 }, "name": { "type": "string", "description": "Name of your contact\n\nMaximum: 25", "maxLength": 25 }, "company_name": { "type": "string", "description": "The company name of your contact\n\nMaximum: 150", "maxLength": 150 }, "phone": { "type": "string", "description": "The phone number of your contact\n\nMaximum: 25", "maxLength": 25 }, "salary": { "type": "number", "description": "The salary of your contact\n\nMaximum: 15" }, "state": { "type": "string", "description": "The state of your contact\n\nMaximum: 100", "maxLength": 100 }, "postal_code": { "type": "string", "description": "The postal code of your contact\n\nMaximum: 25", "maxLength": 25 }, "contact_type": { "type": "string", "description": "Allowed values - active, bounce, abuse, unsubscribe, suppressed, spam complaints\n\nDefault: active", "default": "active" }, "tags": { "type": "array", "items": {} } }, "required": [ "email" ] } }, "list_id": { "type": "string", "description": "The contact list id to which you want to add this contact" } }, "required": [ "contacts", "list_id" ] }, "examples": { "example-1": { "value": { "contacts": [ { "city": "string", "country": "string", "custom_fields": { "enc_id1": "string", "enc_id2": 0 }, "department": "string", "email": "string", "industry": "string", "job_title": "string", "last_name": "string", "lead_source": "string", "middle_name": "string", "name": "string", "company_name": "string", "phone": "string", "salary": 0, "state": "string", "postal_code": "string", "tags": [ "string" ] } ], "list_id": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "data": { "type": "object", "properties": { "inserted": { "type": "number" }, "skipped": { "type": "number" }, "submitted": { "type": "number" }, "updated": { "type": "number" } } }, "message": { "type": "string", "minLength": 1 } } }, "examples": { "example-1": { "value": { "data": { "inserted": 2, "skipped": 1, "submitted": 3, "updated": 0 }, "message": "Batch contacts processed" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "email", "message": "Invalid email" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/list": { "post": { "summary": "Create a New List", "operationId": "create-a-new-list", "description": "Your Mailercloud list, also known as your recipient, is where you store and manage all of your contacts.", "tags": [ "Lists" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "list_type": { "type": "number", "description": "Your List type .\n\nAvailable Choices\n\nNormal List: 1", "default": 1 }, "name": { "type": "string", "description": "Your List name. \nOnly alphanumeric characters, underscore, hyphen, dot and space allowed.\n\nMinimum: 3\nMaximum: 100", "minLength": 3, "maxLength": 100, "pattern": "^[a-zA-Z0-9._ \\-]+$/i" } }, "required": [ "list_type", "name" ] }, "examples": { "example-1": { "value": { "list_type": 1, "name": "Email subscription-list" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {} }, "examples": { "example-1": { "value": { "id": "xyz" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "name", "message": "The name field must be at least 3 characters" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/list/{id}": { "patch": { "summary": "Update a List", "operationId": "update-a-list", "description": "Update the details of a specific list by id. However, you can only update the names using this API", "tags": [ "Lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List Id", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "description": "Your List name. \nOnly alphanumeric characters, underscore, hyphen, dot and space allowed.\n\nMinimum: 3\nMaximum: 100", "maxLength": 100, "pattern": "^[a-zA-Z0-9._ \\-]+$/i" } }, "required": [ "name" ] }, "examples": { "example-1": { "value": { "name": "Subscibers List" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "listdetails": { "type": "object", "properties": { "list_type": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "id", "list_type", "name" ] } }, "required": [ "listdetails" ] }, "examples": { "example-1": { "value": { "listdetails": { "id": "HHda", "list_type": "Normal", "name": "List Registration" } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "name", "message": "Only alphanumeric characters, underscore, hyphen, dot and space allowed" } ] } } } } } }, "401": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } }, "delete": { "summary": "Delete a List", "operationId": "delete-a-list", "description": "This API deletes a specific list by id. However, you can't delete your list if its used in an active campaign , active automation or in an active webform .", "tags": [ "Lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List Id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" }, "examples": { "example-1": { "value": { "message": "List deleted successfully" } } } } } }, "401": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } } } } } } } }, "get": { "summary": "Get Single List Details", "operationId": "get-single-list-details", "description": "Get single list details based on id.", "tags": [ "Lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List Id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "count": { "type": "number" }, "data": { "type": "object", "properties": { "contact_count": { "type": "number" }, "list_status": { "type": "string", "minLength": 1 }, "list_type": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "open_percentage": { "type": "number" } }, "required": [ "contact_count", "id", "list_status", "list_type", "name", "open_percentage" ] } }, "required": [ "count", "data" ] }, "examples": { "example-1": { "value": { "count": 10, "data": { "contact_count": 1000, "id": "xze", "list_status": "Waiting for approval", "list_type": "Normal List", "name": "Email subscription-list", "open_percentage": 50 } } } } } } }, "401": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "field", "message" ], "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "required": [ "errors" ] }, "examples": { "example-1": { "value": { "errors": [ { "field": "id", "message": "Record not found with the given Id" } ] } }, "example-2": { "value": { "errors": [ { "field": "string", "message": "string" } ] } } } } } } } } }, "/lists/search": { "post": { "summary": "List Lists", "operationId": "get-all-list-and-search-list", "description": "Use this API to return an array of all of your contact lists. You can filter, search and sort list.", "tags": [ "Lists" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum number of elements to return. \n\nMaximum: 100\nMinimum: 10", "minimum": 10, "maximum": 100 }, "list_type": { "type": "number", "description": "Your List type .\n\nAvailable Choices\n\nNormal List: 1" }, "page": { "type": "number", "description": "You can retrieve a subset of records starting from the page value you have specified. You can add a limit, which will determine the number of records you can retrieve on a single page.\n\nStarts From: 1", "maximum": 3 }, "search_name": { "type": "string", "minLength": 1, "description": "Filter list by name , giving name in search keyword " }, "sort_field": { "type": "string", "minLength": 1, "description": "Sort list data based on this field\n\nAvailable sort fields\n\nname,contact_count,open_percentage" }, "sort_order": { "type": "string", "minLength": 1, "description": "Sorting order for sort field\n\nAvailable sort orders\n \nasc, ASC, desc, DESC " } }, "required": [ "limit", "list_type", "page" ] }, "examples": { "example-1": { "value": { "limit": 10, "list_type": 1, "page": 1, "search_name": "subscription", "sort_field": "name", "sort_order": "asc" } }, "example-2": { "value": { "limit": 10, "page": 10 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "count": { "type": "number" }, "data": { "type": "object", "properties": { "contact_count": { "type": "number" }, "list_status": { "type": "string", "minLength": 1 }, "list_type": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "open_percentage": { "type": "number" } } } } }, "examples": { "example-1": { "value": { "count": 100, "data": { "contact_count": 100, "id": "ws", "list_status": "Updating", "list_type": "Normal List", "name": "Subscription list", "open_percentage": 50 } } }, "example-2": { "value": { "data": { "0": { "contact_count": "1", "id": "hXUA", "list_status": "Updating", "list_type": "Normal", "name": "List Registration", "open_percentage": "0.00" }, "1": { "contact_count": "0", "id": "YxGF", "list_status": "Uploading", "list_type": "Normal", "name": "Form 1", "open_percentage": "0.00" }, "2": { "contact_count": "2", "id": "xhef", "list_status": "Waiting for approval", "list_type": "Normal", "name": "sample 2 updated", "open_percentage": "0.00" }, "3": { "contact_count": "1", "id": "ixss", "list_status": "Verifying", "list_type": "Normal", "name": "uptest up test on", "open_percentage": "0.00" }, "4": { "contact_count": "1", "id": "yFXf", "list_status": "Verifying", "list_type": "Normal", "name": "list f updated", "open_percentage": "0.00" }, "5": { "contact_count": "0", "id": "IXCa", "list_status": "", "list_type": "Normal", "name": "test ddd List-23 Feb 2021 04.22 PM", "open_percentage": "0.00" }, "6": { "contact_count": "0", "id": "iFfF", "list_status": "Verifying new contacts", "list_type": "Normal", "name": "string nnnnn", "open_percentage": "0.00" }, "7": { "contact_count": "0", "id": "iFEh", "list_status": "Verifying new contacts", "list_type": "Normal", "name": "string", "open_percentage": "0.00" }, "8": { "contact_count": "0", "id": "yDJX", "list_status": "Verifying new contacts", "list_type": "Normal", "name": "lucky list ", "open_percentage": "0.00" }, "9": { "contact_count": "0", "id": "iDXJ", "list_status": "Verifying new contacts", "list_type": "Normal", "name": "lucksy renamed 1", "open_percentage": "0.00" } }, "list_count": 56 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } }, "examples": { "example-1": { "value": { "error": { "field": "sort_order", "message": "Invalid sort_order" } } } } } } }, "401": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/segment/search": { "post": { "summary": "List Segment", "operationId": "list-segment", "description": "List all your created segments.", "tags": [ "Segments" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": false, "description": "application/json", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum number of elements to return.\n\nMaximum: 100 Minimum: 10" }, "page": { "type": "number", "description": "You can retrieve a subset of records starting from the page value you have specified. You can add a limit, which will determine the number of records you can retrieve on a single page.\n\nStarts From: 1" }, "search": { "type": "string", "minLength": 1, "description": "Filter segment list by name , giving name as search keyword " }, "sort_field": { "type": "string", "minLength": 1, "description": "Sort segment list data based on the following field.\n\nAvailable sort fields: name,active_count " }, "sort_order": { "type": "string", "minLength": 1, "description": "Sorting order for sort field\n\nAvailable sort orders\n\nasc, ASC, desc, DESC" } }, "required": [ "limit", "page", "search", "sort_field", "sort_order" ] }, "examples": { "example-1": { "value": { "limit": 10, "page": 1 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "count": { "type": "number" }, "data": { "type": "array", "uniqueItems": true, "minItems": 1, "items": { "required": [ "active_count", "id", "list", "name" ], "properties": { "active_count": { "type": "number" }, "list": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } } } } }, "required": [ "count", "data" ] }, "examples": { "example-1": { "value": { "count": 2, "data": [ { "active_count": 8690337, "id": "KyGa", "list": "Default List,Sending list,sending list 2,Auto Test 3,Auto Test 0,Auto Test 1,Auto list New,List bounce,Multy domain,lowww,List10lac1,LIST10lac2,List10lac3,List10lac4,List10Lac6,Fineecho copy paste,List auto test -1,List auto test -2,Vinmail Open,list vinmail,Tb live test-Multydomain,Api test", "name": "Sending list-1" }, { "active_count": 8408779, "id": "Kxwf", "list": "Default List,Sending list,sending list 2,Auto Test 3,Auto Test 0,Auto Test 1,Auto list New,List bounce,Multy domain,lowww,List10lac1,LIST10lac2,List10lac3,List10lac4,List10Lac6,Fineecho copy paste,List auto test -1,List auto test -2,Vinmail Open", "name": "ryth" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_code": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/segments": { "post": { "summary": "Create Segment", "operationId": "create-segment", "description": "API to create a segment in a single request. `name`, `match` and `rules` are required. `lists` is optional - if omitted, the segment evaluates against all contacts.\n\nA segment is a dynamic contact filter built from a list of rules. Each rule belongs to one of 4 filter_types: `contact_details` (built-in contact fields), `contact_property` (custom properties), `tag` (contact tags), or `activity` (campaign / automation / engagement events). The `match` field controls whether ALL rules must match (`all`) or ANY rule is enough (`any`).", "tags": [ "Segments" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "match", "rules" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Segment display name. Must be unique within the account.\n\nMinimum: 1\nMaximum: 100" }, "match": { "type": "string", "enum": [ "all", "any" ], "description": "How rules combine.\n\nall: every rule must match (AND)\nany: at least one rule must match (OR)\n\nSupported values: all, any" }, "lists": { "type": "array", "items": { "type": "string" }, "maxItems": 150, "description": "Optional. Restrict the segment to contacts in these lists. Provide list names (cid-scoped). Maximum 150 lists." }, "rules": { "type": "array", "minItems": 1, "description": "Filter rules. At least one rule is required.", "items": { "type": "object", "required": [ "filter_type" ], "properties": { "filter_type": { "type": "string", "enum": [ "contact_details", "contact_property", "tag", "activity" ], "description": "Type of filter rule.\n\ncontact_details: built-in contact fields (email_status, contact_rating, email_domain, etc.)\ncontact_property: custom field defined in your account\ntag: contact tags (encrypted tag IDs)\nactivity: campaign / automation / engagement events\n\nSupported values: contact_details, contact_property, tag, activity" }, "field": { "type": "string", "description": "Field name. Required for contact_details and contact_property.\n\nFor contact_details, allowed values: email_status, verification_status, contact_rating, email_domain, mailbox_provider, signup_source\n\nFor contact_property, use the property mapping_name (e.g. custom_1, country, salary). Must match ^[A-Za-z0-9_]+$\n\nNote: verification_status is a write-side alias and collapses to email_status in storage; GET round-trip always returns field=email_status." }, "property_type": { "type": "string", "enum": [ "text", "number", "date" ], "description": "For contact_property only. Picks the operator family. Defaults from the custom field's type in gyh_custom_fields if omitted." }, "operator": { "type": "string", "description": "Comparison operator. Allowed values depend on the filter_type / field / property_type.\n\nText operators: equal_to (also accepts is, equals), not_equal_to (also is_not), exact_match, contains, does_not_contain, starts_with, does_not_start_with, ends_with, does_not_end_with, any_of, is_known, is_unknown\n\nNumber operators (per PR #142 operator-canonical fix): equal_to (canonical, also accepts equal_to_number, is_number), not_equal_to (canonical, also accepts not_equal_to_number), less_than, less_than_number (verbatim - kept distinct because of its SQL > 0 guard), greater_than, between, is_known_number, is_unknown_number\n\nDate operators: in_the_last_days (also in_last_days), not_in_the_last_days, date_between, on_a_specific_date, is_after, is_before, date_is_not, date_is_known, date_is_unknown\n\nTag operators: is_tagged, is_not_tagged\n\nemail_status field: equal_to, not_equal_to, any_of\nsignup_source field: was, was_not" }, "value": { "description": "Filter value. Type depends on operator.\n\nText/number equality: string or number\nany_of: array of strings\nbetween: { from: number, to: number }\ndate_between: { from: YYYY-MM-DD, to: YYYY-MM-DD }\nin_the_last_days / not_in_the_last_days: integer 1-365\nis_known / is_unknown / is_known_number / is_unknown_number / date_is_known / date_is_unknown / is_empty / is_not_empty: omit value\n\nemail_status enum: valid, unknown, suppressed, unsubscribed, spam, bounced, external_group_mailbox, spam_trap, external_abusers, external_invalid, spam_complaints, frequent_abusers, external_verified, blacklisted, account_level_bounce\n\nsignup_source enum: admin_add, import, api, webform" }, "filter_by": { "type": "string", "description": "Sub-selector for tag and activity rules.\n\nFor tag filter_type with is_tagged / is_not_tagged: any_of, all_of\n\nFor activity filter_type: any_of_the_last_five, all_of_the_last_five, any_of_last_seven_day, any_of_last_one_month, any_of_last_three_month, between, in_the_last_days, not_in_the_last_days, count, count_between, order_by_count, before, after, on, for, between_time" }, "category": { "type": "string", "enum": [ "campaign", "automation", "webform", "list", "audience", "engagement_status", "global_engagers", "global_openers", "subscriber_opened", "subscriber_clicked" ], "description": "Activity category. Required when filter_type=activity.\n\nSupported values: campaign, automation, webform, list, audience, engagement_status, global_engagers, global_openers, subscriber_opened, subscriber_clicked" }, "activity": { "type": "string", "description": "Activity event name. Required for some activity categories (campaign, automation, webform, list, audience).\n\nSupported values: opened, not_opened, clicked, not_clicked, sent, not_sent, started, completed, not_started, not_completed, happened, not_happened" } } } } } }, "examples": { "Example-1---Active-gmail-subscribers": { "value": { "name": "Active gmail subscribers", "match": "all", "lists": [ "Newsletter Subscribers" ], "rules": [ { "filter_type": "contact_details", "field": "email_status", "operator": "equal_to", "value": "valid" }, { "filter_type": "contact_details", "field": "email_domain", "operator": "contains", "value": "gmail" } ] } }, "Example-2---High-rated-US-contacts-engaged-last-30-days": { "value": { "name": "Engaged US contacts - last 30 days", "match": "all", "rules": [ { "filter_type": "contact_details", "field": "contact_rating", "operator": "between", "value": { "from": 3, "to": 5 } }, { "filter_type": "contact_property", "field": "country", "property_type": "text", "operator": "equal_to", "value": "United States" }, { "filter_type": "activity", "category": "campaign", "activity": "opened", "filter_by": "in_the_last_days", "value": 30 } ] } }, "Example-3---VIP-tag-OR-signed-up-via-API-in-last-7-days": { "value": { "name": "VIP or recent API signups", "match": "any", "rules": [ { "filter_type": "tag", "operator": "is_tagged", "filter_by": "any_of", "value": [ "enc_t1", "enc_t2" ] }, { "filter_type": "contact_details", "field": "signup_source", "operator": "was", "value": "api" }, { "filter_type": "activity", "category": "list", "activity": "happened", "filter_by": "in_the_last_days", "value": 7 } ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "examples": { "Example-1": { "value": { "id": "EKZwS" } } } } } }, "400": { "description": "Bad Request - validation, name resolution, or operator-shape failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "rules[0].field", "message": "Unknown contact_details field 'foo'" }, { "field": "rules[1].value", "message": "between requires { from, to }" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } }, "403": { "description": "Forbidden - caller's plan does not include segmentation", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "Example-1": { "value": { "errors": [ { "field": "", "message": "Plan does not include segmentation" } ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "Example-1": { "value": { "message": "Internal server error" } } } } } } } } }, "/senders/search": { "post": { "summary": "List Senders", "operationId": "get-all-senders-and-search-senders", "description": "Use this API to return an array of all your active and verified sender email addresses with sender name and reply-to email. You can filter, search and sort senders.", "tags": [ "Senders" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum number of elements to return.\n\nMaximum: 100\nMinimum: 10", "minimum": 10, "maximum": 100 }, "page": { "type": "number", "description": "You can retrieve a subset of records starting from the page value you have specified. You can add a limit, which will determine the number of records you can retrieve on a single page.\n\nStarts From: 1", "minimum": 1 }, "search": { "type": "string", "maxLength": 255, "description": "Filter senders by email or name. Partial match is supported." }, "sort_field": { "type": "string", "description": "Sort sender data based on this field.\n\nAvailable sort fields: sender_email, sender_name, created_date" }, "sort_order": { "type": "string", "description": "Sorting order for sort field.\n\nAvailable sort orders: asc, ASC, desc, DESC" } }, "required": [ "limit", "page" ] }, "examples": { "example-1": { "value": { "limit": 10, "page": 1, "search": "marketing", "sort_field": "sender_email", "sort_order": "asc" } }, "example-2": { "value": { "limit": 20, "page": 1 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "count": { "type": "number", "description": "Total number of senders matching the search criteria" }, "data": { "type": "array", "items": { "type": "object", "properties": { "sender_email": { "type": "string", "description": "Sender email address" }, "sender_name": { "type": "string", "description": "Display name of the sender" }, "createdDate": { "type": "string", "description": "Creation date of the sender record" }, "status": { "type": "string", "description": "Sender status. Values: Verified, Pending" } } } } } }, "examples": { "example-1": { "value": { "count": 2, "data": [ { "id": "hXUA", "sender_email": "sender1@example.com", "sender_name": "Marketing Team", "createdDate": "2025-01-01 10:00:00", "status": "Verified" }, { "id": "YxGF", "sender_email": "support@example.com", "sender_name": "Support", "createdDate": "2025-01-02 10:00:00", "status": "Verified" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "sort_field", "message": "Invalid sort_field" } ] } }, "example-2": { "value": { "errors": [ { "field": "sort_order", "message": "Invalid sort_order" } ] } }, "example-3": { "value": { "errors": [ { "field": "limit", "message": "limit must be at least 10" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/reply-emails/search": { "post": { "summary": "List Reply Emails", "operationId": "get-all-reply-emails-and-search-reply-emails", "description": "Use this API to return an array of all your active reply-to email addresses. You can filter and search reply emails with pagination.", "tags": [ "Senders" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "description": "Request body type", "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "limit": { "type": "number", "description": "Maximum number of elements to return.\n\nMaximum: 100\nMinimum: 10", "minimum": 10, "maximum": 100 }, "page": { "type": "number", "description": "You can retrieve a subset of records starting from the page value you have specified. You can add a limit, which will determine the number of records you can retrieve on a single page.\n\nStarts From: 1", "minimum": 1 }, "search": { "type": "string", "maxLength": 255, "description": "Filter reply emails by email address. Partial match is supported." } }, "required": [ "limit", "page" ] }, "examples": { "example-1": { "value": { "limit": 10, "page": 1, "search": "support@" } }, "example-2": { "value": { "limit": 20, "page": 1 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "count": { "type": "number", "description": "Total number of reply emails matching the search criteria" }, "data": { "type": "array", "items": { "type": "object", "properties": { "reply_email": { "type": "string", "description": "Reply-to email address" }, "status": { "type": "string", "description": "Reply email status. Values: Verified, Pending" } } } } } }, "examples": { "example-1": { "value": { "count": 2, "data": [ { "id": "ixss", "reply_email": "reply1@example.com", "status": "Verified" }, { "id": "yFXf", "reply_email": "support@example.com", "status": "Verified" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "limit", "message": "limit must be at least 10" } ] } }, "example-2": { "value": { "errors": [ { "field": "page", "message": "page is required" } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": { "error": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "examples": { "example-1": { "value": { "errors": [ { "field": "", "message": "Authorization failed" } ] } } } } } } } } }, "/client/plan": { "get": { "summary": "Client Details", "operationId": "client-details", "description": "API to get current user details", "tags": [ "Account" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "x-examples": { "example-1": { "data": { "email": "user@example.com", "name": "MailerCloud User", "plan": "Enterprise plan", "remaining_contacts": 943, "total_contacts": 1000, "used_contacts": 57 } } }, "properties": { "data": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "description": "Client email" }, "name": { "type": "string", "minLength": 1, "description": "Client name" }, "plan": { "type": "string", "minLength": 1, "description": "Client current plan" }, "remaining_contacts": { "type": "number", "description": "Remaining contact for client" }, "total_contacts": { "type": "number", "description": "Total contacts for client" }, "used_contacts": { "type": "number", "description": "Client used contact count" } } } }, "required": [ "data" ] }, "examples": { "example-1": { "value": { "data": { "email": "user@example.com", "name": "MailerCloud User", "plan": "Enterprise plan", "remaining_contacts": 943, "total_contacts": 1000, "used_contacts": 57 } } } } } } } } } }, "/webform/search": { "post": { "summary": "Webform List", "operationId": "webform-list", "description": "Use this API to return an array of all of your webforms. You can filter, search and sort webforms.", "tags": [ "Webforms" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": false, "description": "application/json", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "limit": 0, "page": 0, "search": "string", "sort_field": "string", "sort_order": "string", "date_from": "string", "date_to": "string", "status": "string" } }, "properties": { "limit": { "type": "number", "description": "Maximum number of elements to return.\n\nMaximum: 100 Minimum: 10" }, "page": { "type": "number", "description": "You can retrieve a subset of records starting from the page value you have specified. You can add a limit, which will determine the number of records you can retrieve on a single page.\n\nStarts From: 1" }, "search": { "type": "string", "minLength": 1, "description": "Filter form by name , giving name in search keyword" }, "sort_field": { "type": "string", "minLength": 1, "description": "Sort list data based on this field\n\nAvailable sort fields - name, modifiedDate, view_count, submission_count, new_contact_count" }, "sort_order": { "type": "string", "minLength": 1, "description": "If sort_field is given then sort_order is required\n\nSorting order for sort field\n\nAvailable sort orders - asc, ASC, desc, DESC" }, "date_from": { "type": "string", "minLength": 1, "description": "Filter forms based on modified date." }, "date_to": { "type": "string", "minLength": 1, "description": "Filter forms based on modified date." }, "status": { "type": "string", "minLength": 1, "description": "Filter forms based on status. Set status to Active to get forms with embed code.\n\nAvailable status \u2013 Active, Inactive, Draft, Duplicate" } }, "required": [ "limit", "page" ] }, "examples": { "example-1": { "value": { "limit": 0, "page": 0, "search": "string", "sort_field": "string", "sort_order": "string", "date_from": "string", "date_to": "string", "status": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "", "type": "object", "x-examples": { "example-1": { "count": 1, "data": [ { "embed_code": "