# Tags

> Add and remove contact tags from your code to target campaigns and start automations.

Source: https://www.mailmanny.com/docs/tags
All docs for AI agents: https://www.mailmanny.com/llms.txt

Tags are labels you put on contacts: customer, vip, attended-workshop. Contacts never see them. Use them to target campaigns, build segments and start automations.

## Add and remove tags

`POST /api/v1/audiences/{id}/contacts/{email_or_id}/tags` (permission: `contacts:write`)

Tags are referenced by name. A name that doesn't exist in the audience yet is created. Adding a tag the contact already has, or removing one they don't, does nothing, so the call is safe to repeat.

**Node.js SDK**

```ts
const { data } = await mm.contacts.tags({
  audienceId,
  email: "sam@example.com",
  add: ["customer", "sourdough-club"],
  remove: ["trial"],
});

console.log(data?.tags); // ["newsletter", "customer", "sourdough-club"]
```

**curl**

```bash
curl -X POST https://www.mailmanny.com/api/v1/audiences/$AUDIENCE_ID/contacts/sam@example.com/tags \
  -H "Authorization: Bearer $MAILMANNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "add": ["customer", "sourdough-club"], "remove": ["trial"] }'
```

**200 OK**

```json
{
  "object": "contact",
  "id": "0199f0b2-6c1e-7a3d-9f2b-3c4d5e6f7a8b",
  "added": ["customer", "sourdough-club"],
  "removed": ["trial"],
  "tags": ["newsletter", "customer", "sourdough-club"]
}
```

`added` and `removed` list what actually changed; `tags` is the full set afterwards. Up to 50 names per list, 100 characters each.

## Tag while adding a contact

`tags` on [POST /contacts](https://www.mailmanny.com/docs/contacts.md) adds tags in the same request. It never removes tags the contact already has.

```ts
await mm.contacts.create({
  audienceId,
  email: "sam@example.com",
  tags: ["newsletter", "from-checkout"],
});
```

## Tags start automations

An automation with a **Tag added** trigger starts for every contact that gets the tag, whether you add it in the app, on import or through the API. A common pattern: tag `customer` after the first purchase and let an onboarding series take it from there.

> **Tip:** Tags or events?
> Use a tag for something that stays true (they're a customer). Use an [event](https://www.mailmanny.com/docs/events.md) for something that happened (they placed order #1042), especially if it can happen more than once.