Managing Lists & Segments via API

Manage lists and segments through the API

Managing Lists & Segments via API

Lists and segments are the two ways to organize contacts in Mailnaptic. Lists are explicit opt-in groups that contacts subscribe to. Segments are dynamic audiences defined by filter rules that automatically update as contact data changes. Both are fully manageable through the API.

Lists

Create a list

POST /api/v1/lists

{
  "name": "Weekly Newsletter",
  "description": "Weekly product updates and tips"
}

List all lists

GET /api/v1/lists

Returns all lists with their ID, name, description, and subscriber count.

Get list details

GET /api/v1/lists/:id

Returns the list details along with member count and creation date.

Update a list

PUT /api/v1/lists/:id

{
  "name": "Weekly Product Newsletter",
  "description": "Updated description"
}

Delete a list

DELETE /api/v1/lists/:id

Deletes the list. Contacts who were members are not deleted — they remain in your account but are no longer associated with this list.

List members

GET /api/v1/lists/:id/members?page=1&per_page=50

Returns a paginated list of contacts who are subscribed to this list.

Add a member

POST /api/v1/lists/:id/members

{
  "contact_id": 12345
}

Remove a member

DELETE /api/v1/lists/:id/members/:contact_id

Segments

Create a segment

POST /api/v1/segments

{
  "name": "Active subscribers",
  "logic": "and",
  "rules": [
    {
      "type": "email_opened",
      "op": "less_than",
      "value": 30
    },
    {
      "type": "last_active_days",
      "op": "less_than",
      "value": 14
    }
  ]
}

Segment rule structure

Each rule is an object with at least a type field. Additional fields depend on the rule type:

Rule type	Parameters	Description
`email_opened`	`op`, `value` (days)	Opened an email within N days
`email_not_opened`	`op`, `value` (days)	Has not opened in N days
`email_clicked`	`op`, `value` (days)	Clicked a link within N days
`email_not_clicked`	`op`, `value` (days)	Has not clicked in N days
`last_active_days`	`op` (`less_than`/`greater_than`), `value`	Days since last activity
`site_visited_page`	`value` (URL pattern)	Visited a specific page
`site_triggered_event`	`value` (event name)	Triggered a custom web event
`site_purchased`	none	Completed a purchase event
`tag`	`value` (tag name)	Has a specific tag
`list`	`value` (list ID)	Is a member of a specific list
`custom_field`	`field`, `op`, `value`	Custom field matches a condition

Get segment details

GET /api/v1/segments/:id

Returns the segment's name, logic, rules, and current member count.

Preview segment members

GET /api/v1/segments/:id/preview?page=1&per_page=50

Returns a paginated list of contacts that currently match the segment's rules. Since segments are dynamic, this list can change every time you query it.

Update a segment

PUT /api/v1/segments/:id

{
  "name": "Highly active subscribers",
  "rules": [
    {
      "type": "email_opened",
      "op": "less_than",
      "value": 7
    }
  ]
}

Delete a segment

DELETE /api/v1/segments/:id

Deletes the segment definition. Contacts are not affected. If the segment is used as a campaign target or exclusion, remove it from those campaigns first.

Lists vs. segments: when to use which

Use lists for explicit opt-in groups where the contact actively chose to subscribe (e.g., "Weekly Newsletter", "Product Updates").
Use segments for dynamic audiences based on behavior or attributes (e.g., "opened an email in the last 30 days", "tagged as VIP").
Use both together: target a segment of active subscribers within a specific list to maximize engagement.

Scopes required: lists:read / lists:write for list operations, segments:read / segments:write for segment operations.

Managing Lists & Segments via API