> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Better Auth Integration

> Automatically sync users from Better Auth to create subscribers

Sync your [Better Auth](https://www.better-auth.com) users to Sequenzy with a simple plugin. When users sign up, they're automatically added as subscribers—enabling welcome emails, onboarding sequences, and more.

## Installation

Install the official Sequenzy plugin for Better Auth:

```bash theme={null}
npm install @sequenzy/better-auth
# or
bun add @sequenzy/better-auth
# or
pnpm add @sequenzy/better-auth
```

## Quick Setup

### 1. Get Your API Key

1. Go to **Settings → API Keys** in Sequenzy
2. Click **Create API Key**
3. Copy the key and add it to your environment variables:

```bash theme={null}
SEQUENZY_API_KEY=sk_live_xxxxxxxxxxxxx
```

### 2. Add the Plugin

Add the Sequenzy plugin to your Better Auth configuration:

```ts auth.ts theme={null}
import { betterAuth } from "better-auth";
import { sequenzy } from "@sequenzy/better-auth";

export const auth = betterAuth({
  // ... your existing config
  plugins: [
    sequenzy({
      apiKey: process.env.SEQUENZY_API_KEY!,
    }),
  ],
});
```

### 3. Add Client Plugin (Optional)

For TypeScript type inference, add the client plugin:

```ts auth-client.ts theme={null}
import { createAuthClient } from "better-auth/client";
import { sequenzyClient } from "@sequenzy/better-auth/client";

export const authClient = createAuthClient({
  plugins: [sequenzyClient()],
});
```

That's it! New users will now be automatically synced to Sequenzy.

## Configuration Options

```ts theme={null}
sequenzy({
  // Required: Your Sequenzy API key
  apiKey: process.env.SEQUENZY_API_KEY!,

  // Optional: Add subscribers to specific lists only
  // Default: Uses your workspace default lists setting
  listIds: ["list_welcome", "list_newsletter"],

  // Optional: Tags to assign to new subscribers
  tags: ["signup", "better-auth"],

  // Optional: Enroll in automation sequences
  // Default: true
  enrollInSequences: true,

  // Optional: Extract custom attributes from the user
  getCustomAttributes: (user) => ({
    authProvider: "better-auth",
    signupDate: new Date().toISOString(),
  }),

  // Optional: Success callback
  onSubscriberCreated: ({ userId, email, subscriberId }) => {
    console.log(`Synced ${email} to Sequenzy`);
  },

  // Optional: Error callback
  onError: (error, user) => {
    console.error(`Failed to sync ${user.email}:`, error.message);
  },
});
```

## What Gets Synced

When a user signs up through Better Auth, Sequenzy automatically:

1. Creates a new subscriber with their email
2. Syncs profile data (name parsed into first/last)
3. Adds to specified lists (or your workspace default lists if not specified)
4. Triggers any matching automations

### Synced Attributes

| Attribute         | Source                           |
| ----------------- | -------------------------------- |
| `email`           | User's email address             |
| `firstName`       | First word of user's name        |
| `lastName`        | Remaining words of user's name   |
| Custom attributes | Via `getCustomAttributes` option |

## List Assignment

### Use Workspace Default Lists

By default, new subscribers use the default lists you choose in workspace
settings:

```ts theme={null}
sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  // No listIds = workspace default lists
});
```

### Add to Specific Lists

To add subscribers to specific lists only:

```ts theme={null}
sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  listIds: ["list_abc123", "list_def456"],
});
```

### Add to No Lists

To create subscribers without list assignment:

```ts theme={null}
sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  listIds: [], // Empty array = no lists
});
```

## Supported Auth Methods

The plugin hooks into these Better Auth flows:

| Method         | Endpoint           | Synced |
| -------------- | ------------------ | ------ |
| Email/Password | `/sign-up/email`   | Yes    |
| Google OAuth   | `/callback/google` | Yes    |
| GitHub OAuth   | `/callback/github` | Yes    |
| Other OAuth    | `/callback/*`      | Yes    |

Both new registrations and new OAuth sign-ups are synced. Returning OAuth users (already have an account) are not re-synced.

## Using with Automations

### Welcome Sequence

Create an automation to welcome every new user:

1. Go to **Automations** → **Create New**
2. Set trigger to **Contact Added**
3. Add your welcome email sequence
4. Activate the automation

Every Better Auth signup will now receive your welcome sequence.

### Personalization

Use synced attributes in your emails:

```
Hi {{firstName}},

Welcome! We're excited to have you on board.
```

## Error Handling

The plugin is non-blocking by design. If Sequenzy is unavailable:

* Authentication succeeds normally
* User account is created
* Error is logged (if `onError` is set)

```ts theme={null}
sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  onError: (error, user) => {
    // Log to your error tracking service
    Sentry.captureException(error, {
      extra: { userEmail: user.email },
    });
  },
});
```

## Custom Attributes

Add any data you want to track:

```ts theme={null}
sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  getCustomAttributes: (user) => ({
    userId: user.id,
    hasAvatar: !!user.image,
    signupSource: "web",
    signupTimestamp: Date.now(),
  }),
});
```

These attributes are available in:

* Subscriber profiles
* Email personalization
* Segment filters
* Automation conditions

## Tagging Signups

Tag new subscribers for organization or automation triggers:

```ts theme={null}
sequenzy({
  apiKey: process.env.SEQUENZY_API_KEY!,
  tags: ["signup", "better-auth", "web-app"],
});
```

You can then:

* Filter subscribers by tag
* Trigger automations on tag assignment
* Create segments based on tags

## FAQ

<AccordionGroup>
  <Accordion title="Does this sync existing users?">
    No, only new sign-ups after adding the plugin are synced. Existing users need to be imported separately via the API or CSV upload.
  </Accordion>

  <Accordion title="What if a user already exists in Sequenzy?">
    The plugin uses Sequenzy's upsert API—existing subscribers get their
    attributes merged, not duplicated.
  </Accordion>

  <Accordion title="Can I disable automation enrollment?">
    Yes, set `enrollInSequences: false` to create subscribers without triggering
    automations.
  </Accordion>

  <Accordion title="Is the plugin blocking?">
    No. The plugin runs asynchronously after authentication succeeds. Auth flow is
    never delayed or blocked.
  </Accordion>

  <Accordion title="What if Sequenzy is down?">
    Authentication succeeds normally. The sync failure is logged via `onError` if
    provided.
  </Accordion>

  <Accordion title="Is this included in my plan?">
    Yes, the Better Auth integration is included at no extra cost.
  </Accordion>
</AccordionGroup>

## Source Code

The plugin is open source:

<Card title="GitHub Repository" icon="github" href="https://github.com/sequenzy/sequenzy-better-auth">
  View source, report issues, or contribute
</Card>