Segments and topics
Group contacts with saved filters (segments) and let them opt in or out of subjects (topics).
- A segment is a saved filter over your contacts, for example "plan is pro and city is Bandung". Broadcasts can target a segment.
- A topic is a subject people can subscribe to, for example "product-updates". Broadcasts can target the subscribers of a topic, and contacts can leave one topic without unsubscribing from everything.
All endpoints on this page accept an email API key (or a Helipod API key with the Email API enabled) and act on the key's project.
Segments
Segment object
Prop
Type
Filter rules
{
"operator": "and",
"rules": [
{ "property": "plan", "op": "equals", "value": "pro" },
{ "property": "email", "op": "contains", "value": "@company.com" }
]
}Prop
Type
A rule on a custom property matches only contacts that have that property.
Segment membership is calculated when the segment is created, when its filter changes, and when you ask for a recalculation. Contacts added later are not included until the next calculation.
List segments
/segmentscurl https://mail.helipod.io/api/email/segments \
-H "Authorization: Bearer your_email_api_key"Preview a filter
/segments/previewcurl -X POST https://mail.helipod.io/api/email/segments/preview \
-H "Authorization: Bearer your_email_api_key" \
-H "Content-Type: application/json" \
-d '{"filter":{"operator":"and","rules":[{"property":"plan","op":"equals","value":"pro"}]}}'{ "success": true, "data": { "count": 312 } }Create a segment
/segmentsProp
Type
curl -X POST https://mail.helipod.io/api/email/segments \
-H "Authorization: Bearer your_email_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Pro customers in Bandung",
"filter": {
"operator": "and",
"rules": [
{ "property": "plan", "op": "equals", "value": "pro" },
{ "property": "city", "op": "equals", "value": "Bandung" }
]
}
}'Response 201: the segment object with its contactCount. Error: 402 SEGMENT_LIMIT_REACHED.
Get a segment
/segments/{id}curl https://mail.helipod.io/api/email/segments/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b \
-H "Authorization: Bearer your_email_api_key"Returns the segment object, or 404 SEGMENT_NOT_FOUND. To list its members, use GET /contacts?segmentId=....
Update a segment
/segments/{id}Prop
Type
curl -X PATCH https://mail.helipod.io/api/email/segments/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b \
-H "Authorization: Bearer your_email_api_key" \
-H "Content-Type: application/json" \
-d '{"name":"Pro customers (West Java)"}'Returns the updated segment object.
Recalculate a segment
/segments/{id}/recalculatecurl -X POST https://mail.helipod.io/api/email/segments/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b/recalculate \
-H "Authorization: Bearer your_email_api_key"{ "success": true, "data": { "jobId": "eml_3c4d5e6f7a8b9c0d1e2f" } }Response status is 202. Run this before sending a broadcast to a segment if you added contacts since its last calculation.
Delete a segment
/segments/{id}curl -X DELETE https://mail.helipod.io/api/email/segments/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b \
-H "Authorization: Bearer your_email_api_key"{ "success": true, "data": { "deleted": true } }Topics
Topic object
Prop
Type
Contacts are subscribed to topics with PUT /contacts/{id}/topics and leave them with POST /contacts/{id}/unsubscribe.
List topics
/topicscurl https://mail.helipod.io/api/email/topics \
-H "Authorization: Bearer your_email_api_key"Create a topic
/topicsProp
Type
curl -X POST https://mail.helipod.io/api/email/topics \
-H "Authorization: Bearer your_email_api_key" \
-H "Content-Type: application/json" \
-d '{"name":"product-updates","description":"New features, once a month"}'Response 201: the topic object. Error: 402 TOPIC_LIMIT_REACHED.
Update a topic
/topics/{id}Prop
Type
curl -X PATCH https://mail.helipod.io/api/email/topics/6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d \
-H "Authorization: Bearer your_email_api_key" \
-H "Content-Type: application/json" \
-d '{"description":"New features, twice a month"}'Returns the updated topic object, or 404 TOPIC_NOT_FOUND.
Delete a topic
/topics/{id}curl -X DELETE https://mail.helipod.io/api/email/topics/6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d \
-H "Authorization: Bearer your_email_api_key"{ "success": true, "data": { "deleted": true } }