# Managing Lists & Segments via API

Manage lists and segments through the 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.
