---
title: "Signup forms and the public archive"
description: "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."
url: https://onesend.email/docs/forms-and-archive/
---
# 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:

```bash
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.

<a id="forms"></a>
## 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](#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" |

```bash
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}/embed` returns the embed code (see below).
- `GET /forms/{id}/submissions` lists submissions, newest first. Filter with `status`: `pending`, `confirmed`, `subscribed` (single opt-in), `already_subscribed` or `rejected` (the address bounced, complained or is blocked).
- `POST /forms/preview` returns 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 to `https://<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 with `fetch` and 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):

```js
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:

```bash
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 `website` field. 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 `allowedOrigins` set, posts whose `Origin` (or `Referer`) is another site are refused with 403 `origin_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.

<a id="double-opt-in"></a>
## Double opt-in

With `doubleOptIn` on (the default):

1. 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.
2. 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.
3. 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.
4. 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, a `form.confirmed` event is sent to your [webhooks](https://onesend.email/docs/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):

```json
{
  "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](https://onesend.email/docs/marketing/#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` |

<a id="archive"></a>
## 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.

1. 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.
2. 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.

```bash
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.
