Manage subscribers

Keep your email audience in step with your app: add a subscriber when someone signs up, tag them as their plan changes, and unsubscribe them when they ask. Subscribers are addressed by email and are the same contacts you see in the console audience.

The subscribers calls ship in @buildbase/sdk 1.0.0. If bb.subscribers is undefined, you are on an earlier version.

Quick example

import { createServerClient } from '@buildbase/sdk/server';

const bb = createServerClient({
  serverUrl: 'https://api.console.buildbase.app',
  apiToken: process.env.BUILDBASE_API_TOKEN!, // <orgId>:<secret>
});

export async function onSignup(user: {
  email: string;
  name: string;
  plan: string;
}) {
  const subscriber = await bb.subscribers.upsert({
    email: user.email,
    name: user.name,
    tags: ['customer'],
    attributes: { plan: user.plan },
    lists: [process.env.NEWSLETTER_LIST_ID!],
  });
  return subscriber.created; // true the first time, false after
}

Upsert

upsert creates the subscriber, or updates the one with that address. What you leave out is kept.

An upsert never changes whether someone is subscribed. A sign-up form that upserts again does not resubscribe a person who left.

An unknown tag slug or list id is refused with UNKNOWN_REFERENCE and changes nothing. A new subscriber counts toward your plan's contact limit; updating one never does.

Read, unsubscribe and resubscribe

const subscriber = await bb.subscribers.get('[email protected]'); // null when there is none

await bb.subscribers.unsubscribe('[email protected]', {
  reason: 'asked by email',
});
await bb.subscribers.resubscribe('[email protected]');

unsubscribe stops marketing and transactional sends to the address; account email such as password resets still arrives. resubscribe is refused with RECIPIENT_SUPPRESSED for an address that bounced or is a spam trap.

Delete

await bb.subscribers.delete('[email protected]');

Delete takes the subscriber off every list (firing audience.removed_from_list for each) and then soft-deletes them: they no longer appear in the console, in reads or in any send, but the record is kept, marked deleted, and so is their history, such as the email already sent to them, so a delete is not an erasure of their data. The console has no delete; this call is the only way to remove a contact. The address can be added again later and then starts subscribed, so to stop email to a person who asked, unsubscribe them instead.

Events

Every change fires the same events as the console, so your workflows and webhooks see it: audience.member_created, audience.member_updated, audience.tag_added, audience.tag_removed, audience.attribute_changed, audience.added_to_list, audience.removed_from_list (on delete), audience.unsubscribed and audience.resubscribed.

Handling refusals

Refusals throw BuildBaseApiError with status and code:

The contact or list-size limit is a 402 with the plan's code.

Next steps

• Send transactional email
• Email campaigns
• Server SDK overview