diff --git a/apps/docs/docs.json b/apps/docs/docs.json index ae7f2c7..b15fc35 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -39,7 +39,12 @@ }, { "group": "Guides", - "pages": ["guides/webhooks", "guides/double-opt-in", "guides/use-with-react-email"] + "pages": [ + "guides/webhooks", + "guides/double-opt-in", + "guides/campaign-personalization", + "guides/use-with-react-email" + ] } ] }, diff --git a/apps/docs/guides/campaign-personalization.mdx b/apps/docs/guides/campaign-personalization.mdx new file mode 100644 index 0000000..a7cd12e --- /dev/null +++ b/apps/docs/guides/campaign-personalization.mdx @@ -0,0 +1,166 @@ +--- +title: Campaign Personalization +description: "Use contact variables to personalize campaign content for each recipient" +--- + +## Overview + +Campaign personalization lets you pull values from your contacts into campaign emails. You can use built-in fields like `{{firstName}}` and `{{email}}`, plus custom variables such as `{{company}}`, `{{plan}}`, or `{{registrationCode}}`. + +## How it works + + + + Add the custom variable names you want to use, such as `company` or `plan`, + on the contact book. + + + Save the matching values on each contact through the dashboard, CSV import, + or API. + + + Select that contact book in your campaign and insert variables into the + subject or email content. + + + useSend replaces each variable with that contact's value when the campaign + is rendered. + + + +## Available variables + +These built-in variables are always available in campaigns: + +- `{{email}}` +- `{{firstName}}` +- `{{lastName}}` + +Custom variables come from the contact book's variable list. + + + Custom variables must be added to the contact book before they can be used in + a campaign. Variable names can only contain letters, numbers, and underscores. + + +## Set up personalization in the dashboard + +### 1. Add variables to your contact book + +1. Go to [Contacts](https://app.usesend.com/contacts) +2. Create a new contact book or open an existing one +3. Add your variables as a comma-separated list, for example: + +```text +company, plan, registrationCode +``` + +### 2. Add values to your contacts + +For each contact, save values for the variables you registered. + +For example, a contact might look like this: + +```json +{ + "email": "jane@example.com", + "firstName": "Jane", + "lastName": "Doe", + "properties": { + "company": "Acme", + "plan": "Pro", + "registrationCode": "WELCOME-2026" + } +} +``` + +You can add these values: + +- manually from the contact editor +- through CSV import using matching column names +- through the Contacts API using `properties` + +### 3. Insert variables in your campaign + +1. Open or create a campaign +2. Select the contact book that contains your variables +3. Insert variables into the subject or email body + +Examples: + +```text +Subject: Welcome to {{company}} + +Hi {{firstName}}, + +You're currently on the {{plan}} plan. +Your registration code is {{registrationCode}}. +``` + +If a contact book is selected, the campaign editor will suggest the available +variables automatically. + +## Fallback values + +If a variable might be empty, you can provide a fallback value: + +```text +Hi {{firstName,fallback=there}}, +``` + +This renders `there` when `firstName` is empty. + +## Using the API + +### Create a contact book with variables + +```bash +curl -X POST https://app.usesend.com/api/v1/contactBooks \ + -H "Authorization: Bearer us_your_api_key" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Customers", + "variables": ["company", "plan", "registrationCode"] + }' +``` + +### Create a contact with variable values + +```bash +curl -X POST https://app.usesend.com/api/v1/contactBooks/{contactBookId}/contacts \ + -H "Authorization: Bearer us_your_api_key" \ + -H "Content-Type: application/json" \ + -d '{ + "email": "jane@example.com", + "firstName": "Jane", + "properties": { + "company": "Acme", + "plan": "Pro", + "registrationCode": "WELCOME-2026" + } + }' +``` + +### Create a campaign that uses variables + +```bash +curl -X POST https://app.usesend.com/api/v1/campaigns \ + -H "Authorization: Bearer us_your_api_key" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Welcome campaign", + "from": "Acme ", + "subject": "Welcome to {{company}}", + "contactBookId": "{contactBookId}", + "html": "

Hi {{firstName,fallback=there}}, your plan is {{plan}}.

" + }' +``` + +## Best practices + +| Best practice | Why it helps | +| -------------------------------------------- | -------------------------------------------------------------------- | +| Register variables before importing contacts | Keeps CSV columns and API properties aligned with the contact book | +| Keep variable names simple | Makes templates easier to read and maintain | +| Use fallbacks for optional data | Prevents awkward empty spaces when a contact is missing a value | +| Test with a small segment first | Helps you verify rendered output before sending to a larger audience | diff --git a/apps/docs/guides/double-opt-in.mdx b/apps/docs/guides/double-opt-in.mdx index 1173eb7..e673cce 100644 --- a/apps/docs/guides/double-opt-in.mdx +++ b/apps/docs/guides/double-opt-in.mdx @@ -131,7 +131,7 @@ The following variables can be used in the confirmation email template: | `{{lastName}}` | The contact's last name | - The `{{doubleOptInUrl}}` variable is **required** in the email template. The + The `{{ doubleOptInUrl }}` variable is **required** in the email template. The confirmation email cannot be saved without it. This ensures every confirmation email contains a working verification link. @@ -147,25 +147,9 @@ Each resend generates a new confirmation link with a fresh 7-day expiration wind ## Best practices - - - Double opt-in requires at least one verified domain to send confirmation - emails. Make sure to [verify your domain](https://app.usesend.com/domains) - before enabling double opt-in. - - - The confirmation email should be clear and concise. Include a prominent - confirmation button and a brief explanation of what the subscriber is - confirming. - - - Use a from address that your subscribers will recognize, such as - `newsletter@yourdomain.com` or `hello@yourdomain.com`. This reduces the - chance of the confirmation email being marked as spam. - - - Regularly check for contacts stuck in Pending status. If many contacts - aren't confirming, consider improving your confirmation email or resending - confirmations. - - +| Best practice | Why it helps | +| ---------------------------------- | -------------------------------------------------------------------------------- | +| Set up a verified domain first | Double opt-in emails need a verified domain before they can be sent | +| Keep the confirmation email simple | Makes it easier for subscribers to understand and complete the confirmation step | +| Use a recognizable from address | Reduces the chance of the confirmation email being ignored or marked as spam | +| Monitor pending contacts | Helps you spot low confirmation rates and improve your signup flow |