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

# Add a Newsletter Signup Form

> Capture email subscribers on your site and sync to your marketing list

A newsletter signup is one of the highest-ROI additions to any site — it converts passing traffic into an audience you actually own. This guide walks through three ways to add one.

<CardGroup cols={3}>
  <Card title="Easiest" icon="wand-magic-sparkles">
    Ask the AI assistant
  </Card>

  <Card title="Visual" icon="pencil">
    Use a pre-built section
  </Card>

  <Card title="For developers" icon="code">
    Build from scratch
  </Card>
</CardGroup>

## Option 1: Ask the AI Assistant

<Steps>
  <Step title="Open the AI chat">
    Click the **AI** tab in your project.
  </Step>

  <Step title="Describe what you want">
    ```
    Add a newsletter signup form to the footer of my site. 
    Save submissions to the `newsletter_subscribers` table.
    ```
  </Step>

  <Step title="Review and refine">
    The AI adds the form, creates the table if it doesn't exist, and wires up the API handler. Ask for tweaks:

    * *"Make it a two-column layout"*
    * *"Add a consent checkbox"*
    * *"Show a thank-you message inline instead of redirecting"*
  </Step>

  <Step title="Deploy">
    Click **Deploy** to push the changes live.
  </Step>
</Steps>

## Option 2: Use a Pre-Built Section

<Steps>
  <Step title="Open the visual editor">
    Go to your project and click **Edit** on any page.
  </Step>

  <Step title="Open the Sections panel">
    In the left sidebar, click **Sections**. Scroll to the **Newsletter** category.
  </Step>

  <Step title="Drag and drop">
    Drag a newsletter section onto the page where you want it — footer, sidebar, end-of-post.
  </Step>

  <Step title="Configure the fields">
    Click the section to open the inspector. Adjust:

    * Headline and subtext
    * Field labels (Name, Email)
    * Button text
    * Thank-you message
    * Styling (background, button color)
  </Step>

  <Step title="Save and deploy">
    Click **Save**, then **Deploy**.
  </Step>
</Steps>

## Option 3: Build From Scratch

If you want full control, you can write the form component directly.

<Steps>
  <Step title="Create the database table">
    In **Database > Tables**, create `newsletter_subscribers`:

    ```sql theme={null}
    CREATE TABLE newsletter_subscribers (
      id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
      email text UNIQUE NOT NULL,
      name text,
      source text,
      subscribed_at timestamptz DEFAULT now(),
      confirmed_at timestamptz
    );
    ```
  </Step>

  <Step title="Build the form component">
    ```html theme={null}
    <form method="post" action="/api/subscribe">
      <input name="email" type="email" required placeholder="Your email" />
      <input name="name" type="text" placeholder="Your name (optional)" />
      <label>
        <input type="checkbox" name="consent" required />
        I agree to receive occasional emails.
      </label>
      <button type="submit">Subscribe</button>
    </form>
    ```
  </Step>

  <Step title="Write the API handler">
    Create an API route at `/api/subscribe` that:

    1. Validates email format
    2. Inserts into `newsletter_subscribers`
    3. Sends a confirmation email (if using double opt-in)
    4. Returns JSON (`{ success: true }` or error)
  </Step>

  <Step title="Sync to your ESP">
    Use a [workflow](/how-tos/workflows) to push new subscribers to your email service. See [Connect Mailchimp](/how-tos/connect-mailchimp) for the pattern.
  </Step>
</Steps>

## Double Opt-In

Double opt-in is strongly recommended — it boosts deliverability, filters typos, and is required in several jurisdictions (Germany, Canada).

Flow:

1. User submits form → row created with `confirmed_at = NULL`
2. Send confirmation email with a tokenized link
3. User clicks link → GET `/api/confirm?token=...` → update `confirmed_at = now()`
4. Only subscribers with `confirmed_at IS NOT NULL` count as "active"

