API Reference

Tags

Tags are lightweight labels you can attach to contacts for flexible categorization and filtering.

List All Tags

GET

/tags

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

Example

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

Response 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "VIP",
      "color": "#fa5252",
      "contacts_count": 85,
      "created_at": "2026-01-05T12:00:00+00:00",
      "updated_at": "2026-01-05T12:00:00+00:00"
    }
  ]
}

Create a Tag

POST

/tags

Body

name

string

Tag name. Max 255 characters.

Required

color

string

default: #868e96

Hex color code for the tag.

Optional

Example

curl -X POST https://mailtani.com/api/v1/tags \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise",
    "color": "#7950f2"
  }'

Response 201 Created

{
  "data": {
    "id": 2,
    "name": "Enterprise",
    "color": "#7950f2",
    "contacts_count": 0,
    "created_at": "2026-01-15T09:00:00+00:00",
    "updated_at": "2026-01-15T09:00:00+00:00"
  }
}

Get a Tag

GET

/tags/{id}

Example

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

Response 200 OK — returns the tag object.

Update a Tag

PUT

/tags/{id}

Body

name

string

Updated tag name.

Optional

color

string

Updated hex color.

Optional

Example

curl -X PUT https://mailtani.com/api/v1/tags/2 \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Enterprise Client", "color": "#be4bdb" }'

Response 200 OK — returns the updated tag object.

Delete a Tag

DELETE

/tags/{id}

Deletes the tag. Contacts with the tag are not deleted — the tag is simply removed from them.

Example

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

Response 204 No Content