# Your app as the record of subscriptions

> Part of the Cowliss docs. Markdown for every page: append `index.md` to its URL. Site map: /llms.txt

Some products run a newsletter for each of their own customers: a portfolio site where visitors follow an artist, a platform where readers follow a creator. One person may follow several of them, and leaving one must never touch the others.

Cowliss keeps one answer per purpose per profile, so a person held as one profile has one answer for every artist. Your app already knows who follows whom, so let it stay the record, and let Cowliss send. This page shows the shape that works, what Cowliss guarantees for it, and how your app hears what happened after each email.

## One profile per subscription

Identify each subscription as its own profile. Its `userId` is your subscription's id, and the address goes in the `email` trait, never in an `email` identifier:

```ts
await cow.identify({
  identifiers: { userId: subscription.id },
  traits: {
    email: subscription.email,
    artist: subscription.artistName,
    unsubscribeUrl: `https://example.com/leave/${subscription.token}`,
  },
  consent: { "marketing.artistNewsletter": true },
});
```

A visitor who follows three artists is three profiles with the same address. Each one is mailed, unsubscribed and reported on by itself.

Two things Cowliss guarantees, which this shape relies on:

- **A trait never becomes an identifier.** Profiles are found by their identifiers only, so two profiles can carry the same `email` trait and stay two profiles. Put the address in `identifiers` and the two subscriptions become one person.
- **The unsubscribe link is read from the recipient when the email is sent.** Each email carries the link on the profile it goes to, so leaving one subscription leaves that one alone.

## Your own unsubscribe page

Name the trait that holds each subscription's unsubscribe URL on your app, once:

```sh
cow apps update <appId> --unsubscribe-url-trait unsubscribeUrl
```

From then on a marketing email to that profile links to your page: the footer link, the link props and the one-click unsubscribe button in the recipient's mail app. Your page makes the change in your own records, and your next identify carries it to Cowliss. [Your own unsubscribe](/guides/partners/#your-own-unsubscribe) lists what that page must do (offer the change on GET, make it on the one-click POST).

## What is per address, not per subscription

Suppression. When an address bounces for good or its owner reports an email as spam, Cowliss stops sending to that address for your whole organization, on every subscription that carries it. The mailbox is the same one, and so is the person who complained. Your app hears about it at once, below, so it can show the subscriber why mail stopped.

## Hearing what happened

Cowliss records each of these as a [system event](/reference/system-events/) on the profile the email went to:

| Event | What happened |
| --- | --- |
| `system.email_bounced` | The address is dead, or already on the do-not-send list (`suppressed: true`). Stop sending to it. |
| `system.email_soft_bounced` | A temporary bounce, such as a full mailbox. Nothing is stopped. |
| `system.email_complained` | The recipient reported the email as spam. |
| `system.consent_revoked` | A purpose went off: an unsubscribe, a complaint, the preferences page, or a teammate in the dashboard. |
| `system.consent_granted` | A purpose went on. |

Each outcome event carries the `deliveryId` your send returned, the `purpose` the email was sent under and the mail provider's `reason`. To get them in your app, push two automations that forward them to a [webhook](/reference/api/webhooks/) you registered as `subscriptions`. A webhook name is unique in your organization, so when two of your apps forward this way, give each its own (`shop-subscriptions`, `blog-subscriptions`) and name it in that app's automations. The first forwards the email outcomes:

```json title="automations/forward-outcomes.json"
{
  "description": "Tells our app when an email to a subscriber bounces or draws a spam complaint.",
  "trigger": {
    "event": [
      "system.email_bounced",
      "system.email_soft_bounced",
      "system.email_complained"
    ]
  },
  "purpose": "transactional",
  "from": "hello@example.com",
  "steps": [
    {
      "id": "tell-our-app",
      "type": "sendWebhook",
      "webhook": "subscriptions",
      "payload": {
        "event": { "var": "event.name" },
        "properties": { "var": "event.properties" },
        "occurredAt": { "var": "event.timestamp" }
      }
    }
  ]
}
```

The second forwards consent changes that did not come from your app:

```json title="automations/forward-consent.json"
{
  "description": "Tells our app when a subscriber's consent changes anywhere but in our app.",
  "trigger": {
    "event": ["system.consent_revoked", "system.consent_granted"]
  },
  "purpose": "transactional",
  "from": "hello@example.com",
  "steps": [
    {
      "id": "not-our-own-write",
      "type": "branch",
      "if": { "!==": [{ "var": "event.properties.reason" }, "app"] },
      "then": [
        {
          "id": "tell-our-app",
          "type": "sendWebhook",
          "webhook": "subscriptions",
          "payload": {
            "event": { "var": "event.name" },
            "properties": { "var": "event.properties" },
            "occurredAt": { "var": "event.timestamp" }
          }
        }
      ]
    }
  ]
}
```

Four choices in them matter:

- **`purpose` is `transactional`.** A `marketing` automation's webhooks wait for the recipient's yes to marketing, so the unsubscribe it is forwarding would stop its own forward.
- **The consent one drops reason `app`.** A consent change your own identify made is one your app already knows about, and forwarding it would echo it back.
- **They are two automations, not one.** A person is in an automation [once at a time](/automations/#enrollment), and an event that arrives while their run is still open does not start another. A spam complaint on marketing email is followed at once by the consent it turns off, so one automation for both would forward the complaint and miss the rest.
- **Read a root as covering its names.** Turning `marketing` off turns off every name under it, and each gets its own event, all at the same moment. The root's event comes first and is the one forwarded, so when your app hears that `marketing` went off, it treats every `marketing.*` purpose of that subscriber as off too.

Use your own verified address for `from`; the automation sends no email. `occurredAt` is when the event happened, in milliseconds since the Unix epoch. Every webhook body carries the profile's `identifiers`, so your endpoint reads `userId` (your subscription's id) straight from it and needs no lookup. See [the `sendWebhook` step](/automations/api/#sendwebhook) for the whole body.

## What this costs

- Cowliss's own consent counts (a list's subscribers, a broadcast's unsubscribes) say little for an app shaped like this. Read your own records instead.
- A send to a bare address, with no profile, has no outcome events. Address a profile with `to: { userId }` to get them.
- An organization past its spend limit forwards nothing until it has credit again, like any other webhook.
