# Double opt-in and unsubscribe links: newsletter compliance basics

> Double opt-in confirms email subscribers with a verification link, while compliant unsubscribe links ensure recipients can leave in one click.

**Double opt-in requires new subscribers to click a verification link before they receive marketing campaigns, while compliant unsubscribe headers let them opt out in one click.** Together with physical postal addresses and clean suppression records, these two mechanisms keep your sending reputation healthy and satisfy anti-spam laws like CAN-SPAM, CASL, and the GDPR. When subscribers actively confirm their interest and have an effortless way to leave, bounce rates plummet, spam complaints stay negligible, and inbox providers deliver your broadcasts directly to primary inboxes.

Setting up compliant list collection and unsubscription does not require stitching together external compliance tools. Here is how double opt-in, one-click unsubscribes, and automated list sanitation work, along with the exact code to run them.

## What double opt-in does and why it matters

Single opt-in immediately marks anyone who fills out a form as active. That invites typos, bot submissions, and malicious entries into your contact records. If your newsletter sends to bad addresses, high bounce rates will damage your reputation quickly.

With double opt-in turned on, when someone submits your form, their contact state becomes `pending`. The system automatically dispatches a "Confirm your subscription" email containing a secure link. Double opt-in confirmations are completely free on the platform. The contact's status only transitions to `subscribed` once they click that link.

| Feature | Single Opt-In | Double Opt-In |
| --- | --- | --- |
| Contact status at signup | `subscribed` | `pending` |
| Confirmation email | None | Automated, free |
| Protection against bot form fills | Relies on hidden fields / rate limits | Bot submissions never confirm |
| Typo defense | Delivers bad addresses to your list | Typos cannot click confirmation links |
| Consent proof | Form log only | Verified timestamp and click confirmation |

Bot protection runs at the form layer as well. Hosted forms and endpoints stop automated scripts without revealing detection: hidden honeypot fields, rate limits, and submission speed tracking stop bots quietly, while invalid mailboxes or broken domains are rejected automatically.

To enable double opt-in across your marketing address, set the flag using the CLI:

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

Or configure it in your application dashboard under project **Email ▸ Settings**.

## How unsubscribe links protect deliverability

A legal marketing broadcast must provide recipients with an immediate way to leave. In modern email compliance, hiding your unsubscribe link or forcing subscribers to log in to an account violates standard regulations and leads users to press the "Report Spam" button instead.

Large inbox providers like Gmail and Yahoo require two distinct forms of unsubscription:

1. **RFC 8058 One-Click List-Unsubscribe Headers:** Email clients parse machine headers to place a visible "Unsubscribe" button right beside the sender name at the top of the message. Clicking it tells your server to unsubscribe the recipient in the background, without making them visit a webpage.
2. **Body Unsubscribe Links:** The rendered footer of your message must provide a direct unsubscribe link and an email preferences link signed specifically for that subscriber. 

thelastapi handles both mechanisms automatically. Every broadcast email includes standard one-click headers and appends a compliant footer featuring the business name, postal address, and personal unsubscribe links. The hosted unsubscription page asks once to verify intent, ensuring automated corporate link scanners and security crawlers do not accidentally unsubscribe your contacts.

If you write custom HTML templates instead of using the standard Markdown renderer, insert the `{{{UNSUBSCRIBE_URL}}}` merge tag wherever you place your custom link text.

