Tags and statuses

	Tags	Statuses
A contact has	Any number	At most one
Use for	Labels: `hot-lead`, `partner`	Pipeline stages: `Qualified`, `Won`
Color	Always	Optional

Both belong to contacts, not threads. Tagging a contact shows on every conversation with them.

Operation	Request
List	`GET /tags`
Create	`POST /tags`
Get	`GET /tags/{tagRef}`
Update	`PATCH /tags/{tagRef}`
Delete	`DELETE /tags/{tagRef}`

Statuses

curl -X POST "https://inboxapp.com/api/v2/statuses" \
  -H "Authorization: Bearer $INBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Qualified", "color": "green" }'

The same five operations exist under /statuses. Set a contact’s status with PATCH /contacts/{contactId}.

IDs or names

Anywhere a tag or status is expected, a path, a filter or a body field, you can pass its ID or its name.

Names match ignoring case and accents: hot-lead finds Hot-Lead.
When a value is one item’s ID and another’s name, the ID wins.
Names are unique within the team. Creating a duplicate fails with 409 nameTaken.

curl "https://inboxapp.com/api/v2/threads?tag=hot-lead&status=Qualified" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

Colors

color takes a name from the palette, or a 6-digit hex value. It is stored and returned as hex.

curl "https://inboxapp.com/api/v2/colors" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

[
  { "name": "blue", "hex": "#3b82f6" },
  { "name": "red", "hex": "#ef4444" }
]

A tag created without a color gets a random one from the palette. A status can have null.

Apply rules automatically

qualify.ts

const API = "https://inboxapp.com/api/v2";
const headers = {
  Authorization: `Bearer ${process.env.INBOX_API_TOKEN}`,
  "Content-Type": "application/json",
};

async function tagLargeAccounts() {
  const response = await fetch(`${API}/threads?folder=inbox&expand=profile`, {
    headers,
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.code}: ${error.message} (${error.requestId})`);
  }

  const { data: threads } = await response.json();

  for (const thread of threads) {
    if ((thread.profile.followerCount ?? 0) < 10_000) continue;

    await fetch(`${API}/contacts/${thread.contactId}/tags/high-reach`, {
      method: "PUT",
      headers,
    });
  }
}

Getting started

Fundamentals

Configuration

Webhooks

Event types

Reference

Resources

Platforms

Team

Account Links

Contacts

Threads

Messages

Tags

Statuses

Colors

Events

Tags

Statuses

IDs or names

Colors

Apply rules automatically

​Tags

​Statuses

​IDs or names

​Colors

​Apply rules automatically

Tags

Statuses

IDs or names

Colors

Apply rules automatically