# Add a newsletter signup form to any site

> Add a newsletter signup form to any website using a plain HTML snippet, a CORS-enabled JSON endpoint, or the server-side SDK.

**You can add a newsletter signup form to any website by embedding the plain HTML snippet provided in your email settings, submitting JSON directly to your hosted form URL, or using the server-side SDK.** thelastapi gives every project a dedicated signup endpoint with open CORS headers, automatic honeypot bot filtering, and optional double opt-in. Because browser submissions post straight to the hosted URL, you can collect subscribers on static pages, client-side web apps, or backend servers without installing external plugins or managing form infrastructure.

This guide walks through configuring marketing email for your project, retrieving your form endpoint, embedding the form, handling JSON submissions, and managing subscriber consent.

## How the signup form works

Every project that enables marketing email receives a dedicated hosted signup form endpoint. You can inspect this configuration in the console under **Email ▸ Settings ▸ Signup form**, or retrieve it via the API and CLI:

- **`form.url`**: The direct HTTPS endpoint that accepts both standard form submissions and asynchronous JSON payloads.
- **`form.embed_html`**: A prebuilt, dependency-free HTML snippet ready to paste directly into any website template or CMS.

The endpoint supports three primary integration patterns:

1. **Static HTML Embed**: A pure HTML `<form>` that requires no JavaScript, CSS frameworks, or external assets.
2. **Client-Side JSON Post**: An asynchronous `fetch` request sent directly from your custom frontend, made possible because the endpoint has cross-origin resource sharing (CORS) enabled.
3. **Server-Side Integration**: Direct contact creation using `@vibiz/app` on an authenticated backend during user signup or purchase events.

## How to configure email and retrieve your form URL

Marketing email is isolated from transactional messages. While transactional alerts send from your project mailbox, marketing broadcasts send from `hello@news.<slug>.vibiz.app` by default. This separation protects your transactional sending reputation so a bounce from a marketing broadcast cannot pause password resets.

To set up the email resource from your terminal:

```bash
vibiz add email
vibiz email setup
```

The sending address verifies within minutes (`status: setting_up → ready`). Before sending marketing emails or collecting subscribers for distribution, you must configure your sender name, reply-to address, and physical postal address to comply with CAN-SPAM regulations:

```bash
vibiz email settings set \
  --from-name "Acme Updates" \
  --reply-to "hello@acme.com" \
  --postal-address "1 Main St, Springfield, IL 62701, USA"
```

Only project owners can set the physical postal address, and marketing campaigns cannot be sent without it. You can review your form details, sender settings, and sending limits over HTTP:

```bash
curl https://thelastapi.dev/v1/projects/prj_123/email/marketing \
  -H "Authorization: Bearer $VIBIZ_API_KEY"
```

