bunderstackbunderstack/ docs

Contacts

People to write to who are not users, sign-ups from your own forms, and one-click unsubscribe

app.contacts keeps the people an application writes to who need not be users: a waitlist, a newsletter form, a lead from a landing page. The tables are system tables (_bunderstack_contacts, _bunderstack_contact_addresses, _bunderstack_contact_tags), so every application has them; on Bunderhost they appear on the project's Contacts tab.

Adding contacts

await app.contacts.upsert({
  email: '[email protected]',
  name: 'Ana',
  source: 'waitlist',
  tags: ['beta'],
  attributes: { plan: 'pro' },
  consent: { source: 'waitlist form' }, // optional
})

upsert merges by address: tags add up, attributes merge, the first source stays, and an existing consent is kept. The same facade is ctx.contacts inside procedures and jobs.

await app.contacts.get({ email: '[email protected]' })
await app.contacts.list({ tag: 'beta', status: 'subscribed', limit: 50 })
await app.contacts.tag({ email }, ['vip'])
await app.contacts.untag({ email }, ['beta'])
await app.contacts.remove({ email }) // erases the contact

list filters by tag, source, search (name or address) and status: subscribed (neither unsubscribed nor suppressed), unsubscribed, suppressed or consented.

Getting people onto a list

A contact is on a list when it carries the list's tag; a broadcast to tags: { any: ['newsletter'] } reaches it. Adding one is a single step, from wherever the application learns about a person:

  • Your own code: ctx.contacts.upsert({ email, tags: ['newsletter'] }) in a procedure, a job, an auth hook or a webhook handler. The template's subscribeToNews procedure does this for a box ticked at sign-up.
  • A form on your pages: contacts.capture (below) takes a plain HTML or fetch post and needs no code of yours.
  • Elsewhere: a CSV import or the editor on Bunderhost's Contacts tab, or an agent with upsert_contacts.

There is no built-in confirmation email. A contact is subscribed the moment it is added, and every broadcast it receives carries a one-click unsubscribe.

Double opt-in, if you want one

When you do want people to confirm their address first, build it from the same pieces: add them under a holding tag, send your own confirmation email, and move them onto the list when they click.

// 1. On sign-up: saved, but not on the list yet.
await ctx.contacts.upsert({ email, tags: ['newsletter-pending'] })
const token = await signToken(email) // your own signed, expiring token
await ctx.messaging.email.send({
  to: email,
  subject: 'Confirm your subscription',
  html: `<a href="${env.APP_URL}/newsletter/confirm?t=${token}">Confirm</a>`,
})

// 2. In your /newsletter/confirm route, after checking the token:
await ctx.contacts.untag({ email }, ['newsletter-pending'])
await ctx.contacts.tag({ email }, ['newsletter'])
await ctx.contacts.upsert({ email, consent: { source: 'double opt-in' } })

Broadcasts to newsletter then reach only confirmed people, and the record of when and how each one agreed is the consent on their address.

Consent is something a contact can have, not a gate. consent records when and where someone agreed; status: 'consented' finds them. Nothing requires it. Whether you need it is your decision and your jurisdiction's.

Unsubscribe

Every address can be opted out, and an opted-out address is never written to by anything that sends to contacts.

await app.contacts.unsubscribe({ email })
await app.contacts.resubscribe({ email }) // when they sign up again
const url = await app.contacts.unsubscribeUrl({ email })

unsubscribeUrl returns a one-click link to /api/_bunderstack/unsubscribe?t=<token> (it needs APP_URL). The token is signed with AUTH_SECRET and names one address. Opening the link shows a confirmation page; a POST, which is what mail clients send for List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058), unsubscribes. A plain GET never does, because mail scanners open links.

To serve your own page, point the links at it and call unsubscribeByToken:

contacts: { unsubscribeUrl: 'https://shop.example/unsubscribe' }

// in your route
const result = await app.contacts.unsubscribeByToken(token) // { address } | null

Sign-ups from your own forms

contacts: {
  capture: { source: 'landing', tags: ['newsletter'], consent: true },
}

This mounts POST /api/_bunderstack/contacts, which takes email and an optional name as JSON or a form post:

<form method="post" action="/api/_bunderstack/contacts">
  <input name="email" type="email" required />
  <input name="website" tabindex="-1" autocomplete="off" hidden />
  <input type="hidden" name="redirect" value="/thanks" />
  <button>Subscribe</button>
</form>

It answers 204 (or 303 to a same-site redirect) whether or not the address was known, so it cannot be used to find out who is on the list. A filled website field is treated as a bot and ignored. Each address may post ten times a minute. consent: true records the form as the consent source.

Without capture, nothing is mounted at that path.

Broadcasts

A broadcast is one email to many contacts. It lives in _bunderstack_broadcasts, and the application's own worker sends it, through one of its email channels, so the provider and sender chosen for that channel apply. On Bunderhost you write it on the Broadcasts tab or have an agent draft it; a person approves the send, and Bunderhost queues the bunderstack:broadcast job.

  • Audience: tags (any, all, none), sources, and optionally only addresses with consent. Unsubscribed, bounced and complained addresses are always left out. Who receives it is fixed when sending starts.
  • Personalisation: {{name}}, {{email}}, {{attributes.<key>}} and {{unsubscribe_url}}; {{name | there}} falls back when the value is empty. Values are escaped in HTML.
  • Unsubscribe: every message carries List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click, and an unsubscribe footer when the HTML does not place {{unsubscribe_url}} itself. It needs APP_URL; without it the broadcast fails instead of sending.
  • Pace and recovery: five messages a second. One run sends for up to four minutes and queues the next. A message claimed by a run that died is reported as failed rather than sent twice.
  • History: per-recipient rows are kept 90 days; the broadcast keeps its counters (sent, delivered, opened, clicked, bounced, complained, unsubscribed, failed).

The job exists when the application already runs a worker (it declares jobs or storage) and has an email channel, so an application without background work does not start polling for it. A dedicated channel on its own subdomain keeps complaints about newsletters away from your sign-in mail:

messaging: {
  email: email(),
  news: email(), // sender set on the host, e.g. [email protected]
}

Migrations

The contact and broadcast tables come with bunderstack/schema. After upgrading, run drizzle-kit generate (or your db:generate script) and commit the migration, as for any other system table.

On this page