Forms

A signup form adds the people who submit it as contacts and subscribes them to lists. Stamp0 hosts the form page; you can link to it, embed it in an iframe, or post to it from your own HTML or JavaScript.

Create a formCopy Anchor Link

curl https://api.stamp0.com/forms \
  -H "Authorization: Bearer $STAMP0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter",
    "fields": [
      { "name": "email", "label": "Email", "type": "email", "required": true },
      { "name": "first_name", "label": "First name", "type": "text" },
      { "name": "role", "label": "Role", "type": "text" }
    ],
    "list_ids": ["lst_…"],
    "double_opt_in": true,
    "success_message": "Check your inbox to confirm."
  }'

• fields (up to 30) must include a required email field. A field's name is email, first_name, last_name or a property key; its type is email, text, number, checkbox or date.
• double_opt_in is on by default: new signups stay pending on the form's lists until they click the confirmation email. It needs at least one list and a default_from in the marketing settings.
• After a signup the page shows success_message, or redirects to redirect_url (https).
• PATCH /forms/:id with status: "disabled" stops accepting signups.

The response carries hosted_url (the page), action_url (where submissions go) and embed snippets. Both URLs are https://api.stamp0.com/f/frm_….

Put it on your siteCopy Anchor Link

What a signup doesCopy Anchor Link

A submission creates the contact (source form) or finds the existing one, and subscribes it to list_ids: subscribed at once, or pending with a confirmation email when double opt-in is on. Confirming also clears an earlier global unsubscribe, because it is fresh consent.

Only the fields the form declares are read, coerced to the property's type. A form only fills values a contact does not have yet: it never overwrites stored names or properties, because anyone can submit anyone's address. New contacts count toward the plan's contact limit.

Spam protectionCopy Anchor Link

spam_protection has three settings:

• honeypot (on by default): a hidden field bots fill in; such submissions are dropped silently. Keep it in your own HTML (embed.html includes it).
• turnstile (off by default): requires a Cloudflare Turnstile check. It works on the hosted page and the iframe, which render the widget for you.
• max_per_ip_per_hour (default 20): signups from one IP address per hour.

The double opt-in email goes out through your SES like any other email and shows in your email log. It has no unsubscribe link: it is the request to subscribe.

Reference: Forms.