Docs / Marketing and deliverability
Signup forms and the public archive
This guide covers hosted signup forms with double opt-in, embedding a form on your own site, the consent proof stored on each contact, and the public archive of past campaigns. Each section shows the dashboard page and the matching API. API paths are under /v1 and need an API key with Full access (full) unless noted; read-only calls also accept Read only (read) keys.
The examples assume:
export ONESEND_BASE_URL=http://localhost:3000
export ONESEND_API_KEY=os_live_…
Public pages (/f/…, /a/…) use ONESEND_PUBLIC_URL in links, so set it to the address people reach your server at.
Signup forms
In the dashboard, open Contacts → Forms and select Create form. The editor shows a live preview of the hosted page; after you save, the right column has the hosted page address, the embed code and the latest submissions.
A form has:
| Setting | Meaning |
|---|---|
name | For you. Visitors see style.title, or the name when no title is set |
fields | Email is always first and required. Each field adds a contact attribute (first_name, last_name, phone or a custom attribute) with a label, type (text, number, date, boolean, category, email), optional placeholder and required |
listIds | Lists a subscriber is added to (after they confirm, with double opt-in) |
consentText | Shown next to a required checkbox. Links can be written as [privacy policy](https://…). Changing the text increases consentVersion |
doubleOptIn | Default true. See Double opt-in |
successMessage or redirectUrl | What happens after a successful submit: a message on the hosted page, or a redirect (303) to your page |
fromName, fromEmail, replyTo | Sender of the confirmation and welcome email. fromEmail defaults to no-reply@ your first verified domain |
confirmation | Optional subject, heading, body (plain text, blank lines separate paragraphs) and buttonLabel for the confirmation email. {{ form_name }} and {{ workspace_name }} are available |
welcomeTemplateId | Optional template sent once the contact is subscribed. Contact fields ({{ first_name }}, attributes) are available |
style | title, description, buttonLabel, primary (button color), background, text, font, logoUrl. Values not set here come from the workspace brand (Settings → Workspace → Brand) unless useBrand is false |
allowedOrigins | Websites allowed to post the form, such as https://www.example.com. Empty: any site |
status | active or disabled. A disabled form shows "This form is not available" |
curl -X POST "$ONESEND_BASE_URL/v1/forms" \
-H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
-d '{
"name": "Website footer",
"listIds": ["lst_…"],
"fields": [{ "key": "first_name", "label": "First name", "type": "text" }],
"consentText": "I agree to receive the monthly newsletter. See the [privacy policy](https://acme.dev/privacy).",
"fromName": "Acme", "fromEmail": "news@news.acme.dev",
"style": { "title": "Get the Acme newsletter", "primary": "#2B4DE0" }
}'
The response includes urls.hosted (the hosted page), urls.submit and stats (submissions, confirmations, pending and confirmationRate, which is confirmed ÷ (confirmed + pending)).
Other form endpoints:
GET /forms,GET /forms/{id},PATCH /forms/{id},DELETE /forms/{id}. Deleting a form keeps the contacts who signed up; pending confirmation links stop working.GET /forms/{id}/embedreturns the embed code (see below).GET /forms/{id}/submissionslists submissions, newest first. Filter withstatus:pending,confirmed,subscribed(single opt-in),already_subscribedorrejected(the address bounced, complained or is blocked).POST /forms/previewreturns the hosted page HTML for unsaved settings, for previews.
The hosted page
GET /f/{formId} is a server-rendered page. It needs no JavaScript, uses labels and native validation, marks errors with aria-invalid and a summary with role="alert", and fits small screens. It is served with a strict content security policy (no scripts, inline styles only, form posts only to this server and to your redirect address) and X-Robots-Tag: noindex.
Embedding a form
GET /v1/forms/{id}/embed returns:
html: a plain HTML<form>that posts tohttps://<your server>/f/{formId}/submit, with a small scoped style block. It works without JavaScript: after submitting, the visitor sees the result on the hosted page (or your redirect address).script:<script src="https://<your server>/f/{formId}/embed.js" data-form="{formId}" async></script>. Add it after the form to submit withfetchand show the success message in place. If the script fails to load, the form still posts normally.htmlWithScript: both together.
To post from your own code, send JSON to POST /f/{formId}/submit (CORS allows the form's allowedOrigins, or any origin when the list is empty):
await fetch('https://<your server>/f/frm_…/submit', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ email: 'ada@example.com', first_name: 'Ada', consent: true }),
});
// → { "ok": true, "status": "pending", "message": "…", "redirectUrl": null }
Invalid input returns 400 invalid_submission with error.details keyed by field (email, consent, or an attribute key).
From a server, use POST /v1/forms/{id}/submissions with an API key (Sending only is enough). Pass the subscriber's ip and userAgent to include them in the consent proof:
curl -X POST "$ONESEND_BASE_URL/v1/forms/frm_…/submissions" \
-H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
-d '{"email":"ada@example.com","firstName":"Ada","consent":true,"ip":"203.0.113.9","userAgent":"Mozilla/5.0 …"}'
Abuse protection
Forms do not use a third-party CAPTCHA. Instead:
- Honeypot. Every form has a hidden
websitefield. People never see it; a submission that fills it is dropped. - Time to submit. The hosted page carries a signed render time (
_t); the embed script sends the time since the page loaded (_e). Submissions faster than 2 seconds are dropped. - Rate limits. 20 posts per client IP, then one every 30 seconds; 600 per form, then 10 a minute; and at most 3 confirmation emails per address and form, then one every 20 minutes. A re-submit within 5 minutes of the last confirmation email does not send another.
- Allowed origins. With
allowedOriginsset, posts whoseOrigin(orReferer) is another site are refused with 403origin_not_allowed.
Dropped submissions get the normal success response, so bots do not learn what was detected. For the same reason, every accepted submission gets the same response whether the address is new, already subscribed or blocked.
Behind a reverse proxy, set ONESEND_TRUST_PROXY so rate limits use the visitor's address instead of the proxy's.
Double opt-in
With doubleOptIn on (the default):
- A new address is saved as a contact with status
pending. Pending contacts never receive campaigns and are not added to the form's lists yet. - OneSend sends a confirmation email through your routing policy, like other transactional email, without open or click tracking. Its link is
/f/confirm/{token}: a signed token that works only for confirming that submission and expires after 7 days. - The link opens a page with a Confirm subscription button. Confirming takes a button press (a POST), so link scanners that open every link in an email do not confirm on the visitor's behalf.
- On confirmation the contact becomes
subscribed, the values from the form are saved, the contact is added to the form's lists, the consent proof is stored, aform.confirmedevent is sent to your webhooks, and the welcome email is sent if the form has one.
Rules:
- Re-submitting is safe: one pending submission per form and address is reused (the latest values win), and the confirmation email is not re-sent within 5 minutes.
- A subscribed contact is not asked to confirm again; the form's lists are added.
- A contact who unsubscribed can subscribe again only by confirming, even on a form with
doubleOptIn: false. Confirming removes the unsubscribe suppression. - Addresses that hard-bounced, complained or were blocked by hand are never mailed (submission status
rejected). - Confirming twice shows "You are already subscribed" and changes nothing.
With doubleOptIn: false, new addresses are subscribed and added to the lists at once.
Consent proof
Each contact who subscribes through a form stores consent (returned by GET /v1/contacts/{id} and shown on the contact page):
{
"method": "double_opt_in",
"formId": "frm_…",
"submissionId": "fsub_…",
"submittedAt": "2026-11-08T10:12:03.000Z",
"confirmedAt": "2026-11-08T10:14:40.000Z",
"ipHash": "5f0c…",
"userAgent": "Mozilla/5.0 …",
"consentText": "I agree to receive the monthly newsletter. …",
"consentVersion": 2
}
method is double_opt_in, single_opt_in, or import for imported contacts (see CSV import). The IP address is stored only as a keyed hash: it can show that two submissions came from the same address, not which address it was.
Webhook events
| Event | When | data |
|---|---|---|
form.submitted | A submission was accepted (not for dropped or rejected ones) | formId, submissionId, status (pending, subscribed or already_subscribed), contactId |
form.confirmed | A double opt-in subscription was confirmed | formId, submissionId, contactId, listIds |
Public archive
The archive is a public page that lists the campaigns you choose, with one page per campaign. It is off until you turn it on.
- In Settings → Archive, turn on Publish the archive. Optionally set a title, a description, a signup form to show at the top of every archive page, and a custom domain.
- In a campaign's Settings step, or on its report, turn on Show in public archive. The page goes live once the campaign has started sending.
curl -X PATCH "$ONESEND_BASE_URL/v1/archive/settings" \
-H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
-d '{"enabled":true,"title":"Acme newsletter","formId":"frm_…"}'
curl -X PUT "$ONESEND_BASE_URL/v1/campaigns/cmp_…/archive" \
-H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
-d '{"showInArchive":true}'
The campaign gets a slug from its subject the first time it is shown; pass slug to choose one (lowercase letters, digits and hyphens). GET /v1/campaigns/{id}/archive returns showInArchive, slug, url and published (true when the page is live).
Public URLs
| URL | Content |
|---|---|
/a/{workspace} | Index of published campaigns, newest first |
/a/{workspace}/{slug} | One campaign |
/a/{workspace}/{slug}.md | The campaign as Markdown with a short front matter block (title, date, url), for feed readers and AI tools |
/a/{workspace}.md | The index as Markdown |
/a/{workspace}/feed.xml | RSS 2.0 feed of the latest 50 campaigns |
/sitemap.xml | Every published archive page on this server (or, on a custom archive domain, that workspace's pages) |
/robots.txt | Allows /a/, /docs and /openapi.json, disallows everything else, and links the sitemap |
{workspace} is the workspace ID shown under Settings → Workspace.
What an archive copy contains
Archive pages are rendered without any recipient:
- Contact fields are empty, so template defaults apply (
{{ first_name | default:"there" }}shows "there"). - Unsubscribe and preference links are removed. The view-in-browser link points to the archive page.
- No open pixel, click tracking or UTM parameters are added.
- Scripts, forms, frames and event handler attributes from the campaign HTML are removed, and the page is served with a sandboxing content security policy (no scripts, no cookies; form posts only to this server).
Each campaign page has a <title>, a meta description (the preview text, or the start of the email), a canonical link, Open Graph tags (og:title, og:description, og:url, og:type, og:site_name, and og:image from the brand logo) and links to the RSS feed and the Markdown version.
Indexing
Archive pages are the only pages meant for search engines: they are sent with X-Robots-Tag: index, follow. Every other response (the dashboard, the API, form pages, tracking and unsubscribe pages) is sent with X-Robots-Tag: noindex, nofollow, except the API reference at /docs.
Custom archive domain
Set domain (for example news.example.com) to use your own host in archive links and canonical URLs. It must be on a domain this workspace has verified under Domains, and its DNS must point at this server (a CNAME to your OneSend host), with TLS handled by your reverse proxy. The archive keeps its paths on that host: https://news.example.com/a/{workspace}/{slug}. Archive pages answer only on ONESEND_PUBLIC_URL's host and the workspace's own archive domain.
SDK, CLI and MCP
The TypeScript SDK has onesend.forms (list, create, get, update, delete, embed, submissions, submit) and onesend.archive (settings, update, campaign, setCampaign). The MCP server has list_forms and create_form; create_form returns the hosted page address and the embed code.