See [Send Emails](/how-tos/send-emails) for the email-sending setup.

## GDPR-Compliant Patterns

* **Explicit consent checkbox**, not pre-checked
* **Clear privacy policy link** next to the submit button
* **Unsubscribe link** in every email you send
* **Data export and delete** path (users can request their data or deletion)

<Warning>
  Never pre-fill fields with cookies or third-party data without explicit consent. Pre-filled forms and pre-checked consent boxes are GDPR violations and drive immediate unsubscribes and spam complaints.
</Warning>

## Form Placement Best Practices

| Placement         | Intent    | Notes                                  |
| ----------------- | --------- | -------------------------------------- |
| Footer            | Low       | Always present, low friction           |
| Exit intent popup | High      | Right moment, but annoying if overused |
| End of blog post  | High      | Reader just finished your content      |
| Sidebar           | Medium    | Consistent visibility on scroll        |
| Dedicated landing | Very high | Best for paid traffic                  |

Start with the footer. Add one more placement based on where your readers actually engage.

## Incentive Options

Asking for an email without a reason is a hard sell. Offer something:

* **Lead magnet** — PDF checklist, template, mini-guide
* **Discount code** — 10% off first purchase
* **Early access** — beta features, new products
* **Content upgrade** — extended version of the blog post they just read

<Tip>
  The lead magnet should match the content context. A "Website Performance Checklist" in the footer of a design blog will outperform a generic "Subscribe to our newsletter" by 3-5x.
</Tip>

## Syncing to Your Marketing List

Raw subscribers in your database aren't enough — you need them in your email tool (Mailchimp, ConvertKit, etc.) to actually send to them. See:

* [Connect Mailchimp](/how-tos/connect-mailchimp)
* [Connect Zapier](/how-tos/connect-zapier) for other ESPs

## Verify It Worked

1. Submit the form with a test email
2. Check the `newsletter_subscribers` table — the row should be there
3. If using double opt-in, confirm the confirmation email arrives
4. Click the confirmation link — `confirmed_at` should populate
5. Check your ESP (Mailchimp, etc.) — the subscriber should appear in your audience

## Troubleshooting

<AccordionGroup>
  <Accordion title="Form submits but nothing saves">
    The API route is erroring. Open browser DevTools > Network tab, submit the form, and look at the `/api/subscribe` response. Common causes: database connection error, unique constraint violation (email already exists), validation failure.
  </Accordion>

  <Accordion title="Confirmation email isn't being sent">
    SMTP isn't configured or the sender domain isn't verified. Go to **Settings > Email** — you should see a green checkmark next to your sender domain. If not, see [Send Emails](/how-tos/send-emails) for the setup.
  </Accordion>

  <Accordion title="Duplicate subscriptions for the same email">
    Add a `UNIQUE` constraint on the `email` column if you haven't:

    ```sql theme={null}
    ALTER TABLE newsletter_subscribers ADD CONSTRAINT unique_email UNIQUE (email);
    ```

    Handle the resulting error in your API handler — treat it as a successful subscribe (user is already on the list).
  </Accordion>

  <Accordion title="Spam signups flooding the list">
    Bots are filling your form. Add a honeypot field (hidden input; real users don't fill it, bots do) or reCAPTCHA on the form. If volume is extreme, add rate limiting by IP.
  </Accordion>

  <Accordion title="Subscribers not syncing to Mailchimp/ESP">
    The sync workflow isn't running or is erroring. Go to **Workflows > Runs** and inspect recent runs. If none exist, the trigger isn't wired. If they exist but fail, check the error message — usually a bad API key or wrong audience ID.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Connect Mailchimp" icon="envelope" href="/how-tos/connect-mailchimp">
    Sync subscribers to your email marketing tool
  </Card>

  <Card title="Welcome Sequence" icon="envelope-open-text" href="/how-tos/workflow-welcome-sequence">
    Send a welcome email series to new subscribers
  </Card>
</CardGroup>