For more details on aligning records and passing inbox checks, read our guide on [DKIM, SPF and DMARC deliverability](https://thelastapi.dev/blog/dkim-spf-dmarc-deliverability).

## Setting up marketing email with proper compliance

Marketing broadcasts must be separated from transactional messages like receipts and password resets. In the platform, transactional email sends from your primary app domain (`hello@<slug>.vibiz.app`), while marketing mail sends from `hello@news.<slug>.vibiz.app` (or your own custom domain, like `news.yourcompany.com`). If marketing broadcasts trigger an unexpected spike in spam complaints, transactional delivery remains unaffected.

To initialize marketing email:

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

Next, provide your sender information and physical postal address. By law, a valid physical mailing address must appear in the footer of every commercial message. Broadcasts are blocked until an owner adds this:

```bash
curl -X PATCH https://thelastapi.dev/v1/projects/prj_123/email/marketing \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "from_name": "Acme",
    "reply_to": "hello@acme.com",
    "postal_address": "1 Main St, Springfield, IL 62701, USA"
  }'
```

Without a postal address configured, pre-send broadcast reviews will throw an `invalid_request` with the code `postal_address_required`.

## Collecting contacts and handling consent

When storing subscriber records from your backend, track consent details directly. The `@vibiz/app` package manages contact lifecycle events cleanly:

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

// Add subscriber during signup
await vibiz.contacts.upsert({
  email: 'ana@example.com',
  first_name: 'Ana',
  lists: ['Newsletter'],
  properties: { plan: 'free' },
  consent: {
    method: 'app_signup',
    text: 'Send me weekly product updates',
  },
});

// Provide an in-app toggle to unsubscribe
await vibiz.contacts.unsubscribe('ana@example.com');
```

The database tracks how the contact consented (such as the form, time, IP address, user agent, and exact consent text). 

Crucially, **nobody who said no is quietly brought back.** If your application logic accidentally upserts an email that previously unsubscribed, the contact is marked as `pending` and sent a re-confirmation email. They are never resubscribed without actively confirming. Furthermore, any address that bounced or submitted a spam complaint remains permanently suppressed (`suppressed: true`), even if the contact is removed and added again later.

If you are migrating existing users, review our guide on how to [import a newsletter list from CSV safely](https://thelastapi.dev/blog/import-newsletter-list-csv).

## Pre-send broadcast reviews and suppression safeguards

Sending marketing broadcasts costs $0.001 per recipient ($1 per 1,000 sent), billed from account credits. Before any broadcast delivers, the system runs an automated audit:

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

The review verifies the following requirements:
- Sending address readiness and DNS verification.
- Sender name, valid `reply_to` address, and physical postal address.
- Email body size (Gmail clips messages over 102 KB, which hides the footer unsubscribe link).
- Missing fallback values on merge tags (for instance, using `{{{FIRST_NAME|there}}}`).
- Total broadcast cost against current credit balance.

Any errors on the review checklist will block sending with `review_failed`.

When a broadcast begins, safety controls govern message speed to protect sender reputation:
- **Stepped Delivery:** Contacts you have never emailed before are sent in batches: 2%, then 5%, then the remaining list, staggered 30 minutes apart. Contacts you have emailed previously go first at full speed.
- **Automated Pauses:** If hard bounces exceed 2.5% or spam complaints exceed 0.08%, sending halts automatically (`paused_reason: bounces | complaints`). Marketing sending for a project is blocked entirely if it exceeds a 5% bounce rate or 0.3% complaints over a 30-day window.
- **Automated List Cleanup:** Turned on by default, contacts who ignore several broadcasts over a 3-month window receive one automated message asking if they wish to stay subscribed. If they do not click within 14 days, their status moves to `dormant`, excluding them from future broadcasts.

For building applications that only send individual notifications or verification emails, see how to [send transactional email from your app without touching DNS](https://thelastapi.dev/blog/send-transactional-email-no-dns).

## Next step

Activate your marketing mail resource using `vibiz email setup`, update your postal address via `vibiz email settings set --postal-address "..."`, and enable double opt-in to keep bounce rates near zero. Explore all options in the complete [Email docs](https://thelastapi.dev/docs/email).

## Frequently asked questions

### Does a double opt-in confirmation email count against my daily limits or credits?

No. Double opt-in confirmation emails and test sends to account owners are free and do not deduct from your credits or marketing email allowance.

### What happens if an unsubscribed user submits a newsletter signup form again?

The contact is placed into a `pending` status and sent a confirmation link; they are only marked `subscribed` if they explicitly click to re-confirm.

### Why does the broadcast review check email size against a 102 KB limit?

Inbox providers like Gmail clip message bodies larger than 102 KB, which cuts off the bottom of the email and hides the required unsubscribe link and physical postal address.

### What are the bounce and complaint thresholds that pause a broadcast?

Broadcasts pause automatically if hard bounces exceed 2.5% or spam complaints exceed 0.08%, and account owners receive an immediate notification.

---

Published 2026-11-15 · https://thelastapi.dev/blog/double-opt-in-unsubscribe
