Collect topic signups (Preview)

Use a topic form to let readers subscribe without giving your website an API key. Submitting a form requests a confirmation email. The address becomes a contact and a topic subscriber only after the reader confirms. Unconfirmed requests do not count toward your contacts usage.

Prepare the topic

Create an opt-in topic and choose its default sender. The sender must be ready to send email. A topic in a namespace creates its confirmed contacts in that namespace.

Create the form

Open the topic in the dashboard and create a signup form. Add the exact HTTPS origins of the sites that will embed it, such as https://example.com. An origin has no path or trailing slash. Choose the message readers see before confirming and the success message they see after confirming. An optional HTTPS redirect takes confirmed readers to your own page.

The forms API manages the same configuration: create, get, list, update, and remove a form. Keep the API key on your server. The form's public key is safe to include in your website.

Share or embed

Copy the hosted URL to share the form directly. The hosted page uses your sending brand and link domain. Hosted URLs on Samva's canonical origin keep working when you activate a custom link domain. To collect signups on your own site, copy the dashboard's embed snippet and add that site's origin to the form. The form includes an invisible field that automated submissions must leave empty.

The snippet submits the public form key and email address to POST /v1/public/topics/{topicId}/subscribe?formKey={formKey}. The URL and JSON body must name the same form key. A successful request returns confirmation_sent; it does not mean the reader has subscribed. Requests from other origins, filled honeypot fields, and excessive submissions are refused. A rate limit tells the caller how long to wait before trying again.

Confirm and send

The reader opens the confirmation link and confirms their email. Samva records double opt-in consent and subscribes the contact to this topic with source form. The subscription event includes the signup page and referrer when supplied. Confirming twice does not create another contact or repeat the subscription event.

Send a campaign under the same topic to reach confirmed subscribers. A pending signup is absent from the campaign audience. Unsubscribe and preference links let readers leave this topic independently of other topics.