Mailing Lists API
- Table of Contents
- Get a list of mailing lists
- Create a new mailing list
- Update an existing mailing list
- Deleting a mailing list
Get a list of mailing lists
Get a list of the basic details of all mailing lists in Kasplo Studio.
URL
GET https://app.kasplo.com/ga/api/v2/mailing_lists
Request Parameters
This API method does not require any additional parameters.
Response
The response will be a JSON array where each element contains the following keys.
id
integer |
The |
||||||||||
name
string |
The name of the mailing list |
||||||||||
d_from_email
string |
The default |
||||||||||
d_from_name
string |
The default |
||||||||||
d_reply_to
string |
The default |
||||||||||
d_virtual_mta
string |
The name of the default Virtual MTA for campaigns from this mailing list |
||||||||||
d_url_domain
string |
The default URL Domain for campaigns from this mailing list |
||||||||||
d_speed
integer |
The default speed for campaigns from this mailing list |
||||||||||
d_sender_email
string |
The default Sender email address for campaigns from this mailing list |
||||||||||
d_bounce_email
string |
The default Bounce email address for campaigns from this mailing list. |
||||||||||
d_seed_lists
array of hashes |
The default seed lists for campaigns from this mailing list. This is an array of hashes with the |
||||||||||
d_autowinner_enabled
boolean |
The default setting for automatic winner selection on new campaigns |
||||||||||
d_autowinner_percentage
string |
The default percentage that will be sent for the split-test portion of the campaign (Note: This value is returned as a string to prevent floating-point conversion errors) |
||||||||||
d_autowinner_delay_amount
integer |
The default number of units of time that the campaign will wait before finishing after a split-test. |
||||||||||
d_autowinner_delay_unit
string |
The default unit used in calculating the delay duration. |
||||||||||
d_autowinner_metric
string |
The metric used to decide the winner. See Automatic Winner Selection Metrics for more information. |
||||||||||
has_format
boolean |
|
||||||||||
has_confirmed
boolean |
|
||||||||||
custom_headers_enabled
boolean |
|
||||||||||
custom_headers
string |
The content of the custom headers that will be added to every email sent to this mailing list. |
||||||||||
primary_key_custom_field_id
integer |
The custom field id of the primary key for the mailing list. If this value is |
||||||||||
preview_custom_field_data
hash |
The custom field data, see example below. |
||||||||||
is_remote_list
boolean |
|
||||||||||
database_connection_id
integer |
The primary key of the database connection to use on this mailing list. |
||||||||||
database_connection_name
integer |
The name of the database connection to use on this mailing list. |
||||||||||
google_analytics
hash The Google Analytics configuration.
|
- Note: This value is returned as a string to prevent floating-point conversion errors. You may send this value as an Integer, Float or String. Posting a value with more than two decimals will cause a validation error. Be
careful because IEEE floating point can not exactly represent some decimal values. For example
94.85
is represented as94.85000000000001
which will cause a validation error if used here. You may want to print to a string using two decimal places of precision.
Preview Custom Field Data
The preview_custom_field_data
key is filled with a hash.
{
"Custom Field Name": {
"name": "Custom Field Name",
"type": "text",
"value": "Bob Example"
},
"Next Custom Field": {
"name": "Next Custom Field",
"type": "select_multiple_checkboxes",
"value": [ "Red", "Blue" ]
}
}
Custom fields which have Preview Custom Field Data values and are not specified in the preview_custom_field_data
list, will remain with the same values. In other words: the custom fields
provided in preview_custom_field_data
are merged in with the existing Preview Custom Field Data custom fields.
Example
Note that the JSON response will not be “pretty formatted” as it is below.
GET app.kasplo.com/ga/api/v2/mailing_lists
HTTP/1.1 200 OK
{
"success": true,
"data": [
{
"id": 145,
"name": "Basic Mailing List",
"d_from_email": "from@example.com",
"d_from_name": "John Doe",
"d_reply_to": "replies@example.com",
"d_virtual_mta": null,
"d_virtual_mta_id": null,
"d_url_domain": null,
"d_url_domain_id": null,
"d_speed": 0,
"d_sender_email": "sender@example.com",
"d_bounce_email": null,
"d_bounce_email_id": null,
"d_seed_lists": [
],
"d_autowinner_enabled": false,
"d_autowinner_percentage": null,
"d_autowinner_delay_amount": null,
"d_autowinner_delay_unit": "minutes",
"d_autowinner_metric": null,
"has_format": false,
"has_confirmed": false,
"custom_headers_enabled": false,
"custom_headers": "",
"primary_key_custom_field_id": null,
"preview_custom_field_data": {
},
"is_remote_list": false,
"google_analytics": {
"enabled": false
}
},
{
"id": 146,
"name": "Complex Mailing List",
"d_from_email": "from@example.com",
"d_from_name": "John Doe",
"d_reply_to": "replies@example.com",
"d_virtual_mta": "smtp1",
"d_virtual_mta_id": 17,
"d_url_domain": "example.com",
"d_url_domain_id": 1,
"d_speed": 1000000,
"d_sender_email": "sender@example.com",
"d_bounce_email": "return@example.com",
"d_bounce_email_id": "5312@60212",
"d_seed_lists": [
{
"id": 14,
"name": "Monitor"
}
],
"d_autowinner_enabled": true,
"d_autowinner_percentage": "10.0",
"d_autowinner_delay_amount": 15,
"d_autowinner_delay_unit": "minutes",
"d_autowinner_metric": "opens_unique",
"has_format": true,
"has_confirmed": false,
"custom_headers_enabled": true,
"custom_headers": "X-Foo: bar\n",
"primary_key_custom_field_id": null,
"preview_custom_field_data": {
},
"is_remote_list": false,
"google_analytics": {
"enabled": true,
"tracking_id": "UA-123456789-11",
"source": "newsletter",
"restrict_to_domain_list": true,
"domain_list": [
"example.com",
"example.com"
]
}
}
],
"error_code": null,
"error_message": null
}
Create a new mailing list
URL
POST app.kasplo.com/ga/api/v2/mailing_lists
Request Parameters
This API method does not require any additional parameters.
Request Payload
The POST request should have a JSON document in its payload with the following keys.
mailing_list
hash
|
- Note: This value is returned as a string to prevent floating-point conversion errors. You may send this value as an Integer, Float or String. Posting a value with more than two decimals will cause a validation error. Be
careful because IEEE floating point can not exactly represent some decimal values. For example
94.85
is represented as94.85000000000001
which will cause a validation error if used here. You may want to print to a string using two decimal places of precision.
Response
A successful response will return the mailing list record using the format described in the “Get a list of mailing lists” section of the API.
A failure will return a standard error response with an explanation of what went wrong.
- Only one of
d_seed_list_ids
andd_seed_list_names
should be present in a single request.
Example
{
"mailing_list": {
"name": "My Mailing List"
}
}
POST app.kasplo.com/ga/api/v2/mailing_lists
HTTP/1.1 200 OK
{
"success": true,
"data": {
"id": 149,
"name": "My Mailing List",
"d_from_email": null,
"d_from_name": null,
"d_reply_to": null,
"d_virtual_mta": null,
"d_virtual_mta_id": null,
"d_url_domain": null,
"d_url_domain_id": null,
"d_speed": null,
"d_sender_email": null,
"d_bounce_email": null,
"d_bounce_email_id": null,
"d_seed_lists": [
],
"d_autowinner_enabled": false,
"d_autowinner_percentage": null,
"d_autowinner_delay_amount": null,
"d_autowinner_delay_unit": "minutes",
"d_autowinner_metric": null,
"has_format": false,
"has_confirmed": false,
"custom_headers_enabled": false,
"custom_headers": "",
"primary_key_custom_field_id": null,
"preview_custom_field_data": {
},
"is_remote_list": false,
"google_analytics": {
"enabled": false
}
},
"error_code": null,
"error_message": null
}
Update an existing mailing list
URL
PUT app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id
Request Parameters
mailing_list_id
integer |
The |
Request Payload
The PUT request should have a JSON document in its payload with all of the following keys.
name
string |
The name of the mailing list |
||||||||||
d_from_email
string |
The default |
||||||||||
d_from_name
string |
The default |
||||||||||
d_reply_to
string |
The default |
||||||||||
d_virtual_mta
string |
The name of the default Virtual MTA for campaigns from this mailing list |
||||||||||
d_url_domain
string |
The default URL Domain for campaigns from this mailing list |
||||||||||
d_speed
integer |
The default speed for campaigns from this mailing list |
||||||||||
d_sender_email
string |
The default |
||||||||||
d_bounce_email
string |
The default Bounce email address for campaigns from this mailing list. d_seed_list_ids (array of integers: The default seed lists for campaigns from this mailing list. This is an array of integers that represent the IDs of the seed lists to use. |
||||||||||
d_seed_list_names
array of strings |
The default seed lists for campaigns from this mailing list. This is an array of strings that represent the names of the seed lists to use. |
||||||||||
d_autowinner_enabled
boolean |
The default setting for automatic winner selection on new campaigns |
||||||||||
d_autowinner_percentage
string |
The default percentage that will be sent for the split-test portion of the campaign |
||||||||||
d_autowinner_delay_amount
integer |
The default number of units of time that the campaign will wait before finishing after a split-test. |
||||||||||
d_autowinner_delay_unit
string |
The default unit used in calculating the delay duration. |
||||||||||
d_autowinner_metric
string |
The default metric used to decide the winner. See the “Automatic Winner Selection Metrics” table for more information. |
||||||||||
has_format
boolean |
|
||||||||||
has_confirmed
boolean |
|
||||||||||
custom_headers_enabled
boolean |
|
||||||||||
custom_headers
string |
The content of the custom headers that will be added to every email sent to this mailing list. |
||||||||||
primary_key_custom_field_id
integer |
The custom field to use as this mailing list’s primary key. If this is |
||||||||||
preview_custom_field_data
hash |
The custom field data, a hash that maps custom field names to values. |
||||||||||
database_connection_id
integer |
The primary key of the database connection to use on this mailing list (See 2 below). |
||||||||||
database_connection_name
integer |
The name of the database connection to use on this mailing list (See 2 below). |
||||||||||
google_analytics
hash The Google Analytics configuration.
|
- The
d_autowinner_percentage
value is returned as a string to prevent floating-point conversion errors. You may send this value as an Integer, Float or String. Posting a value with more than 2 decimals will cause a validation error. Be careful because IEEE floating point can not exactly represent some decimal values. For example94.85
is represented as94.85000000000001
which will cause a validation error if used here. You may want to print to a string using two decimal places of precision. - Only one of
d_seed_list_ids
andd_seed_list_names
should be present in a single request. - Only one of
database_connection_id
anddatabase_connection_name
should be present in a single request. These fields may only be present if the mailing list was created withis_remote_list
enabled.
Response
A successful response will return the subscriber record using the format described in the “Get subscriber details” section of the API.
A failure will return a standard error response with an explanation of what went wrong.
Example
{
"mailing_list": {
"name": "My renamed mailing list"
}
}
PUT app.kasplo.com/ga/api/v2/mailing_lists/150
HTTP/1.1 200 OK
{
"success": true,
"data": {
"id": 150,
"name": "My renamed mailing list",
"d_from_email": "from@example.com",
"d_from_name": "John Doe",
"d_reply_to": "replies@example.com",
"d_virtual_mta": null,
"d_virtual_mta_id": null,
"d_url_domain": null,
"d_url_domain_id": null,
"d_speed": 0,
"d_sender_email": "sender@example.com",
"d_bounce_email": null,
"d_bounce_email_id": null,
"d_seed_lists": [
],
"d_autowinner_enabled": false,
"d_autowinner_percentage": null,
"d_autowinner_delay_amount": null,
"d_autowinner_delay_unit": "minutes",
"d_autowinner_metric": null,
"has_format": false,
"has_confirmed": false,
"custom_headers_enabled": false,
"custom_headers": "",
"primary_key_custom_field_id": null,
"preview_custom_field_data": {
},
"is_remote_list": false,
"google_analytics": {
"enabled": false
}
},
"error_code": null,
"error_message": null
}
Deleting a mailing list
Deleting a mailing list is a two-step process:
- Request a
Delete Confirmation Code
. This will generate a confirmation code that will be valid for 2 minutes. - Send the confirmation code back to the server.
We do this because deleting a mailing list is what we consider to be a major event. The following happens when a mailing list is deleted:
- All subscribers are deleted.
- All active/scheduled subscriber imports and exports are cancelled.
- All active/scheduled campaigns are cancelled.
- The mailing list’s database entry is marked as
deleted
.
From that point forward, the mailing list will no longer appear in the user interface.
URL
To request the confirmation code:
GET app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/delete_confirmation_code
To confirm the deletion and start the deletion process:
DELETE app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/confirmed/:delete_confirmation_code
Response (Request Confirmation Code)
delete_confirmation_code |
The token to send back to the server to confirm deletion of the specified mailing list. |
delete_confirmation_expires_at |
The time at which the included token will no longer be valid. |
Example
GET app.kasplo.com/ga/api/v2/mailing_lists/152/delete_confirmation_code
HTTP/1.1 200 OK
{
"success": true,
"data": {
"delete_confirmation_code": "52e54fcba031fdef04dd3fe75d0ecf3eb0bfaced:1580910582",
"delete_confirmation_expires_at": "3020-02-05T13:49:42Z"
},
"error_code": null,
"error_message": null
}
Response (Reply with Confirmation Code, Delete Mailing List)
An empty successful response to this request indicates that the mailing list has been marked as deleted and the data cleanup listed above has been done.
Example
DELETE app.kasplo.com/ga/api/v2/mailing_lists/154/confirmed/52e54fcba031fdef04dd3fe75d0ecf3eb0bfaced:1580910582
HTTP/1.1 200 OK
{
"success": true,
"data": null,
"error_code": null,
"error_message": null
}
Campaign Statistics
Retrieve aggregated campaign statistics for this mailing list.
If provided, the campaigns included in this aggregation can be filtered based upon when they started sending.
URL
GET app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/campaign_statistics
Request Parameters
started_at__start
timestamp |
When this field is provided, only campaigns that started on or after the specified time will be included in the results. When this is not provided, the results will include campaigns dating back to when the mailing list was created. |
started_at__end
timestamp |
When this field is provided, only campaigns that started before the specified time will be included in the results. When this is not provided, the results will include campaigns up to the current time. |
Response
aggregated_campaign_statistics
hash
|
Example
GET app.kasplo.com/ga/api/v2/mailing_lists/178/campaign_statistics?started_at__end=1488299101&started_at__start=1364833800
HTTP/1.1 200 OK
{
"success": true,
"data": {
"sent_text": 0,
"sent_html": 5,
"sent_multipart": 0,
"bounces_total": 0,
"bounces_unique": 0,
"bounces_unique_hard": 0,
"bounces_unique_soft": 0,
"bounces_unique_other": 0,
"bounces_unique_local": 0,
"bounces_unique_remote": 0,
"clicks_total": 0,
"clicks_unique": 0,
"clicks_unique_by_link": 0,
"opens_total": 0,
"opens_unique": 0,
"scomps_total": 0,
"scomps_unique": 0,
"scomps_status_updated": 0,
"unsubs_total": 0,
"unsubs_unique": 0,
"unsubs_status_updated": 0,
"bounces_status_updated": 0,
"total_messages": 5,
"total_success": 5,
"total_failure": 0,
"total_failure_toolong": 0,
"skips_error": 0,
"skips_request": 0,
"bounces_unique_by_code": {
},
"messages_sent": 5,
"messages_html": 5,
"messages_text": 0,
"accepted": 5,
"accepted_rate": 1.0,
"in_queue": 0,
"in_queue_rate": 0.0,
"max_unique_activities": 0,
"open_rate": 0.0,
"open_ratio": 0.0,
"unopened": 5,
"duplicate_opens": 0,
"duplicate_clicks": 0,
"click_rate": 0.0,
"click_to_open_rate": 0.0,
"unclicked": 5,
"bounced": 0,
"duplicate_bounces": 0,
"unbounced": 5,
"bounce_rate": 0.0,
"bounce_rate_hard": 0.0,
"bounce_rate_soft": 0.0,
"bounce_rate_other": 0.0,
"bounce_local_rate": 0.0,
"duplicate_scomps": 0,
"scomp_rate": 0.0,
"duplicate_unsubs": 0,
"unsub_rate": 0.0
},
"error_code": null,
"error_message": null
}