Skip to content
Cowliss is in beta: features and pricing may change.

Your app as the record of subscriptions

View as markdown

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.

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:

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.

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

Terminal window
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 lists what that page must do (offer the change on GET, make it on the one-click POST).

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.

Cowliss records each of these as a system event 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 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:

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": "[email protected]",
"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:

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": "[email protected]",
"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, 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 for the whole body.

  • 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.