Signup Forms & Double Opt-In

Overview

A signup form is the public, embeddable front door to a contact list. Drop it on any website and visitors can subscribe; EuroMail handles the confirmation email, consent record, unsubscribe links, and suppression checks for you. Every form belongs to exactly one list.

For the full endpoint reference, see the Signup Forms API reference.

Create a form

Each contact list has one form, configured via the dashboard or the API:

curl -X POST https://api.euromail.dev/v1/contact-lists/{list_id}/form \
  -H "X-EuroMail-Api-Key: em_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blog Newsletter",
    "double_optin": true,
    "redirect_url": "https://yoursite.com/thanks"
  }'

• double_optin. When true, subscribers must click a confirmation link before they are added as subscribed. Keep this on for marketing mail.
• redirect_url. Where the subscriber lands after submitting (or after confirming).

Embedding the form

Each form is served from a public, slug-based URL and ships an embeddable JavaScript snippet. Add it to any page. The embed is loaded cross-origin, so it works on any domain:

<script src="https://api.euromail.dev/subscribe/your-form-slug/embed.js" defer></script>

The hosted form is also reachable directly at https://api.euromail.dev/subscribe/your-form-slug if you prefer to link to it rather than embed it.

Styling the embed

The embed renders into a container you control, so your own CSS applies. Wrap it in a styled element and target the form's fields from your stylesheet:

<div class="newsletter-signup">
  <script src="https://api.euromail.dev/subscribe/your-form-slug/embed.js" defer></script>
</div>

.newsletter-signup input[type="email"] { /* your styles */ }
.newsletter-signup button { /* your styles */ }

The double opt-in flow

With double_optin enabled, a subscription proceeds in four steps:

1. Submit. The visitor enters their email in the embedded form.
2. Pending. EuroMail creates the contact with status pending and sends a confirmation email containing a unique link (/confirm/{token}).
3. Confirm. The visitor clicks the link. The contact becomes subscribed and a timestamped consent record is stored.
4. Welcome. If the list has a welcome email configured, it goes out now.

This flow is what makes EuroMail signup forms GDPR-compliant out of the box: you hold proof of explicit, logged consent for every subscriber. See GDPR Tooling.

The confirmation and unsubscribe pages can be served from your own tracking/vanity domain (e.g. https://news.yoursite.com/confirm/...) so the whole flow stays on your brand.

Unsubscribe handling

Every email sent to a list includes a one-click unsubscribe link (/unsubscribe/{token}) and the List-Unsubscribe headers mailbox providers expect. An unsubscribe sets the contact to unsubscribed and adds them to the suppression list, so they are excluded from future sends automatically. You never have to scrub lists by hand.

Toggling a form on and off

Disable a form without deleting it (e.g. to pause signups during a migration):

curl -X POST https://api.euromail.dev/v1/contact-lists/{list_id}/form/toggle \
  -H "X-EuroMail-Api-Key: em_live_your_key_here"

While disabled, the embed and hosted page stop accepting new submissions.

Checklist for a compliant signup

• Keep double_optin on for any marketing list.
• Link your privacy policy near the form.
• Use a verified sending domain so the confirmation email lands in the inbox.
• Let EuroMail manage unsubscribes. Never re-add someone who opted out.