Your app as the record of subscriptions
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
Section titled “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:
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
emailtrait and stay two profiles. Put the address inidentifiersand 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
Section titled “Your own unsubscribe page”Name the trait that holds each subscription’s unsubscribe URL on your app, once:
cow apps update <appId> --unsubscribe-url-trait unsubscribeUrlFrom 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).
What is per address, not per subscription
Section titled “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
Section titled “Hearing what happened”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:
{ "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", "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:
{ "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", "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:
purposeistransactional. Amarketingautomation’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
marketingoff 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 thatmarketingwent off, it treats everymarketing.*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.
What this costs
Section titled “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.