API Reference

Segments

Segments are dynamic groups of contacts defined by filter conditions. Contacts are matched in real-time based on the segment's rules.

List Segments

GET

/segments

Returns all segments with their current matching contact count.

Example

curl https://mailtani.com/api/v1/segments \
  -H "Authorization: Bearer mk_your_api_key_here"

Response 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "Active VIPs",
      "description": "Active contacts with the VIP tag",
      "color": "#fa5252",
      "match_type": "all",
      "conditions": [
        { "field": "status", "operator": "equals", "value": "active" },
        { "field": "tag", "operator": "has", "value": "VIP" }
      ],
      "contacts_count": 85,
      "created_at": "2026-01-08T10:00:00+00:00",
      "updated_at": "2026-01-08T10:00:00+00:00"
    }
  ]
}

Create a Segment

POST

/segments

Body

name

string

Segment name.

Required

description

string

Optional description.

Optional

color

string

default: #228be6

Hex color code.

Optional

match_type

string

`all` to require all conditions (AND), or `any` to require at least one (OR).

Required

conditions

array

Array of filter conditions. Each requires `field`, `operator`, and `value`.

Required

conditions[].field

string

Field to filter on. See available fields below.

Required

conditions[].operator

string

Comparison operator. Depends on the field type.

Required

conditions[].value

mixed

Value to compare against.

Required

Available Fields and Operators

Field	Operators	Value
`status`	`equals`, `not_equals`	`active`, `bounced`, `unsubscribed`, `complained`
`source`	`equals`, `not_equals`	`manual`, `import`, `api`, `scraper`
`email`	`contains`, `not_contains`, `starts_with`, `ends_with`	string
`tag`	`has`, `has_not`	tag name
`list`	`in`, `not_in`	list ID
`created_at`	`before`, `after`	ISO 8601 date

Example

curl -X POST https://mailtani.com/api/v1/segments \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gmail Users",
    "match_type": "all",
    "conditions": [
      { "field": "email", "operator": "ends_with", "value": "@gmail.com" },
      { "field": "status", "operator": "equals", "value": "active" }
    ]
  }'

Response 201 Created — returns the created segment object.

Get a Segment

GET

/segments/{id}

Returns segment details with current contact count.

Example

curl https://mailtani.com/api/v1/segments/1 \
  -H "Authorization: Bearer mk_your_api_key_here"

Response 200 OK — returns the segment object.

Update a Segment

PUT

/segments/{id}

Updates the segment's name, description, color, match type, or conditions. Accepts the same body as Create.

Example

curl -X PUT https://mailtani.com/api/v1/segments/1 \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Active Gmail Users" }'

Response 200 OK — returns the updated segment object.

Delete a Segment

DELETE

/segments/{id}

Deletes the segment. Contacts matching the segment are not affected.

Example

curl -X DELETE https://mailtani.com/api/v1/segments/1 \
  -H "Authorization: Bearer mk_your_api_key_here"

Response 204 No Content

Preview Segment Contacts

GET

/segments/{id}/contacts

Returns a paginated list of contacts currently matching the segment's conditions.

Query Parameters

page

integer

default: 1

Page number.

Optional

Example

curl "https://mailtani.com/api/v1/segments/1/contacts?page=1" \
  -H "Authorization: Bearer mk_your_api_key_here"

Returns the same contact format as the Contacts API.