mailtanimailtani
Log InStart Your Free Trial

API Reference

Introduction
Emails
Contacts
Lists
Tags
Campaigns
Flow Campaigns
Segments
Events & Automations
Errors & Rate Limiting
GuidesSetupMCP Server

Lists

Organize contacts into lists for targeted outreach.

List All Lists

GET
/lists

Returns all lists in the current project, ordered alphabetically by name.

Example

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

Response 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "Newsletter Subscribers",
      "description": "Users who opted in to the newsletter",
      "color": "#228be6",
      "contacts_count": 1250,
      "created_at": "2026-01-05T12:00:00+00:00",
      "updated_at": "2026-01-05T12:00:00+00:00"
    }
  ]
}

Create a List

POST
/lists

Body

name

string

List name. Max 255 characters.

Required
description

string

Optional description.

Optional
color

string

default: #228be6

Hex color code for the list.

Optional

Example

curl -X POST https://mailtani.com/api/v1/lists \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Launch",
    "description": "Contacts interested in the new product launch",
    "color": "#40c057"
  }'

Response 201 Created

{
  "data": {
    "id": 2,
    "name": "Product Launch",
    "description": "Contacts interested in the new product launch",
    "color": "#40c057",
    "contacts_count": 0,
    "created_at": "2026-01-15T09:00:00+00:00",
    "updated_at": "2026-01-15T09:00:00+00:00"
  }
}

Get a List

GET
/lists/{id}

Example

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

Response 200 OK — returns the list object.

Update a List

PUT
/lists/{id}

Body

name

string

Updated list name.

Optional
description

string

Updated description.

Optional
color

string

Updated hex color.

Optional

Example

curl -X PUT https://mailtani.com/api/v1/lists/2 \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Launch - Q1" }'

Response 200 OK — returns the updated list object.

Delete a List

DELETE
/lists/{id}

Deletes the list. Contacts in the list are not deleted.

Example

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

Response 204 No Content

Add Contacts to a List

POST
/lists/{id}/contacts

Adds contacts to a list. Contacts already in the list are silently skipped.

Body

contact_ids

array

Array of contact IDs to add to the list.

Required

Example

curl -X POST https://mailtani.com/api/v1/lists/1/contacts \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "contact_ids": [1, 2, 3] }'

Response 200 OK

{ "added": 3, "skipped": 0 }

Remove a Contact from a List

DELETE
/lists/{id}/contacts/{contactId}

Removes a single contact from the list. The contact itself is not deleted.

Example

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

Response 204 No Content