Do I have to create a tag before I use it?

No. Send the name and any tag that does not exist yet is created as it is attached. There is a create endpoint if you want to define one up front, but nothing requires it.

What is the difference between a tag and a property?

A tag is a fact with no value: somebody either carries cancel-pending or they do not. A property carries a value, is arbitrary JSON, and is what you reach for when the branch depends on what something is rather than on whether it happened.

How do I remove a tag?

One DELETE call against the contact and the tag. A customer whose payment recovers drops out of the dunning segment as soon as the tag goes, because the segment is a rule rather than a stored list.

Can I import the tags I already have?

Yes. Contacts and their tags come in over the API, and the upsert endpoint matches on email, so a sync job can run twice without creating duplicates.

Tags and segments

Tag a contact from your own backend and a sequence starts. Segments are just rules over tags and properties, so there is no separate list to keep in sync.

Contact record

Screenshot pending. A contact detail view showing the tags on the person, their custom properties, and the event timeline underneath, from a real workspace with the email address obscured.

What it does

Most tools ask you to maintain lists. A person is on one, or on several, and keeping those lists correct quietly becomes somebody's job. Tags invert that. You record facts about a contact at the moment they happen, and the segments fall out of the facts.

A tag is a name: trial-started, cancel-pending, plan-pro. You attach it from your own backend when the thing it describes actually happens, and names that do not exist yet are created as they are attached, so nothing has to be provisioned before it can be used.

Alongside tags, a contact carries custom properties stored as JSON and a timeline of events you have tracked with your own metadata. Between the three, anything your product knows about somebody can decide what they receive.

The shape of it

01
Something happens
A trial starts, a payment fails, somebody stops logging in. Your app knows first.
02
Attach the tag
One call by name. Names that do not exist yet are created on the way in.
03
Rules re-evaluate
Segments are questions over tags, properties and events, not lists you fill.
04
The sequence runs
A tag-triggered flow picks the contact up without a second API call.

How it works

One call attaches a tag by name. There is no lookup step, no tag id to keep in a config file, and no create-then-attach dance.

Adding a tag is also what starts a tag-triggered sequence, so the same call that records the fact enrols the person in whatever should happen next. For most lifecycle email that is the entire integration: your billing webhook fires, you attach payment-failed, and dunning begins.

Segments are rules over the same data rather than a second copy of it. A segment is not a list you fill, it is a question you ask about tags, properties and events, and its membership changes the moment the underlying fact changes. Removing a tag is a single call too, so a contact whose payment recovers leaves the dunning segment without anybody reconciling anything.

POST /contacts/{id}/tags

curl -X POST \
  https://api.sendheron.com/api/v1/contacts/$CONTACT_ID/tags \
  -H "Authorization: Bearer $SENDHERON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tagNames": ["cancel-pending"]}'

# 201 Created. The tag is attached, and any sequence
# triggered by cancel-pending has just enrolled this contact.

Attach tags by name, and names that do not exist yet are created
Adding a tag is what starts a tag-triggered sequence
Arbitrary custom properties per contact, stored as JSON
Track custom events against a contact with your own metadata
No list membership to reconcile

Add tags over the API

What makes it different, honestly

There is no list membership to keep in sync, which removes a whole category of embarrassing bug: the person who cancelled but stayed on the win-back list, the customer who upgraded and kept getting trial nudges.

Tags and segments are unlimited on every tier, for the same reason sequences are. They cost us nothing to hold, so metering them would be a billing tactic rather than a price.

The honest limitation is that this model is only as good as what your backend tells us. A tag-driven system beats a list-driven one exactly to the degree that your application is wired to report what happens. If adding one call to your billing webhook is not something you want to do, a tool that infers intent from opens and clicks will feel easier at the start, and be wrong more often later.

Questions