Tags & statuses

Tags and statuses help organize prospects in your Inbox. Tags are flexible labels for categorization. Statuses represent pipeline stages.

Feature	Tags	Statuses
Per prospect	Multiple	One
Use case	Flexible labels	Pipeline stages
Example	”Hot Lead”, “Enterprise"	"New → Qualified → Won”

Tags

const { data: tags } = await client.get("/tags");

console.log(`Found ${tags.length} tags`);
tags.forEach((tag) => {
  console.log(`${tag.name} (${tag.color})`);
});

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

Response:

[
  { "id": "t8rvk2m5j0xn4wq7ybftcael", "name": "Hot Lead", "color": "#ef4444" },
  {
    "id": "u9swl3n6k1yo5xr8zcgudbfm",
    "name": "Enterprise",
    "color": "#3b82f6"
  },
  { "id": "v0txm4o7l2zp6ys9adhvecgn", "name": "Partner", "color": "#22c55e" }
]

Create tag

const { data: tag } = await client.post("/tags", {
  name: "VIP",
  color: "purple",
});

console.log("Created tag:", tag.id);

Colors accept either a predefined name ("red", "blue", "green", "purple", etc.) or a hex code ("#ef4444"). Use GET /tags/colors to see all predefined options.

Update tag

const { data: tag } = await client.patch(`/tags/${tagId}`, {
  name: "VIP Customer",
  color: "#6366f1",
});

Delete tag

await client.delete(`/tags/${tagId}`);

Deleting a tag removes it from all prospects. This cannot be undone.

Apply tags to a prospect

Tags are updated incrementally using addTags and removeTags on the prospect context endpoint:

// Add tags
await client.patch(`/prospects/${prospectId}/context`, {
  addTags: ["t8rvk2m5j0xn4wq7ybftcael", "u9swl3n6k1yo5xr8zcgudbfm"],
});

// Remove a tag
await client.patch(`/prospects/${prospectId}/context`, {
  removeTags: ["t8rvk2m5j0xn4wq7ybftcael"],
});

// Add and remove in one request
await client.patch(`/prospects/${prospectId}/context`, {
  addTags: ["v0txm4o7l2zp6ys9adhvecgn"],
  removeTags: ["u9swl3n6k1yo5xr8zcgudbfm"],
});

There is no tagIds field. Tags are always modified incrementally with addTags and removeTags.

Statuses

List statuses

const { data: statuses } = await client.get("/statuses");

statuses.forEach((status) => {
  console.log(`${status.name} (${status.color})`);
});

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

Response:

[
  {
    "id": "s3km7xj9wq5p2bvnhfdteoly",
    "name": "New",
    "color": "#64748b",
    "createdAt": "2024-06-01T12:00:00.000Z"
  },
  {
    "id": "s4ln8yk0xr6q3cw1behsifup",
    "name": "Qualified",
    "color": "#f59e0b",
    "createdAt": "2024-06-01T12:00:00.000Z"
  },
  {
    "id": "s5mo9zl1ys7r4dx2cfitjgvq",
    "name": "Won",
    "color": "#22c55e",
    "createdAt": "2024-06-01T12:00:00.000Z"
  }
]

Create status

const { data: status } = await client.post("/statuses", {
  name: "Demo Scheduled",
  color: "teal",
});

console.log("Created status:", status.id);

Update status

const { data: status } = await client.patch(`/statuses/${statusId}`, {
  name: "Demo Complete",
  color: "#14b8a6",
});

Delete status

await client.delete(`/statuses/${statusId}`);

Deleting a status removes it from all prospects. This cannot be undone. The consumer is responsible for handling any side effects — the API does not emit individual prospect.statusChanged events for each affected prospect.

Set prospect status

await client.patch(`/prospects/${prospectId}/context`, {
  statusId: "s4ln8yk0xr6q3cw1behsifup",
});

Clear prospect status

await client.patch(`/prospects/${prospectId}/context`, {
  statusId: null,
});

Filtering threads by tags and statuses

Filter threads using the filters parameter on GET /threads. Filters combine with AND logic:

const { data } = await client.get("/threads", {
  params: {
    inbox: "default",
    "filters[tags][selectedIds][0]": "t8rvk2m5j0xn4wq7ybftcael",
    "filters[statuses][selectedIds][0]": "s4ln8yk0xr6q3cw1behsifup",
    "filters[assignees][noAssignee]": true,
  },
});

Use filters[tags][noTags]: true or filters[statuses][noStatus]: true to find threads with no tags or no status respectively. See Managing threads — Filtering for the full list of filter options and the Query parameters reference for encoding details.

Common patterns

Tag system setup

const standardTags = [
  { name: "Hot Lead", color: "red" },
  { name: "Warm Lead", color: "orange" },
  { name: "Cold Lead", color: "slate" },
  { name: "Customer", color: "green" },
  { name: "Partner", color: "blue" },
  { name: "Do Not Contact", color: "#1f2937" },
];

for (const tag of standardTags) {
  try {
    await client.post("/tags", tag);
    console.log(`Created: ${tag.name}`);
  } catch (error) {
    if (error.response?.status === 409) {
      console.log(`Exists: ${tag.name}`);
    } else {
      throw error;
    }
  }
}

Pipeline setup

const pipeline = [
  { name: "New", color: "slate" },
  { name: "Contacted", color: "blue" },
  { name: "Qualified", color: "amber" },
  { name: "Demo", color: "purple" },
  { name: "Proposal", color: "pink" },
  { name: "Won", color: "green" },
  { name: "Lost", color: "red" },
];

for (const status of pipeline) {
  try {
    await client.post("/statuses", status);
    console.log(`Created: ${status.name}`);
  } catch (error) {
    if (error.response?.status === 409) {
      console.log(`Exists: ${status.name}`);
    }
  }
}

Auto-tagging by follower count

async function autoTag(prospectId: string, followerCount: number) {
  const tagsToAdd: string[] = [];

  if (followerCount > 100000) tagsToAdd.push(influencerTagId);
  else if (followerCount > 10000) tagsToAdd.push(highReachTagId);

  if (tagsToAdd.length > 0) {
    await client.patch(`/prospects/${prospectId}/context`, {
      addTags: tagsToAdd,
    });
  }
}

List tags

GET /tags

Create tag

POST /tags

List statuses

GET /statuses

Create status

POST /statuses

Update prospect context

PATCH /prospects//context

Available colors

GET /colors

Getting started

Fundamentals

Configuration

Tags

Create tag

Update tag

Delete tag

Apply tags to a prospect

Statuses

List statuses

Create status

Update status

Delete status

Set prospect status

Clear prospect status

Filtering threads by tags and statuses

Common patterns

Tag system setup

Pipeline setup

Auto-tagging by follower count

List tags

Create tag

List statuses

Create status

Update prospect context

Available colors

​Tags

​List tags

​Create tag

​Update tag

​Delete tag

​Apply tags to a prospect

​Statuses

​List statuses

​Create status

​Update status

​Delete status

​Set prospect status

​Clear prospect status

​Filtering threads by tags and statuses

​Common patterns

​Tag system setup

​Pipeline setup

​Auto-tagging by follower count

​Related endpoints

List tags

Create tag

List statuses

Create status

Update prospect context

Available colors

Tags

List tags

Create tag

Update tag

Delete tag

Apply tags to a prospect

Statuses

List statuses

Create status

Update status

Delete status

Set prospect status

Clear prospect status

Filtering threads by tags and statuses

Common patterns

Tag system setup

Pipeline setup

Auto-tagging by follower count

Related endpoints