Adding a subscribe form

There are two ways to let people subscribe, and which one you want depends on whether you have a backend.

Start with the signup form. The API is for when you already have a backend doing something else with the address.

Option 1 — the signup form widget

Create one under Newsletter → Signup forms, then paste the snippet:

<script src="https://api.vlozi.app/newsletter/f/embed.js" data-newsletter="nlf_…"></script>

That is the whole integration. The widget renders an email field (and a name field, if you enabled one), posts the signup, and shows your success message. No API key, no backend, no CORS configuration.

Why the form id is safe to publish

The id in that snippet is a capability, not your workspace identity:

• It is random and unguessable, so nobody finds it by scanning.
• It does exactly one thing — add an address to that one list. It cannot read your subscribers, cannot tell an attacker whether an address is already on the list, and cannot unsubscribe anyone.
• It is revocable. Pause the form and the id stops working within 30 seconds, with your subscriber list untouched. Then mint a new one.

Your workspace id is not a secret and never appears here. Nothing about the request tells Vlozi which workspace to write to — the form id does, server-side.

Placing it precisely

The one-liner drops the form wherever the <script> tag sits. To control the position, put a container anywhere on the page and the script anywhere else:

<div data-vlozi-newsletter="nlf_…"></div>
 
<script src="https://api.vlozi.app/newsletter/f/embed.js"></script>

One script tag can render several containers on the same page.

Styling

Set Accent colour and Button label on the form. Everything the widget renders is prefixed .vlzn, so you can restyle it from your own stylesheet:

.vlzn-i { border-radius: 8px; }        /* inputs */
.vlzn-b { border-radius: 8px; }        /* button */
.vlzn-msg { font-style: italic; }      /* success / error message */

Settings that matter

What stops abuse

Because this endpoint is anonymous, it is bounded on several axes at once:

• Every widget signup requires email confirmation, regardless of your workspace's opt-in setting. Someone submitting a stranger's address cannot put them on your list — only that person, from their own inbox, can.
• A hidden honeypot field silently discards obvious bots. They get a normal success response and nothing is written.
• Rate limits apply per visitor per form, and per visitor per workspace.
• A per-address cooldown means repeatedly submitting the same email sends one confirmation, not many. Your form cannot be turned into a mail bomb aimed at someone else.

Option 2 — subscribing from your backend

Use this when a signup is part of something bigger — a checkout, an account creation, a CRM sync.

POST https://api.vlozi.app/newsletter/public/subscribe

Headers:

Content-Type: application/json
x-api-key: ls_your_secret_key

Create the key under Settings → API Keys, choose Secret, and grant it newsletter:subscribers.create.

The tenant is resolved from the key — you do not send it. A client-supplied x-tenant-id header is stripped at the gateway and will not be honoured.

Body:

{
  "email": "reader@example.com",
  "name": "Reader Name",
  "tags": ["website", "blog"],
  "source": "homepage"
}

Success (200):

{ "ok": true }

Rate limit (429): 10 subscribe requests per 60 seconds per IP per workspace.

Example

The browser posts to your own endpoint, which holds the secret key:

// POST /api/subscribe  — your server
export async function POST(request) {
  const { email, name, source } = await request.json();
 
  const res = await fetch("https://api.vlozi.app/newsletter/public/subscribe", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      // Secret key — server-side only. NOT NEXT_PUBLIC_*, that prefix ships it
      // to the browser.
      "x-api-key": process.env.VLOZI_API_KEY,
    },
    body: JSON.stringify({ email, name, source }),
  });
 
  return new Response(await res.text(), {
    status: res.status,
    headers: { "Content-Type": "application/json" },
  });
}

Because your endpoint faces the internet, add your own abuse controls there. Vlozi's limit is a backstop, not a substitute.

The double opt-in flow

1. Visitor submits the form
2. Vlozi creates the subscriber with status=active and confirmed_at=null
3. A confirmation email is sent from your configured sender
4. Visitor clicks Confirm → confirmed_at is set
5. They are now eligible to receive campaigns

Unconfirmed subscribers are excluded from every campaign send. The confirmation link is valid for 7 days, and they can re-request one at any time.

Unsubscribe links

Every email includes an {{ unsubscribe_url }} token that resolves to a unique, HMAC-signed link. Clicking it unsubscribes immediately.

<p style="color: #999; font-size: 12px;">
  Don't want these emails?
  <a href="{{ unsubscribe_url }}">Unsubscribe</a>
</p>