docs: add campaign personalization guide (#374)

* docs: add campaign personalization guide

* docs: show best practices without accordions

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"
+            ]
           }
         ]
       },

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
+
+<Steps>
+  <Step title="Register variables on the contact book">
+    Add the custom variable names you want to use, such as `company` or `plan`,
+    on the contact book.
+  </Step>
+  <Step title="Store values on each contact">
+    Save the matching values on each contact through the dashboard, CSV import,
+    or API.
+  </Step>
+  <Step title="Use variables in your campaign">
+    Select that contact book in your campaign and insert variables into the
+    subject or email content.
+  </Step>
+  <Step title="Send the campaign">
+    useSend replaces each variable with that contact's value when the campaign
+    is rendered.
+  </Step>
+</Steps>
+
+## Available variables
+
+These built-in variables are always available in campaigns:
+
+- `{{email}}`
+- `{{firstName}}`
+- `{{lastName}}`
+
+Custom variables come from the contact book's variable list.
+
+<Warning>
+  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.
+</Warning>
+
+## 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 <hello@acme.com>",
+    "subject": "Welcome to {{company}}",
+    "contactBookId": "{contactBookId}",
+    "html": "<p>Hi {{firstName,fallback=there}}, your plan is {{plan}}.</p>"
+  }'
+```
+
+## 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 |

apps/docs/guides/double-opt-in.mdx

@@ -147,25 +147,9 @@ Each resend generates a new confirmation link with a fresh 7-day expiration wind
 
 ## Best practices
 
-<AccordionGroup>
+| Best practice                      | Why it helps                                                                     |
-  <Accordion title="Set up a verified domain first">
+| ---------------------------------- | -------------------------------------------------------------------------------- |
-    Double opt-in requires at least one verified domain to send confirmation
+| Set up a verified domain first     | Double opt-in emails need a verified domain before they can be sent              |
-    emails. Make sure to [verify your domain](https://app.usesend.com/domains)
+| Keep the confirmation email simple | Makes it easier for subscribers to understand and complete the confirmation step |
-    before enabling double opt-in.
+| Use a recognizable from address    | Reduces the chance of the confirmation email being ignored or marked as spam     |
-  </Accordion>
+| Monitor pending contacts           | Helps you spot low confirmation rates and improve your signup flow               |
-  <Accordion title="Keep the confirmation email simple">
-    The confirmation email should be clear and concise. Include a prominent
-    confirmation button and a brief explanation of what the subscriber is
-    confirming.
-  </Accordion>
-  <Accordion title="Use a recognizable from address">
-    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.
-  </Accordion>
-  <Accordion title="Monitor pending contacts">
-    Regularly check for contacts stuck in Pending status. If many contacts
-    aren't confirming, consider improving your confirmation email or resending
-    confirmations.
-  </Accordion>
-</AccordionGroup>