The JSON response returns your configuration, including `form.url` and `form.embed_html`. The full reference for mailbox configuration and marketing parameters is available in the [Email docs](https://thelastapi.dev/docs/email).

## Embedding the plain HTML snippet on any site

If you run a static site, documentation portal, or simple landing page, the fastest way to add a form is with plain HTML. Run `vibiz email settings` to print your project's snippet, or copy `form.embed_html`.

The generated snippet contains standard HTML inputs and an invisible honeypot field:

```html
<!-- Replace <form url> with the form.url value from your email settings -->
<form action="<form url>" method="POST">
  <label for="email">Email address</label>
  <input type="email" id="email" name="email" required placeholder="ana@example.com" />
  
  <label for="first_name">First name</label>
  <input type="text" id="first_name" name="first_name" placeholder="Ana" />

  <!-- Hidden honeypot field stops automated bots silently -->
  <input type="text" name="_hp" style="display:none" tabindex="-1" autocomplete="off" />

  <button type="submit">Subscribe</button>
</form>
```

When a visitor submits this form, their browser submits a `POST` request directly to your hosted `form.url`. The submission does not require external tracking scripts, keeping your pages lightweight and compliant with strict content security policies.

## Submitting JSON from a custom frontend form

If your application uses a client-side framework such as React, Vue, or Svelte, or if you want to handle the submission asynchronously without reloading the page, send JSON to `form.url`.

The endpoint accepts a JSON object with `email` and optional `first_name` fields. Because CORS is open on the form endpoint, you can call it directly from the visitor's browser:

```html
<form id="newsletter-form">
  <input type="email" id="subscriber-email" required placeholder="ana@example.com" />
  <input type="text" id="subscriber-name" placeholder="Ana" />
  <button type="submit" id="submit-btn">Subscribe</button>
  <div id="form-message"></div>
</form>

<script>
  const form = document.getElementById('newsletter-form');
  const message = document.getElementById('form-message');

  form.addEventListener('submit', async (event) => {
    event.preventDefault();
    message.textContent = 'Subscribing...';

    const payload = {
      email: document.getElementById('subscriber-email').value,
      first_name: document.getElementById('subscriber-name').value
    };

    try {
      // POST directly to your project's form.url
      const response = await fetch('<form url>', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload)
      });

      if (response.ok) {
        message.textContent = 'Thank you for subscribing!';
        form.reset();
      } else {
        const errorData = await response.json();
        message.textContent = errorData.message || 'Unable to subscribe. Please verify your address.';
      }
    } catch (err) {
      message.textContent = 'Submission failed. Please try again later.';
    }
  });
</script>
```

The response returned by the endpoint remains identical whether the submitted address is brand new or already subscribed. This design ensures third parties cannot scrape your endpoint to determine whether an email address exists on your list.

## Capturing signups server-side with the SDK

For server-rendered web applications or workflows where users opt into email updates during account registration, you can record subscriptions on your backend using `@vibiz/app`.

Server-side calls run under your secret `VIBIZ_APP_KEY`. This approach allows you to record specific subscription lists, custom properties, and consent audit trails simultaneously:

```ts
import { vibiz } from '@vibiz/app';

export async function handleUserSignup(email: string, firstName: string) {
  await vibiz.contacts.upsert({
    email,
    first_name: firstName,
    lists: ['Newsletter'],
    properties: {
      source: 'checkout_modal',
      signup_date: new Date().toISOString(),
    },
    consent: {
      method: 'form',
      text: 'Send me product announcements and weekly updates',
    },
  });
}
```

When running in local development, an app using a development key answers successfully without storing data, ensuring test submissions never pollute your production contacts. For teams migrating existing audiences from other platforms, read our guide on how to [import a newsletter list from CSV, safely](https://thelastapi.dev/blog/import-newsletter-list-csv).

## Comparing form implementation approaches

| Approach | Environment | Best used for | Bot and validation behavior |
| --- | --- | --- | --- |
| **HTML Snippet** | Static HTML / CMS | Landing pages, blogs, static documentation | Uses standard POST, honeypot inputs, and browser redirects |
| **JSON Post** | Browser JavaScript | Custom interactive components, modal dialogs | Open CORS headers, custom inline success states |
| **Server SDK** | Backend Node.js | User registration flows, post-purchase opt-ins | Full property mapping, immediate list categorization |

## Bot handling, double opt-in, and suppression rules

When a user signs up through a form, the platform applies several automated protections before a contact record is stored.

### Spam and error filtering

- **Bot detection**: Submissions that populate the hidden honeypot field, submit faster than humanly possible, or exceed request thresholds are discarded silently without warning the bot.
- **Address validation**: Submissions containing typos (e.g., `user@gmial.com`), temporary disposable inboxes, or domains lacking active MX records are rejected with an `invalid_request` error.

### Double opt-in configuration

By default, contacts submitting a form receive the `subscribed` status immediately without receiving a confirmation email. If you prefer to verify email ownership before adding subscribers to campaigns, turn on double opt-in:

```bash
vibiz email settings set --double-opt-in on
```

With double opt-in enabled:
1. Submissions enter a `pending` state.
2. The platform automatically sends a "Confirm your subscription" email to the recipient at no extra charge.
3. The subscriber's status changes to `subscribed` once they click the confirmation link inside that message.

### Unsubscribes and suppression

If a contact previously unsubscribed from your communications and later submits the signup form again, the system does not quietly resubscribe them. Instead, it places them into the `pending` state and sends a confirmation email. Their status only reverts to `subscribed` if they explicitly click the link.

Addresses that previously recorded hard bounces or registered spam complaints remain blocked on the suppression list (`suppressed: true`), even if they submit a form or are re-imported.

## Managing subscribers and sending your first broadcast

Once visitors sign up, you can inspect and manage your audience directly from the CLI or API:

```bash
# List all active subscribers
vibiz email contacts --status subscribed

# Filter by a specific list
vibiz email contacts --list "Newsletter"
```

When you are ready to reach your audience, you can draft marketing emails using Markdown, set fallback tags, and schedule your sends. To learn how to structure lists, configure automated sequences, and monitor broadcast analytics, explore our guide on choosing a [newsletter tool for a small business: contacts, lists and broadcasts](https://thelastapi.dev/blog/newsletter-tool-small-business). If you also need to manage account verification messages, see how to [send transactional email from your app without touching DNS](https://thelastapi.dev/blog/send-transactional-email-no-dns).

## Next step

Add the form snippet or JSON submission handler to your website, run `vibiz email settings` to verify your postal address, and submit a test entry to confirm that new subscribers appear under `vibiz email contacts`.

## Frequently asked questions

### Does the signup form require visitors to solve a CAPTCHA puzzle?

No, automated bots are stopped silently using hidden honeypot fields, submission timing analysis, and rate limits without subjecting human visitors to CAPTCHA challenges.

### How much does it cost to collect subscribers and send broadcasts?

Collecting contacts, hosting forms, managing lists, and sending double opt-in confirmation emails are completely free. Sending broadcasts to your subscribers costs $0.001 per recipient ($1 per 1,000 emails sent), billed against your account balance.

### Can the signup form send contacts from my own custom domain?

Yes, once you add a mailbox for your domain and verify its DNS records, you can update your marketing settings with `--from-domain yourcompany.com` to send marketing broadcasts from `news.yourcompany.com` while continuing to use your hosted form endpoint.

---

Published 2026-11-15 · https://thelastapi.dev/blog/newsletter-signup-form-any-site
