Newsleopard API Documentation
API Endpoint
https://api.newsleopard.comOverview ¶
Newsleopard’s Campaign API allows developers to automate operations through an API, providing the same functionality as the Newsleopard admin panel with greater flexibility. The Newsleopard API is divided into three main parts:
-
Contacts
-
Campaign
-
Report
For usage instructions for each API, please refer to the respective sections. If you have any questions, please feel free to contact us.
-
Email: service@newsleopard.com
-
Customer Service Hours: Monday to Friday 09:30-12:00 / 13:30-18:00
Authentication
-
When connecting to the API, you must include authentication information in the request header.
key value x-api-keyYour API Key -
If the authentication information is missing or the API key is incorrect, the following will be returned:
{"message": "Forbidden"} -
How to apply for an API KEY?
- Step 1: Register for a Newsleopard account.
- Step 2: Send an email to service@newsleopard.com with the subject
Request for Newsleopard API KEYand include yourregistered account. You will be notified by email upon activation.
Sending Flow Overview
Newsleopard provides the following two methods to meet your basic bulk email sending needs.
Method One
-
Step 1: Create a List
Use Create a List to get a new list ID or Query Lists to get an existing list ID.
-
Step 2: Import Contacts to a Specific List
For a new list, directly use Import Contacts (File Upload) or Import Contacts (Plain Text) to import contacts. For an existing list, you can decide whether to import contacts directly or use Remove Contacts from List to clear the old list before importing.
-
Step 3: Check Import Status
Use the import ID obtained from the previous step with Query Import Status to confirm if the import is complete.
-
Step 4: Create a Campaign to Send
Use Create Campaign to send to the specified list. If you need to perform A/B testing to improve overall performance, you can use Create A/B Testing Campaign.
Suitable for:
- Users who need to manage the sending status of contact lists through Newsleopard, such as permanent bounces, consecutive soft bounces, unsubscribes, and complaints, to avoid subsequent spamming or legal issues.
- Users who need Newsleopard to help check for duplicate emails or incorrect formats in files to avoid subsequent spamming or duplicate sending.
Method Two
-
Step 1: One-time Upload and Create Campaign
Use One-time Upload and Create Campaign or One-time Upload and Create A/B Testing Campaign to directly create a campaign and attach a contact list for bulk sending or A/B testing.
Suitable for:
- Users who, due to special circumstances, need to send to duplicate emails.
- Users who are not allowed to store their contact lists on Newsleopard due to regulations.
Data Retrieval Flow Overview
After creating and sending a campaign, you can follow these steps to obtain relevant data for the campaign, including: delivered, opened, clicked, bounced, complained, and unsubscribed, provided as a CSV file for download.
-
Step 1: Get Campaign ID
Use Query Campaign IDs to get the IDs of completed campaigns.
-
Step 2: Generate Campaign Report
Use Generate Report to generate the campaign report.
-
Step 3: Download Campaign Report
Use Query Report Link to get the download link for the report file.
Rate Limiting
Newsleopard imposes limits on the API call frequency (rate limit) and the total number of daily calls, which are 2 requests/second and 300,000 requests/day, respectively.
Additionally, the Generate Report API has an extra limit of 1 request/10 seconds.
If the call frequency is exceeded, you will receive the following response message:
{"message":"too many requests"}If the total daily call volume is exceeded, you will receive the following response message:
{"message":"Limit Exceeded"}Contacts ¶
Mechanism Description
-
Storage Mechanism:
Newsleopard’s storage mechanism uses the Email address as a unique identifier. A contact can belong to multiple lists. When a list is deleted, the contact is only removed from that list and is not deleted. When a contact is deleted, it is removed from all lists that contain it.
-
Import Mechanism:
- There are two ways to import contacts: one is by plain text, and the other is by uploading a file (recommended for more than 100 contacts). During import, field names are compared to determine whether to update existing field data or add a new one. The format for imported contacts is as follows:
- Plain text format with fields separated by commas (,), utf-8 encoding is recommended.
- The first line should contain the field names, in the order of [EMAIL,NAME,CustomField1,CustomField2,CustomField3…]. The first two fields, EMAIL and NAME, are required and must be in the first and second columns. Therefore, even if you are not importing NAME information, the NAME field must be retained.
- Starting from the second line, place the corresponding values for each field name.
- Custom fields in the contact list serve as variables for that contact. These variables can be placed in the subject or body of the email and will be replaced with the variable value for each contact before sending, achieving personalized emails. For usage, please refer to the Mail Merge Variable Usage section.
- Custom fields are divided into 3 data types (string, number, date). The type is automatically determined based on the data content of the column during import.
- Once a column is automatically determined to be of a certain type during the first import, any subsequent imported data that does not conform to that type will be counted as a failed import.
- To update field content, simply perform the import action again to overwrite the value of the same field name for the same EMAIL. Please note that fields that do not need to be updated should not be included in the import to avoid overwriting their content.
- There are two ways to import contacts: one is by plain text, and the other is by uploading a file (recommended for more than 100 contacts). During import, field names are compared to determine whether to update existing field data or add a new one. The format for imported contacts is as follows:
-
Import Debugging Mechanism:
When importing contacts, the system performs a two-stage check. The first stage checks the structure of the uploaded file. Files that do not conform to the rules are not processed. Reasons for failure are as follows:
- Incorrect file format (the first line must contain field names)
- Duplicate field names in the file
After passing the first stage of inspection, a second stage of content inspection is performed. Data that does not conform to the rules will be counted as failed entries, and a download link for the failed import file will be provided. Reasons for failure are as follows:
- Invalid EMAIL format
- Duplicate EMAIL in the file
- Incorrect format or type of custom field content
- NAME exceeds length limit
Create a List ¶
POST https://api.newsleopard.com/v1/contacts/lists/insert
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"name": "VIP Members List"
}Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "List name",
"examples": [
"VIP Members List"
]
}
},
"required": [
"name"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"sn": "List ID"
}Schema
{
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "List ID",
"examples": [
"List ID"
]
}
}
}Create a ListPOST/v1/contacts/lists/insert
Description
Before sending a campaign with Newsleopard, you need to use this service to create a list and obtain its list ID for subsequent use with Import Contacts (File Upload) or Import Contacts (Plain Text). Subsequent campaign creation and sending are also based on lists.
Request Fields
| Field | Type | Description |
|---|---|---|
name * |
string |
List name |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
sn |
string |
List ID |
Query Lists ¶
GET https://api.newsleopard.com/v1/contacts/lists?size=&page=
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyResponses
Headers
Content-Type: application/jsonBody
[
{
"clickedRate": 0,
"createDate": "2019-04-12T05:45:18Z",
"excludeCnt": 2,
"name": "0412",
"openedRate": 0,
"segVersion": -1,
"sn": "40280a3c6a0cb8c5016a10142a230002",
"status": "GENERAL",
"subscribedCnt": 4963,
"type": 0,
"updateDate": "2019-04-12T05:45:18Z"
},
{
"clickedRate": 0,
"createDate": "2019-03-05T08:19:26Z",
"excludeCnt": 0,
"name": "0305",
"openedRate": 0,
"segVersion": -1,
"sn": "4028d2596923c2fe01694cef9f540000",
"status": "GENERAL",
"subscribedCnt": 5,
"type": 0,
"updateDate": "2019-03-05T08:19:26Z"
},
{
"clickedRate": 0,
"createDate": "2019-02-22T10:13:28Z",
"excludeCnt": 1,
"name": "Test",
"openedRate": 66.6667,
"segVersion": -1,
"sn": "40283c54690f9e63016914b2104d0001",
"status": "GENERAL",
"subscribedCnt": 3,
"type": 0,
"updateDate": "2019-02-22T10:13:28Z"
}
]Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "List ID"
},
"name": {
"type": "string",
"description": "List name"
},
"type": {
"type": "number",
"description": "List type"
},
"status": {
"type": "string",
"description": "Status"
},
"subscribedCnt": {
"type": "number",
"description": "Number of subscribed members"
},
"excludeCnt": {
"type": "number",
"description": "Number of excluded members"
},
"openedRate": {
"type": "number",
"description": "Open rate"
},
"clickedRate": {
"type": "number",
"description": "Click rate"
},
"createDate": {
"type": "string",
"description": "Creation time",
"format": "date-time"
},
"updateDate": {
"type": "string",
"description": "Update time",
"format": "date-time"
}
}
},
"examples": [
[
{
"clickedRate": 0,
"createDate": "2019-04-12T05:45:18Z",
"excludeCnt": 2,
"name": "0412",
"openedRate": 0,
"segVersion": -1,
"sn": "40280a3c6a0cb8c5016a10142a230002",
"status": "GENERAL",
"subscribedCnt": 4963,
"type": 0,
"updateDate": "2019-04-12T05:45:18Z"
},
{
"clickedRate": 0,
"createDate": "2019-03-05T08:19:26Z",
"excludeCnt": 0,
"name": "0305",
"openedRate": 0,
"segVersion": -1,
"sn": "4028d2596923c2fe01694cef9f540000",
"status": "GENERAL",
"subscribedCnt": 5,
"type": 0,
"updateDate": "2019-03-05T08:19:26Z"
},
{
"clickedRate": 0,
"createDate": "2019-02-22T10:13:28Z",
"excludeCnt": 1,
"name": "testing",
"openedRate": 66.6667,
"segVersion": -1,
"sn": "40283c54690f9e63016914b2104d0001",
"status": "GENERAL",
"subscribedCnt": 3,
"type": 0,
"updateDate": "2019-02-22T10:13:28Z"
}
]
]
}Query ListsGET/v1/contacts/lists{?size,page}
Description
You can use this service to query existing list IDs for subsequent use with Import Contacts (File Upload) or Import Contacts (Plain Text). If you need to clear the contacts in an existing list before importing a new batch, you can use Remove Contacts from List to clear the old list first.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
size |
string |
Number of data entries per page |
page |
string |
Page index, 0 for the first page, and so on |
Response Fields
| Field | Type | Description |
|---|---|---|
sn |
string |
List ID |
name |
string |
List name |
subscribedCnt |
number |
Number of valid members in the list |
excludeCnt |
number |
Number of invalid members in the list |
openedRate |
number |
Average open rate of the list, calculated based on valid members with a sending history: total opens / total deliveries |
clickedRate |
number |
Average click rate of the list, calculated based on valid members with a sending history: total clicks / total deliveries |
status |
string |
List status, used to identify if the list is currently importing contacts, including: GENERAL (normal) and PROCESSING (importing). Lists that are importing cannot be selected for sending. |
type |
number |
List type, 0 for a general list; 1 for an auto-segmentation list (not yet available) |
createDate |
string |
Creation time |
updateDate |
string |
Update time |
URI Parameters
- size
string(optional)Number of data entries per page
- page
string(optional)Page index, starting from 0 (e.g., page=0 for the first page, page=1 for the second page)
Import Contacts (File Upload) ¶
POST https://api.newsleopard.com/v1/contacts/imports/40280a3c6a0cb8c5016a10142a230002/file
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"webhookUrl": "https://yours.webhook.com.tw"
}Schema
{
"type": "object",
"properties": {
"webhookUrl": {
"type": "string",
"description": "Webhook URL",
"examples": [
"https://yours.webhook.com.tw"
]
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"import_sn": "45093ba5-4bb5-47b2-a2c7-40ae4ff646b6",
"url": "https://s3.amazonaws.com/..."
}Schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Import contacts URL",
"examples": [
"https://s3.amazonaws.com/..."
]
},
"import_sn": {
"type": "string",
"description": "Import ID",
"examples": [
"45093ba5-4bb5-47b2-a2c7-40ae4ff646b6"
]
}
}
}This response has no content.
Import Contacts (File Upload)POST/v1/contacts/imports/{list_sn}/file
Description
If you have more than 100 contacts, it is recommended to use this service to import contacts as a file into a list ID obtained from Create a List or an existing list ID from Query Lists.
Flow
-
Step 1: Call this API to get the URL for uploading the contact file.
-
Step 2: For the file format, please refer to the Import Mechanism Description section.
-
Step 3: Use the PUT method to upload the file in binary format to the URL obtained in Step 1.
-
Step 4: After the file is successfully uploaded, please confirm the import status before creating a campaign.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
list_sn * |
string |
List ID |
* Required field
Request Fields
| Field | Type | Description |
|---|---|---|
webhookUrl |
string |
After the import is complete, the system will send a POST request to the webhookUrl. The format of the response is the same as the return value of Query Import Status. |
Response Fields
| Field | Type | Description |
|---|---|---|
import_sn |
string |
Import ID, used for querying the import status later. |
url |
string |
Upload list file link. |
Notes
-
Since importing a large number of contacts takes time, this service returns the import status asynchronously.
-
If no webhookUrl is provided, you can also use Query Import Status to get the import status.
URI Parameters
- list_sn
string(required) Example: 40280a3c6a0cb8c5016a10142a230002List ID
Import Contacts (Plain Text) ¶
POST https://api.newsleopard.com/v1/contacts/imports/40280a3c6a0cb8c5016a10142a230002/text
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"contacts": "EMAIL,NAME\nuser1@newsleopard.com,Member1\nuser2@newsleopard.com,Member2"
}Schema
{
"type": "object",
"properties": {
"contacts": {
"type": "string",
"description": "Import contacts content",
"examples": [
"EMAIL,NAME\nuser1@newsleopard.com,Member1\nuser2@newsleopard.com,Member2"
]
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"import_sn": "45093ba5-4bb5-47b2-a2c7-40ae4ff646b6"
}Schema
{
"type": "object",
"properties": {
"import_sn": {
"type": "string",
"description": "Import ID",
"examples": [
"45093ba5-4bb5-47b2-a2c7-40ae4ff646b6"
]
}
}
}This response has no content.
Import Contacts (Plain Text)POST/v1/contacts/imports/{list_sn}/text
Description
If you have fewer than 100 contacts, it is recommended to use this service to import contacts as plain text into a list ID obtained from Create a List or an existing list ID from Query Lists.
Flow
-
Step 1: Call this API and include the contact content. For the format, please refer to the Mechanism Description section, and use \n as the newline character.
-
Step 2: After the file is successfully uploaded, please use the import ID to check the import status via Query Import Status before creating a campaign.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
list_sn * |
string |
List ID |
* Required field
Request Fields
| Field | Type | Description |
|---|---|---|
contacts * |
string |
Content of the contacts to import |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
import_sn |
string |
Import ID, used for querying the import status later. |
Notes
The payload size must not exceed 10 MB.
URI Parameters
- list_sn
string(required) Example: 40280a3c6a0cb8c5016a10142a230002List ID
Query Import Status ¶
GET https://api.newsleopard.com/v1/contacts/imports/result/import_sn
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyResponses
Headers
Content-Type: application/jsonBody
{
"import_sn": "45093ba5-4bb5-47b2-a2c7-40ae4ff646b6",
"status": "PROCESSING",
"fileCnt": 100,
"insertCnt": 85,
"duplicateCnt": 5,
"errCnt": 10,
"createDate": "2019-03-05T08:19:26Z",
"completedDate": "2019-03-05T08:19:26Z",
"errorDownloadLink": "https://s3.amazonaws.com/prod-member-upload/import/xxx/error-file.csv"
}Schema
{
"type": "object",
"properties": {
"import_sn": {
"type": "string",
"description": "Import ID",
"examples": [
"45093ba5-4bb5-47b2-a2c7-40ae4ff646b6"
]
},
"status": {
"type": "string",
"description": "Import status",
"enum": [
"PROCESSING",
"COMPLETE",
"DUPLICATE_HEADER",
"ERROR",
"MISSING_REQUIRED_DATA"
],
"examples": [
"COMPLETE"
]
},
"fileCnt": {
"type": "integer",
"description": "File count",
"examples": [
100
]
},
"insertCnt": {
"type": "integer",
"description": "Insert count",
"examples": [
85
]
},
"duplicateCnt": {
"type": "integer",
"description": "Duplicate count",
"examples": [
5
]
},
"errCnt": {
"type": "integer",
"description": "Error count",
"examples": [
10
]
},
"createDate": {
"type": "string",
"description": "Creation time",
"examples": [
"2019-03-05T08:19:26Z"
]
},
"completedDate": {
"type": "string",
"description": "Completion time",
"examples": [
"2019-03-05T08:19:26Z"
]
},
"errorDownloadLink": {
"type": "string",
"description": "Error list download link",
"examples": [
"https://s3.amazonaws.com/prod-member-upload/import/xxx/error-file.csv"
]
}
}
}This response has no content.
Query Import StatusGET/v1/contacts/imports/result/{import_sn}
Description
After importing contacts to a specified list via Import Contacts (File Upload) or Import Contacts (Plain Text), this service allows you to query the current import status using the import ID to confirm if the contacts have been processed.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
import_sn * |
string |
Import ID |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
import_sn |
string |
Import ID |
status |
string |
Import status, divided into the following: |
| - PROCESSING: Processing | ||
| - COMPLETE: Import complete | ||
| - DUPLICATE_HEADER: Duplicate field names in the file, cannot import | ||
| - ERROR: Import failed | ||
| - MISSING_REQUIRED_DATA: Missing required file for import | ||
fileCnt |
number |
Total number of entries in the file |
insertCnt |
number |
Number of successfully added or updated entries |
duplicateCnt |
number |
Number of duplicate entries in the file, which will be listed in the failed import file. Please refer to the Mechanism Description section. |
errCnt |
number |
Number of entries that could not be imported, which will be listed in the failed import file. Please refer to the Mechanism Description section. |
createDate |
string |
Creation time |
completedDate |
string |
Completion time |
errorDownloadLink |
string |
Download link for the failed import file, providing the failed contacts and the reasons for failure. |
Notes
Only import statuses from the last 30 days can be queried.
URI Parameters
- import_sn
string(required)Import ID (obtained from the
Contact Import API)
Remove Contacts from List ¶
DELETE https://api.newsleopard.com/v1/contacts/40280a3c6a0cb8c5016a10142a230002
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"filters": [
{
"columnName": "DOMAIN",
"operator": "EQ",
"value": "gmail.com"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"filters": {
"type": "array"
}
}
}Responses
Body
0 (updated_count)Headers
Content-Type: application/jsonBody
{
"code": 40050304
"message": "invalid params"
}Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"keys": [
"user1@newsleopard.com",
"user2@newsleopard.com"
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"keys": {
"type": "array"
}
},
"required": [
"keys"
]
}Responses
Body
0 (updated_count)Remove Contacts from ListDELETE/v1/contacts/{list_sn}
Description
This service allows you to remove contacts from a specific list by filtering conditions or specifying contacts, in order to organize the composition of an existing list.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
list_sn * |
string |
List ID |
* Required field
Request Fields
| Field | Type | Description |
|---|---|---|
columnName |
string |
Filterable conditions, including: ・NAME: Contact’s NAME ・MAIL_ADDRESS: EMAIL address ・DOMAIN: Email Domain ・LISTSN: List ID ・Custom field name: Custom field name defined during import |
operator |
string |
Comparison operators, including: ・EQ: Equal ・NOT_EQ: Not equal ・LIKE: Like ・NOT_LIKE: Not like |
value |
string |
Filter value |
Response Fields
| Field | Type | Description |
|---|---|---|
updated_count |
number |
Number of contacts removed from the list |
Error Message Description
| Error Code | Description |
|---|---|
40050304 |
Invalid custom field name |
40050305 |
Missing filters or keys |
40050306 |
Invalid field name |
40050307 |
Invalid comparison operator |
40050308 |
The list to be removed from does not exist |
Notes
Comparison operations for custom fields of date and number types are not yet supported. Please be aware of this when using.
URI Parameters
- list_sn
string(required) Example: 40280a3c6a0cb8c5016a10142a230002List ID
Campaign ¶
Mail Merge Variable Usage
Description
Newsleopard allows you to place variables in the email subject or body, which are automatically replaced with the variable’s value before sending to achieve personalized emails. The format for using variables is ${CustomFieldName}. For detailed information on variables, please refer to the Mechanism Description.
Create Campaign ¶
POST https://api.newsleopard.com/v1/campaign/normal/submit
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"form": {
"name": "Campaign Name",
"selectedLists": [
"40280a3c6a0cb8c5016a10142a230001",
"40280a3c6a0cb8c5016a10142a230003"
],
"excludeLists": [
"40280a3c6a0cb8c5016a10142a230001",
"40280a3c6a0cb8c5016a10142a230001"
]
},
"config": {
"schedule": {
"type": 0,
"timezone": 21,
"scheduleDate": "2019-07-05T06:00:28.000Z"
},
"ga": {
"enable": true,
"ecommerceEnable": "boolean",
"utmCampaign": "spring_sale",
"utmContent": "logolink"
}
},
"content": {
"preheader": "Subject preview text",
"subject": "Email Subject",
"fromName": "Sender Name",
"fromAddress": "name@example.com",
"htmlContent": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content</p></body></html>",
"footerLang": 1
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"form": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
},
"selectedLists": {
"type": "array",
"description": "List of lists to send to [1 or more]"
},
"excludeLists": {
"type": "array",
"description": "List of lists to exclude"
}
},
"required": [
"name",
"selectedLists",
"excludeLists"
]
},
"config": {
"type": "object",
"properties": {
"schedule": {
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "Sending type"
},
"timezone": {
"type": "number",
"description": "Timezone code"
},
"scheduleDate": {
"type": "string",
"description": "Scheduled sending time UTC+0"
}
},
"required": [
"type",
"timezone",
"scheduleDate"
]
},
"ga": {
"type": "object",
"properties": {
"enable": {
"type": "boolean",
"description": "Enable GA analytics true / false. If true, utmCampaign and utmContent must be provided."
},
"ecommerceEnable": {
"type": "string",
"description": "Enable GA e-commerce analytics"
},
"utmCampaign": {
"type": "string",
"description": "utmCampaign content"
},
"utmContent": {
"type": "string",
"description": "utmContent content"
}
},
"required": [
"enable",
"ecommerceEnable"
]
}
},
"required": [
"schedule",
"ga"
]
},
"content": {
"type": "object",
"properties": {
"preheader": {
"type": "string",
"description": "Subject preview text"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"fromName": {
"type": "string",
"description": "Sender name"
},
"fromAddress": {
"type": "string",
"description": "Sender address"
},
"htmlContent": {
"type": "string",
"description": "Email content"
},
"footerLang": {
"type": "number",
"description": "Footer language 0 = English, 1 = Chinese"
}
},
"required": [
"subject",
"fromName",
"fromAddress",
"htmlContent",
"footerLang"
]
}
},
"required": [
"form",
"config",
"content"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"sn": "Campaign ID"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "Campaign ID"
}
},
"required": [
"sn"
]
}Headers
Content-Type: application/jsonBody
{
"code": "40001",
"invalidFields": "Field-related error message"
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"examples": [
"40001"
]
},
"invalidFields": {
"type": "string",
"description": "Message",
"examples": [
"Field-related error message"
]
}
}
}Create CampaignPOST/v1/campaign/normal/submit
Description
This service provides general campaign sending. Before using it, please ensure that you have completed list creation and contact import. If you need to perform A/B testing during the campaign, you can refer to Create A/B Testing Campaign.
Request Fields
| Field | Type | Description |
|---|---|---|
form.name * |
string |
Campaign name, customizable, not displayed in the email |
form.selectedLists * |
array |
List IDs to send to, 1 or more |
form.excludeLists * |
array |
List IDs to exclude from sending, 1 or more. Contacts in excludeLists will not be sent to, even if they exist in selectedLists. |
content.preheader |
string |
Subject preview text, must not exceed 60 characters |
content.subject * |
string |
Email subject, must not exceed 150 characters |
content.fromName * |
string |
Sender name, must not exceed 50 characters |
content.fromAddress * |
string |
Sender address, the sender’s email address must be verified through the Newsleopard admin panel |
content.htmlContent * |
string |
Email content |
content.footerLang * |
number |
Footer message language, 0: English; 1: Chinese |
config.schedule.type * |
number |
Sending type, 0: Send immediately; 1: Schedule sending |
config.schedule.timezone |
number |
Refer to the attached Timezone Code Table |
config.schedule.scheduleDate |
string |
Scheduled sending time, format example: 2019-04-01T08:38:32.00ZPlease ensure the date and time are in UTC+0 and are not in the past. |
config.ga.enable * |
boolean |
Whether to enable GA traffic tracking. If true, utmCampaign and utmContent must be provided. |
config.ga.ecommerceEnable * |
boolean |
Whether to enable GA e-commerce analytics. If true, GA tracking must also be true, and utmCampaign and utmContent must be provided. |
config.ga.utmCampaign |
string |
utm_campaign content |
config.ga.utmContent |
string |
utm_content content |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
sn |
string |
Campaign ID |
Error Message Description
| Error Code | Description |
|---|---|
40001 |
Field error |
40003 |
Invalid EMAIL |
40004 |
Disallowed DOMAIN |
40007 |
Invalid SN |
40008 |
Unsupported file format |
40009 |
File content is empty |
40010 |
File size exceeds limit |
40011 |
Unverified sender address |
40012 |
Insufficient balance |
40013 |
No contacts to send to |
40014 |
Invalid campaign content |
40015 |
Invalid sending information |
40017 |
Insufficient balance for testing |
40019 |
Incorrect schedule time |
40020 |
Invalid date format |
One-time Upload and Create Campaign ¶
POST https://api.newsleopard.com/v1/campaign/normal/once
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"form": {
"name": "Campaign Name"
},
"config": {
"schedule": {
"type": 0,
"timezone": 21,
"scheduleDate": "2019-07-05T06:00:28.000Z"
},
"ga": {
"enable": true,
"ecommerceEnable": false,
"utmCampaign": "spring_sale",
"utmContent": "logolink"
}
},
"content": {
"preheader": "Subject preview text",
"subject": "Email Subject",
"fromName": "Sender Name",
"fromAddress": "name@example.com",
"htmlContent": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content</p></body></html>",
"footerLang": 1
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"form": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
}
},
"required": [
"name"
]
},
"config": {
"type": "object",
"properties": {
"schedule": {
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "Sending type"
},
"timezone": {
"type": "number",
"description": "Timezone code"
},
"scheduleDate": {
"type": "string",
"description": "Scheduled sending time UTC+0"
}
},
"required": [
"type",
"timezone",
"scheduleDate"
]
},
"ga": {
"type": "object",
"properties": {
"enable": {
"type": "boolean",
"description": "Enable GA analytics true / false. If true, utmCampaign and utmContent must be provided."
},
"ecommerceEnable": {
"type": "boolean",
"description": "Enable GA e-commerce analytics"
},
"utmCampaign": {
"type": "string",
"description": "utmCampaign content"
},
"utmContent": {
"type": "string",
"description": "utmContent content"
}
},
"required": [
"enable",
"ecommerceEnable"
]
}
},
"required": [
"schedule",
"ga"
]
},
"content": {
"type": "object",
"properties": {
"preheader": {
"type": "string",
"description": "Subject preview text"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"fromName": {
"type": "string",
"description": "Sender name"
},
"fromAddress": {
"type": "string",
"description": "Sender address"
},
"htmlContent": {
"type": "string",
"description": "Email content"
},
"footerLang": {
"type": "number",
"description": "Footer language 0 = English, 1 = Chinese"
}
},
"required": [
"subject",
"fromName",
"fromAddress",
"htmlContent",
"footerLang"
]
}
},
"required": [
"form",
"config",
"content"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"sn": "Campaign ID",
"preSignedUrl": "File upload URL"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "Campaign ID"
},
"preSignedUrl": {
"type": "string",
"description": "File upload URL"
}
},
"required": [
"sn",
"preSignedUrl"
]
}Headers
Content-Type: application/jsonBody
{
"code": "40001",
"invalidFields": "Field-related error message"
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"examples": [
"40001"
]
},
"invalidFields": {
"type": "string",
"description": "Message",
"examples": [
"Field-related error message"
]
}
}
}One-time Upload and Create CampaignPOST/v1/campaign/normal/once
Description
For members who do not want to store their contact lists on the Newsleopard platform, Newsleopard also provides a one-time upload and create campaign function. The contacts are sent immediately after upload and are not stored. You can still use the campaign ID to view related reports later.
Flow
-
Step 1: Create a campaign (please refer to Create Campaign, no need to provide form.selectedLists and form.excludeLists)
-
Step 2: According to the preSignedUrl in the Response, upload the contact file for this time (the upload method is the same as Import Contacts (File Upload))
Request Fields
| Field | Type | Description |
|---|---|---|
form.name * |
string |
Campaign name, customizable, not displayed in the email |
content.preheader |
string |
Subject preview text, must not exceed 60 characters |
content.subject * |
string |
Email subject, must not exceed 150 characters |
content.fromName * |
string |
Sender name, must not exceed 50 characters |
content.fromAddress * |
string |
Sender address, the sender’s email address must be verified through the Newsleopard admin panel |
content.htmlContent * |
string |
Email content |
content.footerLang * |
number |
Footer message language, 0: English; 1: Chinese |
config.schedule.type * |
number |
Sending type, 0: Send immediately; 1: Schedule sending |
config.schedule.timezone |
number |
Refer to the attached Timezone Code Table |
config.schedule.scheduleDate |
string |
Scheduled sending time, format example: 2019-04-01T08:38:32.00ZPlease ensure the date and time are in UTC+0 and are not in the past. |
config.ga.enable * |
boolean |
Whether to enable GA traffic tracking. If true, utmCampaign and utmContent must be provided. |
config.ga.ecommerceEnable * |
boolean |
Whether to enable GA e-commerce analytics. If true, GA tracking must also be true, and utmCampaign and utmContent must be provided. |
config.ga.utmCampaign |
string |
utm_campaign content |
config.ga.utmContent |
string |
utm_content content |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
sn |
string |
Campaign ID |
preSignedUrl |
string |
URL for uploading the contact file for this time |
Error Message Description
| Error Code | Description |
|---|---|
40001 |
Field error |
40003 |
Invalid EMAIL |
40004 |
Disallowed DOMAIN |
40007 |
Invalid SN |
40008 |
Unsupported file format |
40009 |
File content is empty |
40010 |
File size exceeds limit |
40011 |
Unverified sender address |
40014 |
Invalid campaign content |
40015 |
Invalid sending information |
40019 |
Incorrect schedule time |
40020 |
Invalid date format |
Notes
-
The system will not check the format or for duplicate emails in the one-time uploaded contact file. Please be aware.
-
The one-time uploaded contact file will not be imported into the system.
Create A/B Testing Campaign ¶
POST https://api.newsleopard.com/v1/campaign/testing/submit
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"form": {
"name": "Campaign Name",
"selectedLists": [
"40280a3c6a0cb8c5016a10142a230001",
"40280a3c6a0cb8c5016a10142a230003"
],
"excludeLists": [
"40280a3c6a0cb8c5016a10142a230001",
"40280a3c6a0cb8c5016a10142a230001"
]
},
"config": {
"schedule": {
"type": 0,
"timezone": 21,
"scheduleDate": "2019-07-05T06:00:28.000Z"
},
"ga": {
"enable": true,
"ecommerceEnable": false,
"utmCampaign": "spring_sale",
"utmContent": "logolink"
}
},
"content": {
"preheaderA": "Subject preview text A",
"preheaderB": "Subject preview text B",
"subjectA": "Email Subject A",
"subjectB": "Email Subject B",
"fromName": "Sender Name",
"fromAddress": "name@example.com",
"htmlContent": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content</p></body></html>",
"footerLang": 1,
"testingOn": 1,
"testing": {
"proportion": 10,
"time": 1,
"unit": 0
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"form": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
},
"selectedLists": {
"type": "array",
"description": "List of lists to send to [1 or more]"
},
"excludeLists": {
"type": "array",
"description": "List of lists to exclude"
}
},
"required": [
"name",
"selectedLists",
"excludeLists"
]
},
"config": {
"type": "object",
"properties": {
"schedule": {
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "Sending type"
},
"timezone": {
"type": "number",
"description": "Timezone code"
},
"scheduleDate": {
"type": "string",
"description": "Scheduled sending time UTC+0"
}
},
"required": [
"type",
"timezone",
"scheduleDate"
]
},
"ga": {
"type": "object",
"properties": {
"enable": {
"type": "boolean",
"description": "Enable GA analytics true / false. If true, utmCampaign and utmContent must be provided."
},
"ecommerceEnable": {
"type": "boolean",
"description": "Enable GA e-commerce analytics"
},
"utmCampaign": {
"type": "string",
"description": "utmCampaign content"
},
"utmContent": {
"type": "string",
"description": "utmContent content"
}
},
"required": [
"enable",
"ecommerceEnable"
]
}
},
"required": [
"schedule",
"ga"
]
},
"content": {
"type": "object",
"properties": {
"preheaderA": {
"type": "string",
"description": "Subject preview text A - when testingOn = 1"
},
"preheaderB": {
"type": "string",
"description": "Subject preview text B - when testingOn = 1"
},
"subjectA": {
"type": "string",
"description": "Email Subject A - when testingOn = 1 [required]"
},
"subjectB": {
"type": "string",
"description": "Email Subject B - when testingOn = 1 [required]"
},
"fromName": {
"type": "string",
"description": "Sender name"
},
"fromAddress": {
"type": "string",
"description": "Sender address"
},
"htmlContent": {
"type": "string",
"description": "Email content"
},
"footerLang": {
"type": "number",
"description": "Footer language 0 = English, 1 = Chinese"
},
"testingOn": {
"type": "number",
"description": "Test type"
},
"testing": {
"type": "object",
"properties": {
"proportion": {
"type": "number",
"description": "Test member ratio - range: 0 ~ 100"
},
"time": {
"type": "number",
"description": "Time"
},
"unit": {
"type": "number",
"description": "Unit hour = 0, day = 1"
}
},
"required": [
"proportion",
"time",
"unit"
]
}
},
"required": [
"subjectA",
"subjectB",
"fromName",
"fromAddress",
"htmlContent",
"footerLang",
"testingOn"
]
}
},
"required": [
"form",
"config",
"content"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"sn": "Campaign ID"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "Campaign ID"
}
},
"required": [
"sn"
]
}Headers
Content-Type: application/jsonBody
{
"code": "40001",
"invalidFields": "Field-related error message"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {}
}Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"form": {
"name": "Campaign Name",
"selectedLists": [
"40280a3c6a0cb8c5016a10142a230001",
"40280a3c6a0cb8c5016a10142a230003"
],
"excludeLists": [
"40280a3c6a0cb8c5016a10142a230001",
"40280a3c6a0cb8c5016a10142a230001"
]
},
"config": {
"schedule": {
"type": 0,
"timezone": 21,
"scheduleDate": "2019-07-05T06:00:28.000Z"
},
"ga": {
"enable": true,
"ecommerceEnable": false,
"utmCampaign": "spring_sale",
"utmContent": "logolink"
}
},
"content": {
"preheader": "Subject preview text",
"subject": "Email Subject",
"fromNameA": "Sender Name A",
"fromNameB": "Sender Name B",
"fromAddressA": "nameA@example.com",
"fromAddressB": "nameB@example.com",
"htmlContent": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content</p></body></html>",
"footerLang": 1,
"testingOn": 2,
"testing": {
"proportion": 10,
"time": 1,
"unit": 0
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"form": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
},
"selectedLists": {
"type": "array",
"description": "List of lists to send to [1 or more]"
},
"excludeLists": {
"type": "array",
"description": "List of lists to exclude"
}
},
"required": [
"name",
"selectedLists",
"excludeLists"
]
},
"config": {
"type": "object",
"properties": {
"schedule": {
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "Sending type"
},
"timezone": {
"type": "number",
"description": "Timezone code"
},
"scheduleDate": {
"type": "string",
"description": "Scheduled sending time UTC+0"
}
},
"required": [
"type",
"timezone",
"scheduleDate"
]
},
"ga": {
"type": "object",
"properties": {
"enable": {
"type": "boolean",
"description": "Enable GA analytics true / false. If true, utmCampaign and utmContent must be provided."
},
"ecommerceEnable": {
"type": "boolean",
"description": "Enable GA e-commerce analytics"
},
"utmCampaign": {
"type": "string",
"description": "utmCampaign content"
},
"utmContent": {
"type": "string",
"description": "utmContent content"
}
},
"required": [
"enable",
"ecommerceEnable"
]
}
},
"required": [
"schedule",
"ga"
]
},
"content": {
"type": "object",
"properties": {
"preheader": {
"type": "string",
"description": "Subject preview text"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"fromNameA": {
"type": "string",
"description": "Sender Name A - when testingOn = 2 [required]"
},
"fromNameB": {
"type": "string",
"description": "Sender Name B - when testingOn = 2 [required]"
},
"fromAddressA": {
"type": "string",
"description": "Sender Address A - when testingOn = 2 [required]"
},
"fromAddressB": {
"type": "string",
"description": "Sender Address B - when testingOn = 2 [required]"
},
"htmlContent": {
"type": "string",
"description": "Email content"
},
"footerLang": {
"type": "number",
"description": "Footer language 0 = English, 1 = Chinese"
},
"testingOn": {
"type": "number",
"description": "Test type"
},
"testing": {
"type": "object",
"properties": {
"proportion": {
"type": "number",
"description": "Test member ratio - range: 0 ~ 100"
},
"time": {
"type": "number",
"description": "Time"
},
"unit": {
"type": "number",
"description": "Unit hour = 0, day = 1"
}
},
"required": [
"proportion",
"time",
"unit"
]
}
},
"required": [
"subject",
"fromNameA",
"fromNameB",
"fromAddressA",
"fromAddressB",
"htmlContent",
"footerLang",
"testingOn"
]
}
},
"required": [
"form",
"config",
"content"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"sn": "Campaign ID"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "Campaign ID"
}
},
"required": [
"sn"
]
}Headers
Content-Type: application/jsonBody
{
"code": "40001",
"invalidFields": "Field-related error message"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {}
}Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"form": {
"name": "Campaign Name",
"selectedLists": [
"40280a3c6a0cb8c5016a10142a230001",
"40280a3c6a0cb8c5016a10142a230003"
],
"excludeLists": [
"40280a3c6a0cb8c5016a10142a230001",
"40280a3c6a0cb8c5016a10142a230001"
]
},
"config": {
"schedule": {
"type": 0,
"timezone": 21,
"scheduleDate": "2019-07-05T06:00:28.000Z"
},
"ga": {
"enable": true,
"ecommerceEnable": false,
"utmCampaign": "spring_sale",
"utmContent": "logolink"
},
"content": {
"preheader": "Subject preview text",
"subject": "Email Subject",
"fromName": "Sender Name",
"fromAddress": "name@example.com",
"htmlContentA": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content A</p></body></html>",
"htmlContentB": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content B</p></body></html>",
"footerLang": 1,
"testingOn": 3,
"testing": {
"proportion": 10,
"time": 1,
"unit": 0
}
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"form": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
},
"selectedLists": {
"type": "array",
"description": "List of lists to send to [1 or more]"
},
"excludeLists": {
"type": "array",
"description": "List of lists to exclude"
}
},
"required": [
"name",
"selectedLists",
"excludeLists"
]
},
"config": {
"type": "object",
"properties": {
"schedule": {
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "Sending type"
},
"timezone": {
"type": "number",
"description": "Timezone code"
},
"scheduleDate": {
"type": "string",
"description": "Scheduled sending time UTC+0"
}
},
"required": [
"type",
"timezone",
"scheduleDate"
]
},
"ga": {
"type": "object",
"properties": {
"enable": {
"type": "boolean",
"description": "Enable GA analytics true / false. If true, utmCampaign and utmContent must be provided."
},
"ecommerceEnable": {
"type": "boolean",
"description": "Enable GA e-commerce analytics"
},
"utmCampaign": {
"type": "string",
"description": "utmCampaign content"
},
"utmContent": {
"type": "string",
"description": "utmContent content"
}
},
"required": [
"enable",
"ecommerceEnable"
]
},
"content": {
"type": "object",
"properties": {
"preheader": {
"type": "string",
"description": "Subject preview text"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"fromName": {
"type": "string",
"description": "Sender name"
},
"fromAddress": {
"type": "string",
"description": "Sender address"
},
"htmlContentA": {
"type": "string",
"description": "Email content A"
},
"htmlContentB": {
"type": "string",
"description": "Email content B"
},
"footerLang": {
"type": "number",
"description": "Footer language 0 = English, 1 = Chinese"
},
"testingOn": {
"type": "number",
"description": "Test type"
},
"testing": {
"type": "object",
"properties": {
"proportion": {
"type": "number",
"description": "Test member ratio - range: 0 ~ 100"
},
"time": {
"type": "number",
"description": "Time"
},
"unit": {
"type": "number",
"description": "Unit hour = 0, day = 1"
}
},
"required": [
"proportion",
"time",
"unit"
]
}
},
"required": [
"subject",
"fromName",
"fromAddress",
"htmlContentA",
"htmlContentB",
"footerLang",
"testingOn"
]
}
},
"required": [
"schedule",
"ga",
"content"
]
}
},
"required": [
"form",
"config"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"sn": "Campaign ID"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "Campaign ID"
}
},
"required": [
"sn"
]
}Headers
Content-Type: application/jsonBody
{
"code": "40001",
"invalidFields": "Field-related error message"
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"examples": [
"40001"
]
},
"invalidFields": {
"type": "string",
"description": "Message",
"examples": [
"Field-related error message"
]
}
}
}Create A/B Testing CampaignPOST/v1/campaign/testing/submit
Description
Newsleopard provides three types of A/B testing: subject, sender, and content. During the campaign, according to the set test ratio, the sending list is divided into A and B groups, which are sent A and B versions of the email respectively. According to the set test time, the better-performing version is confirmed and sent to the remaining un-grouped contacts, thereby improving the overall effectiveness of the campaign.
Request Fields
| Field | Type | Description |
|---|---|---|
form.name * |
string |
Campaign name, customizable, not displayed in the email |
form.selectedLists * |
array |
List IDs to send to, 1 or more |
form.excludeLists * |
array |
List IDs to exclude from sending, 1 or more. Contacts in excludeLists will not be sent to, even if they exist in selectedLists. |
content.preheaderA |
string |
Version A subject preview text, must not exceed 60 characters |
content.preheaderB |
string |
Version B subject preview text, must not exceed 60 characters |
content.subjectA * |
string |
Version A email subject, must not exceed 150 characters |
content.subjectB * |
string |
Version B email subject, must not exceed 150 characters |
content.fromNameA * |
string |
Version A sender name, must not exceed 50 characters |
content.fromNameB * |
string |
Version B sender name, must not exceed 50 characters |
content.fromAddressA * |
string |
Version A sender address, the sender’s email address must be verified through the Newsleopard admin panel |
content.fromAddressB * |
string |
Version B sender address, the sender’s email address must be verified through the Newsleopard admin panel |
content.htmlContentA * |
string |
Version A email content |
content.htmlContentB * |
string |
Version B email content |
content.footerLang * |
number |
Footer message language, 0: English; 1: Chinese |
content.testingOn * |
number |
A/B testing type, 1: Subject A/B testing; 2: Sender name and address A/B testing; 3: Content A/B testing |
content.testing.proportion * |
number |
A/B testing ratio, 0-100, in %. The system will automatically grab contacts from the selectedLists for A and B grouping based on the set ratio. |
content.testing.time * |
number |
A/B testing duration. When the time is up, the performance of the A/B versions will be automatically judged, and the better version will be sent to the remaining un-grouped contacts. |
content.testing.unit * |
number |
A/B testing time unit, 0: hour; 1: day |
config.schedule.type * |
number |
Sending type, 0: Send immediately; 1: Schedule sending |
config.schedule.timezone |
number |
Refer to the attached Timezone Code Table |
config.schedule.scheduleDate |
string |
Scheduled sending time, format example: 2019-04-01T08:38:32.00ZPlease ensure the date and time are in UTC+0 and are not in the past. |
config.ga.enable * |
boolean |
Whether to enable GA traffic tracking. If true, utmCampaign and utmContent must be provided. |
config.ga.ecommerceEnable * |
boolean |
Whether to enable GA e-commerce analytics. If true, GA tracking must also be true, and utmCampaign and utmContent must be provided. |
config.ga.utmCampaign |
string |
utm_campaign content |
config.ga.utmContent |
string |
utm_content content |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
sn |
string |
Campaign ID |
Error Message Description
| Error Code | Description |
|---|---|
40001 |
Field error |
40003 |
Invalid EMAIL |
40004 |
Disallowed DOMAIN |
40007 |
Invalid SN |
40008 |
Unsupported file format |
40009 |
File content is empty |
40010 |
File size exceeds limit |
40011 |
Unverified sender address |
40012 |
Insufficient balance |
40013 |
No contacts to send to |
40014 |
Invalid campaign content |
40015 |
Invalid sending information |
40017 |
Insufficient balance for testing |
40019 |
Incorrect schedule time |
40020 |
Invalid date format |
One-time Upload and Create A/B Testing Campaign ¶
POST https://api.newsleopard.com/v1/campaign/testing/once
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"form": {
"name": "Campaign Name"
},
"config": {
"schedule": {
"type": 0,
"timezone": 21,
"scheduleDate": "2019-07-05T06:00:28.000Z"
},
"ga": {
"enable": true,
"ecommerceEnable": false,
"utmCampaign": "spring_sale",
"utmContent": "logolink"
}
},
"content": {
"preheaderA": "Subject preview text A",
"preheaderB": "Subject preview text B",
"subjectA": "Email Subject A",
"subjectB": "Email Subject B",
"fromName": "Sender Name",
"fromAddress": "name@example.com",
"htmlContent": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content</p></body></html>",
"footerLang": 1,
"testingOn": 1,
"testing": {
"proportion": 10,
"time": 1,
"unit": 0
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"form": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
}
},
"required": [
"name"
]
},
"config": {
"type": "object",
"properties": {
"schedule": {
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "Sending type"
},
"timezone": {
"type": "number",
"description": "Timezone code"
},
"scheduleDate": {
"type": "string",
"description": "Scheduled sending time UTC+0"
}
},
"required": [
"type",
"timezone",
"scheduleDate"
]
},
"ga": {
"type": "object",
"properties": {
"enable": {
"type": "boolean",
"description": "Enable GA analytics true / false. If true, utmCampaign and utmContent must be provided."
},
"ecommerceEnable": {
"type": "boolean",
"description": "Enable GA e-commerce analytics"
},
"utmCampaign": {
"type": "string",
"description": "utmCampaign content"
},
"utmContent": {
"type": "string",
"description": "utmContent content"
}
},
"required": [
"enable",
"ecommerceEnable"
]
}
},
"required": [
"schedule",
"ga"
]
},
"content": {
"type": "object",
"properties": {
"preheaderA": {
"type": "string",
"description": "Subject preview text A - when testingOn = 1"
},
"preheaderB": {
"type": "string",
"description": "Subject preview text B - when testingOn = 1"
},
"subjectA": {
"type": "string",
"description": "Email Subject A - when testingOn = 1 [required]"
},
"subjectB": {
"type": "string",
"description": "Email Subject B - when testingOn = 1 [required]"
},
"fromName": {
"type": "string",
"description": "Sender name"
},
"fromAddress": {
"type": "string",
"description": "Sender address"
},
"htmlContent": {
"type": "string",
"description": "Email content"
},
"footerLang": {
"type": "number",
"description": "Footer language 0 = English, 1 = Chinese"
},
"testingOn": {
"type": "number",
"description": "Test type"
},
"testing": {
"type": "object",
"properties": {
"proportion": {
"type": "number",
"description": "Test member ratio - range: 0 ~ 100"
},
"time": {
"type": "number",
"description": "Time"
},
"unit": {
"type": "number",
"description": "Unit hour = 0, day = 1"
}
},
"required": [
"proportion",
"time",
"unit"
]
}
},
"required": [
"subjectA",
"subjectB",
"fromName",
"fromAddress",
"htmlContent",
"footerLang",
"testingOn"
]
}
},
"required": [
"form",
"config",
"content"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"sn": "Campaign ID",
"preSignedUrl": "File upload URL"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "Campaign ID"
},
"preSignedUrl": {
"type": "string",
"description": "File upload URL"
}
},
"required": [
"sn",
"preSignedUrl"
]
}Headers
Content-Type: application/jsonBody
{
"code": "40001",
"invalidFields": "Field-related error message"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {}
}Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"form": {
"name": "Campaign Name"
},
"config": {
"schedule": {
"type": 0,
"timezone": 21,
"scheduleDate": "2019-07-05T06:00:28.000Z"
},
"ga": {
"enable": true,
"ecommerceEnable": false,
"utmCampaign": "spring_sale",
"utmContent": "logolink"
}
},
"content": {
"preheader": "Subject preview text",
"subject": "Email Subject",
"fromNameA": "Sender Name A",
"fromNameB": "Sender Name B",
"fromAddressA": "nameA@example.com",
"fromAddressB": "nameB@example.com",
"htmlContent": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content</p></body></html>",
"footerLang": 1,
"testingOn": 2,
"testing": {
"proportion": 10,
"time": 1,
"unit": 0
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"form": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
}
},
"required": [
"name"
]
},
"config": {
"type": "object",
"properties": {
"schedule": {
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "Sending type"
},
"timezone": {
"type": "number",
"description": "Timezone code"
},
"scheduleDate": {
"type": "string",
"description": "Scheduled sending time UTC+0"
}
},
"required": [
"type",
"timezone",
"scheduleDate"
]
},
"ga": {
"type": "object",
"properties": {
"enable": {
"type": "boolean",
"description": "Enable GA analytics true / false. If true, utmCampaign and utmContent must be provided."
},
"ecommerceEnable": {
"type": "boolean",
"description": "Enable GA e-commerce analytics"
},
"utmCampaign": {
"type": "string",
"description": "utmCampaign content"
},
"utmContent": {
"type": "string",
"description": "utmContent content"
}
},
"required": [
"enable",
"ecommerceEnable"
]
}
},
"required": [
"schedule",
"ga"
]
},
"content": {
"type": "object",
"properties": {
"preheader": {
"type": "string",
"description": "Subject preview text"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"fromNameA": {
"type": "string",
"description": "Sender Name A - when testingOn = 2 [required]"
},
"fromNameB": {
"type": "string",
"description": "Sender Name B - when testingOn = 2 [required]"
},
"fromAddressA": {
"type": "string",
"description": "Sender Address A - when testingOn = 2 [required]"
},
"fromAddressB": {
"type": "string",
"description": "Sender Address B - when testingOn = 2 [required]"
},
"htmlContent": {
"type": "string",
"description": "Email content"
},
"footerLang": {
"type": "number",
"description": "Footer language 0 = English, 1 = Chinese"
},
"testingOn": {
"type": "number",
"description": "Test type"
},
"testing": {
"type": "object",
"properties": {
"proportion": {
"type": "number",
"description": "Test member ratio - range: 0 ~ 100"
},
"time": {
"type": "number",
"description": "Time"
},
"unit": {
"type": "number",
"description": "Unit hour = 0, day = 1"
}
},
"required": [
"proportion",
"time",
"unit"
]
}
},
"required": [
"subject",
"fromNameA",
"fromNameB",
"fromAddressA",
"fromAddressB",
"htmlContent",
"footerLang",
"testingOn"
]
}
},
"required": [
"form",
"config",
"content"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"sn": "Campaign ID",
"preSignedUrl": "File upload URL"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "Campaign ID"
},
"preSignedUrl": {
"type": "string",
"description": "File upload URL"
}
},
"required": [
"sn",
"preSignedUrl"
]
}Headers
Content-Type: application/jsonBody
{
"code": "40001",
"invalidFields": "Field-related error message"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {}
}Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"form": {
"name": "Campaign Name"
},
"config": {
"schedule": {
"type": 0,
"timezone": 21,
"scheduleDate": "2019-07-05T06:00:28.000Z"
},
"ga": {
"enable": true,
"ecommerceEnable": false,
"utmCampaign": "spring_sale",
"utmContent": "logolink"
},
"content": {
"preheader": "Subject preview text",
"subject": "Email Subject",
"fromName": "Sender Name",
"fromAddress": "name@example.com",
"htmlContentA": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content A</p></body></html>",
"htmlContentB": "<!DOCTYPE html><html><head></head><body><p>Hello ${NAME},</p><p>Email content B</p></body></html>",
"footerLang": 1,
"testingOn": 3,
"testing": {
"proportion": 10,
"time": 1,
"unit": 0
}
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"form": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Campaign name"
}
},
"required": [
"name"
]
},
"config": {
"type": "object",
"properties": {
"schedule": {
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "Sending type"
},
"timezone": {
"type": "number",
"description": "Timezone code"
},
"scheduleDate": {
"type": "string",
"description": "Scheduled sending time UTC+0"
}
},
"required": [
"type",
"timezone",
"scheduleDate"
]
},
"ga": {
"type": "object",
"properties": {
"enable": {
"type": "boolean",
"description": "Enable GA analytics true / false. If true, utmCampaign and utmContent must be provided."
},
"ecommerceEnable": {
"type": "boolean",
"description": "Enable GA e-commerce analytics"
},
"utmCampaign": {
"type": "string",
"description": "utmCampaign content"
},
"utmContent": {
"type": "string",
"description": "utmContent content"
}
},
"required": [
"enable",
"ecommerceEnable"
]
},
"content": {
"type": "object",
"properties": {
"preheader": {
"type": "string",
"description": "Subject preview text"
},
"subject": {
"type": "string",
"description": "Email subject"
},
"fromName": {
"type": "string",
"description": "Sender name"
},
"fromAddress": {
"type": "string",
"description": "Sender address"
},
"htmlContentA": {
"type": "string",
"description": "Email content A"
},
"htmlContentB": {
"type": "string",
"description": "Email content B"
},
"footerLang": {
"type": "number",
"description": "Footer language 0 = English, 1 = Chinese"
},
"testingOn": {
"type": "number",
"description": "Test type"
},
"testing": {
"type": "object",
"properties": {
"proportion": {
"type": "number",
"description": "Test member ratio - range: 0 ~ 100"
},
"time": {
"type": "number",
"description": "Time"
},
"unit": {
"type": "number",
"description": "Unit hour = 0, day = 1"
}
},
"required": [
"proportion",
"time",
"unit"
]
}
},
"required": [
"subject",
"fromName",
"fromAddress",
"htmlContentA",
"htmlContentB",
"footerLang",
"testingOn"
]
}
},
"required": [
"schedule",
"ga",
"content"
]
}
},
"required": [
"form",
"config"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"sn": "Campaign ID",
"preSignedUrl": "File upload URL"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "Campaign ID"
},
"preSignedUrl": {
"type": "string",
"description": "File upload URL"
}
},
"required": [
"sn",
"preSignedUrl"
]
}Headers
Content-Type: application/jsonBody
{
"code": "40001",
"invalidFields": "Field-related error message"
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"examples": [
"40001"
]
},
"invalidFields": {
"type": "string",
"description": "Message",
"examples": [
"Field-related error message"
]
}
}
}One-time Upload and Create A/B Testing CampaignPOST/v1/campaign/testing/once
Description
For members who do not want to store their contact lists on the Newsleopard platform, Newsleopard also provides a one-time upload and create A/B testing campaign function. For details, please refer to One-time Upload and Create Campaign and Create A/B Testing Campaign.
Flow
-
Step 1: Create a campaign (please refer to Create A/B Testing Campaign, no need to provide form.selectedLists and form.excludeLists)
-
Step 2: According to the preSignedUrl in the Response, upload the contact file for this time (the upload method is the same as Import Contacts (File Upload))
Request Fields
| Field | Type | Description |
|---|---|---|
form.name * |
string |
Campaign name, customizable, not displayed in the email |
content.preheaderA |
string |
Version A subject preview text, must not exceed 60 characters |
content.preheaderB |
string |
Version B subject preview text, must not exceed 60 characters |
content.subjectA * |
string |
Version A email subject, must not exceed 150 characters |
content.subjectB * |
string |
Version B email subject, must not exceed 150 characters |
content.fromNameA * |
string |
Version A sender name, must not exceed 50 characters |
content.fromNameB * |
string |
Version B sender name, must not exceed 50 characters |
content.fromAddressA * |
string |
Version A sender address, the sender’s email address must be verified through the Newsleopard admin panel |
content.fromAddressB * |
string |
Version B sender address, the sender’s email address must be verified through the Newsleopard admin panel |
content.htmlContentA * |
string |
Version A email content |
content.htmlContentB * |
string |
Version B email content |
content.footerLang * |
number |
Footer message language, 0: English; 1: Chinese |
content.testingOn * |
number |
A/B testing type, 1: Subject A/B testing; 2: Sender name and address A/B testing; 3: Content A/B testing |
content.testing.proportion * |
number |
A/B testing ratio, 0-100, in %. The system will automatically grab contacts from the uploaded file for A and B grouping based on the set ratio. |
content.testing.time * |
number |
A/B testing duration. When the time is up, the performance of the A/B versions will be automatically judged, and the better version will be sent to the remaining un-grouped contacts. |
content.testing.unit * |
number |
A/B testing time unit, 0: hour; 1: day |
config.schedule.type * |
number |
Sending type, 0: Send immediately; 1: Schedule sending |
config.schedule.timezone |
number |
Refer to the attached Timezone Code Table |
config.schedule.scheduleDate |
string |
Scheduled sending time, format example:2019-04-01T08:38:32.00ZPlease ensure the date and time are in UTC+0 and are not in the past. |
config.ga.enable * |
boolean |
Whether to enable GA traffic tracking. If true, utmCampaign and utmContent must be provided. |
config.ga.ecommerceEnable * |
boolean |
Whether to enable GA e-commerce analytics. If true, GA tracking must also be true, and utmCampaign and utmContent must be provided. |
config.ga.utmCampaign |
string |
utm_campaign content |
config.ga.utmContent |
string |
utm_content content |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
sn |
string |
Campaign ID |
preSignedUrl |
string |
URL for uploading the contact file for this time |
Error Message Description
| Error Code | Description |
|---|---|
40001 |
Field error |
40003 |
Invalid EMAIL |
40004 |
Disallowed DOMAIN |
40007 |
Invalid SN |
40008 |
Unsupported file format |
40009 |
File content is empty |
40010 |
File size exceeds limit |
40011 |
Unverified sender address |
40014 |
Invalid campaign content |
40015 |
Invalid sending information |
40019 |
Incorrect schedule time |
40020 |
Invalid date format |
Notes
-
The system will not check the format or for duplicate emails in the one-time uploaded contact file. Please be aware.
-
The one-time uploaded contact file will not be imported into the system.
Delete Campaign API ¶
DELETE https://api.newsleopard.com/v1/campaign/normal
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"campaignSnList": [
"40280a3c6a0cb8c5016a10142a230001",
"40280a3c6a0cb8c5016a10142a230001"
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"campaignSnList": {
"type": "array",
"description": "Campaigns to delete"
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"success": [
"40280a3c6a0cb8c5016a10142a230001"
],
"sendingCampaign": [
"40280a3c6a0cb8c5016a10142a230003"
],
"badCampaigns": [
"40290a3c1a0cb8c5fdaa10142a230001"
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"success": {
"type": "array"
},
"sendingCampaign": {
"type": "array"
},
"badCampaigns": {
"type": "array"
}
}
}Delete Campaign APIDELETE/v1/campaign/normal
Description
This service allows you to delete sent, scheduled, or paused campaigns directly using the campaign ID.
Request Fields
| Field | Type | Description |
|---|---|---|
campaignSnList * |
array |
Campaign IDs to delete |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
success |
array |
Successfully deleted campaign IDs |
sendingCampaign |
array |
Campaign IDs that could not be deleted because they are being prepared for sending or are currently sending |
badCampaigns |
array |
Invalid campaign IDs |
Pause Campaign API ¶
PATCH https://api.newsleopard.com/v1/campaign/normal/40280a3c6a0cb8c5016a10142a230001
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyResponses
Headers
Content-Type: application/jsonHeaders
Content-Type: application/jsonBody
{
"code": "40001"
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"examples": [
"40001"
]
}
}
}Pause Campaign APIPATCH/v1/campaign/normal/{campaign_sn}
Description
You can use this service to pause a scheduled campaign.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
campaign_sn * |
string |
Campaign ID |
* Required field
URI Parameters
- campaign_sn
string(required) Example: 40280a3c6a0cb8c5016a10142a230001Campaign ID
Report ¶
Query Campaign IDs ¶
GET https://api.newsleopard.com/v1/report/campaigns?startDate=&endDate=
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: `Your API Key`Responses
Headers
Content-Type: application/jsonBody
{
"sn": "402810c26cb86ad7016cb8b2414a0003",
"name": "Campaign Name",
"sentBeginDate": "2019-04-01T08:38:32.569Z",
"sentEndDate": "2019-08-27T08:08:54.09Z"
}Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"sn": {
"type": "string",
"description": "Campaign ID",
"examples": [
"Campaign ID"
]
},
"name": {
"type": "string",
"description": "Campaign name",
"examples": [
"Campaign Name"
]
},
"sentBeginDate": {
"type": "string",
"description": "Campaign sending time",
"format": "date-time",
"examples": [
"2019-04-01T08:38:32.569Z"
]
},
"sentEndDate": {
"type": "string",
"description": "Campaign sending completion time",
"format": "date-time"
}
}
}
}Query Campaign IDsGET/v1/report/campaigns{?startDate,endDate}
Description
This service allows you to query the IDs of completed campaigns using a time range, for subsequent report generation.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
startDate |
string |
Start date, format example: 2019-04-01T08:38:32.00Z, please ensure the date and time are in UTC+0 |
endDate |
string |
End date, format example: 2019-04-05T05:30:30.00Z, please ensure the date and time are in UTC+0 |
Response Fields
| Field | Type | Description |
|---|---|---|
sn |
string |
Campaign ID |
name |
string |
Campaign name |
sentBeginDate |
string |
Campaign sending start date |
sentEndDate |
string |
Campaign sending completion date |
Notes
-
If no date parameters are provided in the URI, the last 10 completed campaigns will be returned by default.
-
If both startDate and endDate parameters are provided in the URI, all completed campaigns within this range will be returned.
-
If only startDate or endDate is provided, it will be considered an invalid time range, and the last 10 completed campaigns will be returned by default.
URI Parameters
- startDate
string(optional)Start date
Format:2019-04-01T08:38:32.00Z
Note: Please ensure the date and time are inUTC+0- endDate
string(optional)End date
Format:2019-04-05T05:30:30.00Z
Note: Please ensure the date and time are inUTC+0
Generate Report ¶
POST https://api.newsleopard.com/v1/report/40280a3c6a0cb8c5016a10142a230001/export
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"webhookUrl": "https://yours.webhook.com.tw"
}Schema
{
"type": "object",
"properties": {
"webhookUrl": {
"type": "string",
"description": "Webhook URL",
"examples": [
"https://yours.webhook.com.tw"
]
}
}
}Responses
Headers
Content-Type: application/jsonHeaders
Content-Type: application/jsonBody
{
"code": "40303",
"message": "bad operation with invalid user state"
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"examples": [
"40303"
]
},
"message": {
"type": "string",
"description": "Message",
"examples": [
"bad operation with invalid user state"
]
}
}
}Generate ReportPOST/v1/report/{campaign_sn}/export
Description
This service allows you to generate reports for a campaign using the campaign ID obtained from Query Campaign IDs, including: delivered, opened, clicked, bounced, complained, and unsubscribed.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
campaign_sn * |
string |
Campaign ID |
* Required field
Request Fields
| Field | Type | Description |
|---|---|---|
webhookUrl |
string |
After the report is generated, the system will send a POST request to the webhookUrl. The format of the response is the same as the return value of Query Report Link. |
Notes
-
Since generating a report takes time, this service returns the report download link asynchronously.
-
If no webhookUrl is provided, you can also use Query Report Link to get the download link.
-
The call frequency is 1 request/10 seconds.
-
The generation time for the same campaign report must be at least 1 hour apart. Extra calls within 1 hour will be ignored.
URI Parameters
- campaign_sn
string(required) Example: 40280a3c6a0cb8c5016a10142a230001Campaign ID
Query Report Link ¶
GET https://api.newsleopard.com/v1/report/40280a3c6a0cb8c5016a10142a230001/link
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyResponses
Headers
Content-Type: application/jsonBody
{
"Reports": [
{
"reportType": "delivery",
"link": "https://sample.domain/filename-delivery.csv",
"createdDate": "2019-04-01T08:38:32.569Z"
}
]
}Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"reportType": {
"type": "string",
"description": "Report type",
"enum": [
"delivery",
"open",
"click",
"bounce",
"unsubscribe",
"complain"
],
"examples": [
"delivery"
]
},
"link": {
"type": "string",
"description": "File link",
"examples": [
"https://sample.domain/filename-reportType.csv"
]
},
"createdDate": {
"type": "string",
"description": "Report creation date",
"format": "date-time"
}
}
},
"examples": [
[
{
"reportType": "delivery",
"link": ":https://sample.domain/filename-delivery.csv",
"createdDate": "2019-04-01T08:38:32.569Z"
},
{
"reportType": "open",
"link": ":https://sample.domain/filename-open.csv",
"createdDate": "2019-04-01T08:38:32.569Z"
},
{
"reportType": "click",
"link": ":https://sample.domain/filename-click.csv",
"createdDate": "2019-04-01T08:38:32.569Z"
},
{
"reportType": "bounce",
"link": ":https://sample.domain/filename-bounce.csv",
"createdDate": "2019-04-01T08:38:32.569Z"
},
{
"reportType": "unsubscribe",
"link": ":https://sample.domain/filename-unsubscribe.csv",
"createdDate": "2019-04-01T08:38:32.569Z"
},
{
"reportType": "complain",
"link": ":https://sample.domain/filename-complain.csv",
"createdDate": "2019-04-01T08:38:32.569Z"
}
]
]
}40303 Invalid campaign_sn passed
Headers
Content-Type: application/jsonBody
{
"code": "40303",
"message": "bad operation with invalid user state"
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"examples": [
"40303"
]
},
"message": {
"type": "string",
"description": "Message",
"examples": [
"bad operation with invalid user state"
]
}
}
}Query Report LinkGET/v1/report/{campaign_sn}/link
Description
After generating a campaign report via Generate Report, this service provides a download link for the report file using the campaign ID.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
campaign_sn * |
string |
Campaign ID |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
reportType |
string |
Report type, including: |
| - delivery | ||
| - open | ||
| - click | ||
| - bounce | ||
| - unsubscribe | ||
| - complain | ||
link |
string |
Report download URL |
createdDate |
string |
Report generation time |
Notes
-
If you want to update the downloaded data, please use Generate Report to regenerate the report first.
-
When regenerating the report, the system will first check for new data. A new report will only be generated if there is new data; otherwise, the original report will be used.
URI Parameters
- campaign_sn
string(required) Example: 40280a3c6a0cb8c5016a10142a230001Campaign ID
Template ¶
Query All Templates ¶
GET https://api.newsleopard.com/v1/templates
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: `Your API Key`Responses
Headers
Content-Type: application/jsonBody
{
"capacity": 3,
"templates": [
{
"id": "template_id",
"name": "template_name",
"template": "<html><body><div>Template Content</div></body></html>",
"updateDate": "2022-07-22T08:08:50Z"
}
]
}Schema
{
"type": "object",
"capacity": {
"type": "number",
"description": "The maximum number of templates allowed for the account.",
"examples": [
3
]
},
"templates": {
"type": "array",
"description": "Template",
"properties": {
"id": {
"type": "string",
"description": "Template",
"examples": [
"Template"
]
},
"name": {
"type": "string",
"description": "Template name",
"examples": [
"Template name"
]
},
"template": {
"type": "string",
"description": "Template HTML content",
"examples": [
"<html><body><div>Template Content</div></body></html>"
]
},
"updateDate": {
"type": "string",
"description": "Campaign sending completion time",
"format": "date-time",
"examples": [
"2022-01-01T00:00:00.000Z"
]
}
}
}
}Query All TemplatesGET/v1/templates
Description
This service allows you to retrieve all template data created under your account at once.
Response Fields
| Field | Type | Description |
|---|---|---|
capacity |
number |
The maximum number of templates allowed for the account. |
id |
string |
Template ID. |
name |
string |
Template name. |
template |
string |
Template HTML content. |
updateDate |
string |
Template update time. |
Query Specific Template Content ¶
GET https://api.newsleopard.com/v1/templates/id
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: `Your API Key`Responses
Headers
Content-Type: application/jsonBody
{
"id": "template_id",
"name": "template_name",
"template": "<html><body><div>Template Content</div></body></html>",
"updateDate": "2022-07-22T08:08:50Z"
}Schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Template",
"examples": [
"Template"
]
},
"name": {
"type": "string",
"description": "Template name",
"examples": [
"Template name"
]
},
"template": {
"type": "string",
"description": "Template HTML content",
"examples": [
"<html><body><div>Template Content</div></body></html>"
]
},
"updateDate": {
"type": "string",
"description": "Campaign sending completion time",
"format": "date-time",
"examples": [
"2022-01-01T00:00:00.000Z"
]
}
}
}Headers
Content-Type: application/jsonBody
{
"code": "40007"
}Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"examples": [
"40007"
]
}
}
}Query Specific Template ContentGET/v1/templates/{template_id}
Description
This service allows you to retrieve the data of a specific template using the template ID.
URI Parameters
| Parameters | Type | Description |
|---|---|---|
template_id * |
string |
Template ID |
* Required field
Response Fields
| Field | Type | Description |
|---|---|---|
id |
string |
Template ID |
name |
string |
Template name |
template |
string |
Template HTML content |
updateDate |
string |
Template update time |
Error Message Description
| Error Code | Description |
|---|---|
40007 |
Invalid template ID |
URI Parameters
- template_id
string(required) Example: idTemplate ID
Automation Script ¶
Trigger or Stop Automation Script ¶
POST https://api.newsleopard.com/v1/automation/event
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"workflow": "welcome-automation",
"event": "TRIGGER",
"recipients": [
{
"name": "Alice",
"address": "alice@gmail.com",
"variables": {
"signupDate": "2019-04-01"
}
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"workflow": {
"type": "string"
},
"event": {
"type": "string"
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Recipient name"
},
"address": {
"type": "string",
"description": "Recipient email"
},
"variables": {
"type": "object",
"properties": {
"signupDate": {
"type": "string"
}
}
}
},
"required": [
"address"
]
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"success": [
"alice@gmail.com"
],
"failure": []
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"success": {
"type": "array",
"items": {
"type": "string"
}
},
"failure": {}
}
}Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"workflow": "welcome-automation",
"event": "TERMINATE",
"recipients": [
{
"name": "bob",
"address": "bob@gmail.com",
"variables": {}
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"workflow": {
"type": "string"
},
"event": {
"type": "string"
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Recipient name"
},
"address": {
"type": "string",
"description": "Recipient email"
},
"variables": {
"type": "object",
"properties": {}
}
},
"required": [
"address"
]
}
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"success": [
"bob@gmail.com"
],
"failure": {}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"success": {
"type": "array"
},
"failure": {
"type": "object",
"properties": {}
}
}
}Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API KeyBody
{
"workflow": "welcome-automation",
"event": "TRIGGER",
"recipients": [
{
"name": "Alice",
"address": "alice@gmail.com",
"variables": {
"signupDate": "2019-04-01"
}
},
{
"name": "bob",
"address": "bob@gmail.com",
"variables": {
"gender": "man"
}
},
{
"name": "iamnotanemail",
"address": "iamnotanemail",
"variables": {}
},
{
"name": "variable_too_long",
"address": "variable_too_long@gmail.com",
"variables": {
"description": [
"i_am_the_variable_whose_length_is_over_100_characeters_Lorem",
"ipsum dolor sit amet consectetur adipisicing elit. Quis quaerat quas",
"architecto magni id minima labore illum eligendi impedit numquam debitis. Recusandae eos placeat dolorum. Aliquam obcaecati delectus adipisci molestias?"
]
}
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"workflow": {
"type": "string"
},
"event": {
"type": "string"
},
"recipients": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Recipient name"
},
"address": {
"type": "string",
"description": "Recipient email"
},
"variables": {
"type": "object",
"properties": {
"signupDate": {
"type": "string"
}
}
}
},
"required": [
"address"
]
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Recipient name"
},
"address": {
"type": "string",
"description": "Recipient email"
},
"variables": {
"type": "object",
"properties": {
"gender": {
"type": "string"
}
}
}
},
"required": [
"address"
]
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Recipient name"
},
"address": {
"type": "string",
"description": "Recipient email"
},
"variables": {
"type": "object",
"properties": {}
}
},
"required": [
"address"
]
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Recipient name"
},
"address": {
"type": "string",
"description": "Recipient email"
},
"variables": {
"type": "object",
"properties": {
"description": {
"type": "array"
}
}
}
},
"required": [
"address"
]
}
]
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"success": [
"alice@gmail.com",
"bob@gmail.com"
],
"failure": {
"iamnotanemail": "Invalid: address is not a valid email format",
"variable_too_long@gmail.com": "Invalid: the value of recipient variables should under 100 characters"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"success": {
"type": "array",
"items": [
{
"type": "string"
},
{
"type": "string"
}
]
},
"failure": {
"type": "object",
"properties": {
"iamnotanemail": {
"type": "string"
},
"variable_too_long@gmail.com": {
"type": "string"
}
}
}
}
}Headers
Content-Type: application/jsonBody
{
"message": "Invalid request body",
"errors": "[ array is too long: must have at most 100 elements ]"
}Trigger or Stop Automation ScriptPOST/v1/automation/event
Description
This service allows you to pass in single or multiple contacts to trigger a script created in the Newsleopard admin panel for marketing automation, or to interrupt the process for contacts already in the automation flow and end the script for them early.
Request Fields * Required field
| Field | Type | Description |
|---|---|---|
workflow * |
string |
Automation script ID, automatically generated when creating an automation script in the admin panel, or defined by yourself during creation (note: cannot be changed after creation) |
event * |
string |
Event type, can use TRIGGER to trigger the script or TERMINATE to end the script early for specific contacts already in the automation flow |
recipients * |
array |
Recipients, up to 100 recipients/request |
recipients.name * |
string |
Recipient name |
recipients.address * |
string |
Recipient Email |
recipients.variables |
object |
Recipient variables, custom, each variable content length up to 100, cannot use mathematical expressions and cannot start with a number. |
Response Fields
| Field | Type | Description |
|---|---|---|
success.address |
string |
Recipient Email |
failure |
object |
Recipient error, types are as follows: ・Invalid email format: Invalid: address is not a valid email format ・Recipient variable content too long: Invalid: the value of recipient variables should under 100 characters |
Account Information ¶
Query Current Balance ¶
GET https://api.newsleopard.com/v1/balance
Requests
Headers
Content-Type: application/json
Accept: application/json
x-api-key: `Your API Key`Responses
Headers
Content-Type: application/jsonBody
{
"email": "10",
"sms": "20"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"email": {
"type": "string"
},
"sms": {
"type": "string"
}
}
}Query Current BalanceGET/v1/balance
Description
Before sending emails or SMS, you can use this API to query the current balance to avoid sending failures due to insufficient balance.
Response Fields
| Field | Type | Description |
|---|---|---|
email |
number |
The number of remaining emails in the account. |
sms |
number |
The number of remaining SMS messages in the account. |
Attachments ¶
Timezone Code Table
| Code | Region Name |
|---|---|
| 0 | KIRITIMATI |
| 1 | CHATHAM |
| 2 | AUCKLAND |
| 3 | ENDERBURY |
| 4 | TONGATAPU |
| 5 | KAMCHATKA |
| 6 | FIJI |
| 7 | LORD_HOWE |
| 8 | SYDNEY |
| 9 | GUADALCANAL |
| 10 | NORFOLK |
| 11 | ADELAIDE |
| 12 | BRISBANE |
| 13 | DARWIN |
| 14 | SEOUL |
| 15 | TOKYO |
| 16 | HONG_KONG |
| 17 | KUALA_LUMPUR |
| 18 | MANILA |
| 19 | SHANGHAI |
| 20 | SINGAPORE |
| 21 | TAIPEI |
| 22 | PERTH |
| 23 | BANGKOK |
| 24 | HO_CHI_MINH |
| 25 | JAKARTA |
| 26 | RANGOON |
| 27 | DHAKA |
| 28 | KATHMANDU |
| 29 | COLOMBO |
| 30 | KOLKATA |
| 31 | KARACHI |
| 32 | TASHKENT |
| 33 | YEKATERINBURG |
| 34 | KABUL |
| 35 | TEHRAN |
| 36 | DUBAI |
| 37 | TBILISI |
| 38 | NAIROBI |
| 39 | BAGHDAD |
| 40 | JERUSALEM |
| 41 | KUWAIT |
| 42 | RIYADH |
| 43 | ATHENS |
| 44 | BUCHAREST |
| 45 | HELSINKI |
| 46 | ISTANBUL |
| 47 | MINSK |
| 48 | MOSCOW |
| 49 | CAIRO |
| 50 | JOHANNESBURG |
| 51 | AMSTERDAM |
| 52 | BERLIN |
| 53 | BRUSSELS |
| 54 | PARIS |
| 55 | PRAGUE |
| 56 | ROME |
| 57 | ALGIERS |
| 58 | DUBLIN |
| 59 | LISBON |
| 60 | LONDON |
| 61 | GMT |
| 62 | CAPE_VERDE |
| 63 | SOUTH_GEORGIA |
| 64 | ST_JOHNS |
| 65 | BUENOS_AIRES |
| 66 | HALIFAX |
| 67 | SANTIAGO |
| 68 | SAO_PAULO |
| 69 | BERMUDA |
| 70 | CARACAS |
| 71 | INDIANAPOLIS |
| 72 | NEW_YORK |
| 73 | PUERTO_RICO |
| 74 | BOGOTA |
| 75 | CHICAGO |
| 76 | LIMA |
| 77 | PANAMA |
| 78 | DENVER |
| 79 | EL_SALVADOR |
| 80 | MEXICO_CITY |
| 81 | LOS_ANGELES |
| 82 | PHOENIX |
| 83 | TIJUANA |
| 84 | ANCHORAGE |
| 85 | HONOLULU |
| 86 | NIUE |
| 87 | PAGO_PAGO |