Email Marketing API
1.General Standards:
A. {sid}: Replace with the secret ID for your account.
B.{api-key}: Replace with the API key value for your account.
C.The combination of sid and api-key acts as an authentication mechanism.
D.GET APIs
- pageSize: The number of items to be fetched in one single request.
- page: The page that needs to be fetched based on the pageSize.
- Example: There are a total of 10 items. pageSize=5 and page=1 will return items 1-5, while pageSize=5 and page=2 will return items 5-10. pageSize=5 and page=3 will not return any items.
name: Filter based on the name of the item.
2. GET List API
A. Purpose: Fetch the lists available for the account.
B. Sample CURL request
curl --location '{domain}/audience/v1/{sid}/list' \
--header 'api-key: {api-key}
C. Sample Response
{
"data": [
{
"name": "list-4",
"list_id": "229dc5317d78a2ab45ac641a5a4de156",
"status": 1,
"created_at": "2024-11-18T18:08:20Z",
"updated_at": "2024-11-18T18:08:20Z"
}
],
"error": {},
"limit": 10,
"message": "Request processed successfully.",
"status": 200,
"total": 1
}
Response Description:
- Name: Name of the list.
- List_id: The unique ID for the list (used for adding contacts to a specific list).
- Status: Status of the list. 1 means the list is active.
- Created_at: The creation timestamp (in UTC).
- Updated_at: The last updated timestamp (in UTC).
3. GET Custom-field API
A. Purpose: Fetch the lists available for the account.
B. Sample CURL request
curl --location '{domain}/audience/v1/{sid}/custom-field \
--header 'api-key: {api-key}
C. Sample Response
{
"data": [
{
"name": "age",
"custom_id": "351c3611ddc42c223483386015411b0e",
"type": "string",
"values": "", "status": 1,
"created_at": "2025-01-06T10:43:32Z",
"updated_at": "2025-01-06T10:43:32Z",
"required": 0,
"default": ""
},
],
"error": {},
"limit": 10,
"message": "Request processed successfully.",
"status": 200,
"total": 1
}
Response Description:
- Name: Name of the custom field.
- Custom_id: The unique ID for the custom field.
- Type: Type of the custom field (Possible values: string, boolean, numeric, date, dropdown).
- Values: Possible values for the custom field if the type is dropdown.
- Status: Status of the custom field. 1 means active.
- Created_at: Timestamp of creation (UTC).
- Updated_at: Timestamp of last update (UTC).
- Required: Specifies if the custom field is mandatory for a contact or not. (1 – Required, 0 – Not required). This means that if the value is set to 1 a contact can’t be added without adding the specified custom field value.
4. GET Tag API
A. Purpose: Fetch the lists available for the account.
B. Sample CURL request
- By default, the active tags will be fetched. (Also, you can pass status=1 to fetch active tags). Pass status=2 to fetch the inactive tags.
curl --location '{domain}/audience/v1/{sid}/tag \
--header 'api-key: {api-key}
C. Sample Response
{
"data": [
{
"tag_id": "d4PjLor0zY",
"name": "new-contacts",
"status": 1,
"created_at": "2025-01-07T12:14:17Z",
"modified_at": "2025-01-07T12:14:17Z"
}
],
"limit": 10,
"message": "Success",
"status": true,
"statuscode": 200,
"total": 1
}
Response Description:
- Name: Name of the tag.
- Tag_ID: The unique ID for the tag.
- Status: Status of the tag. 1 means active.
- Created_at: Timestamp of creation (UTC).
- Modified_at: Timestamp of last modification (UTC).
5. POST Contact API
A. Purpose: Create contacts (batch of up to 100 contacts per request).
B. Sample CURL request
- By default, the active tags will be fetched. (Also, you can pass status=1 to fetch active tags). Pass status=2 to fetch the inactive tags.
curl --location '{domain}/audience/v1/{sid}/contact \
--header 'api-key: {api-key} \
--header 'content-type: application/json' \
--data-raw '{
"update_subscribers": true,
"data": [
{
"email": "test@kasplo.com",
"first_name": "John",
"last_name": "Doe",
"custom_fields": {
"city": "Bangalore",
"age": "25"
}
}
],
"list_id": "229dc5317d78a2ab45ac641a5a4de156",
"tags":["314dc5317d78a2ab45ac641aas4de156"]
}'
C. Request Description:
- Data: Array of objects, each representing a contact creation request.
- Email: The email of the contact (cannot be edited once added).
- First_name: First name of the contact.
- Last_name: Last name of the contact.
- Custom_fields: Custom fields for the contact, where the key is the custom field name and the value is valid based on the field type.
- List_id: The ID of the list to which the contact should be added.
- Tags: Array of tag IDs to associate with the contact.
- Update_subscribers: If set to true, it will update existing subscribers with the same email. Default is false.
D. Sample Response
{
"status": 202,
"message": "Request processed successfully.",
"data": {
"invalid_contacts": [
{
"first_name": "Avi",
"last_name": "S",
"email": "avinash+api1@kasplo.com",
"custom_fields": {
"city": "Mysore",
"age": "27"
},
"string": "Contact already exists in request, not unique"
}
],
"total_invalid": 1,
"total_valid": 1,
"valid_contacts": [
{
"first_name": "Avi",
"last_name": "S",
"email": "avinash+api1@kasplo.com",
"custom_fields": {
"city": "Mysore",
"age": "27"
}
}
]
},
"error": {}
}
Response Description:
- Invalid_contacts: List of contacts that were invalid (with a reason for the invalidity).
- Valid_contacts: List of contacts that were successfully added.
- Total_valid: Total number of valid contacts.
- Total_invalid: Total number of invalid contacts.
Notes:
Contacts insertion and updation are asynchronous. There might be a slight delay before the contacts are fully added or updated.
