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.
On this page 10 sections
- How the signup form works
- How to configure email and retrieve your form URL
- Embedding the plain HTML snippet on any site
- Submitting JSON from a custom frontend form
- Capturing signups server-side with the SDK
- Comparing form implementation approaches
- Bot handling, double opt-in, and suppression rules
- Managing subscribers and sending your first broadcast
- Next step
- FAQ
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:
- Static HTML Embed: A pure HTML
<form>that requires no JavaScript, CSS frameworks, or external assets. - Client-Side JSON Post: An asynchronous
fetchrequest sent directly from your custom frontend, made possible because the endpoint has cross-origin resource sharing (CORS) enabled. - Server-Side Integration: Direct contact creation using
@vibiz/appon 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:
vibiz add email
vibiz email setupThe 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:
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:
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.
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:
<!-- 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:
<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:
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.
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 aninvalid_requesterror.
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:
vibiz email settings set --double-opt-in onWith double opt-in enabled:
- Submissions enter a
pendingstate. - The platform automatically sends a "Confirm your subscription" email to the recipient at no extra charge.
- The subscriber's status changes to
subscribedonce 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:
# 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. If you also need to manage account verification messages, see how to send transactional email from your app without touching 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.