Signup Forms

Create embeddable signup forms to capture subscribers directly from your website or landing pages. Forms are linked to audiences and automatically add new subscribers when submitted.

Create a Form

Define a form with its fields, linked audience, and optional double opt-in setting.

POST /v1/forms

create-form.ts

const form = await client.forms.create({
  name: 'Newsletter Signup',
  audienceId: 'audience_xxxxx',
  fields: [
    { name: 'email', type: 'email', required: true },
    { name: 'firstName', type: 'text', required: false },
    { name: 'lastName', type: 'text', required: false },
  ],
  doubleOptIn: true,
  redirectUrl: 'https://yoursite.com/thanks',
});

console.log(form.id);       // form_xxxxx
console.log(form.embedUrl); // https://forms.veilmail.xyz/form_xxxxx

Parameters

Field	Type	Description
name	string	Display name for the form
audienceId	string	Audience to add subscribers to
fields	array	Form fields with `name`, `type`, and `required`
doubleOptIn	boolean	Send confirmation email before subscribing (default: false)
redirectUrl	string	URL to redirect to after successful submission

List Forms

GET /v1/forms

list-forms.ts

const { data } = await client.forms.list();

for (const form of data) {
  console.log(`${form.name} — ${form.submissionCount} submissions`);
}

Get a Form

GET /v1/forms/:id

get-form.ts

const form = await client.forms.get('form_xxxxx');
console.log(form.fields);
console.log(form.embedUrl);

Update a Form

PUT /v1/forms/:id

update-form.ts

const form = await client.forms.update('form_xxxxx', {
  name: 'Updated Newsletter Signup',
  doubleOptIn: false,
  fields: [
    { name: 'email', type: 'email', required: true },
    { name: 'firstName', type: 'text', required: true },
  ],
});

Delete a Form

DELETE /v1/forms/:id

delete-form.ts

await client.forms.delete('form_xxxxx');

Embedding Forms

Each form has an embed URL that you can use to embed the form on your website. You can use an iframe or the Veil Mail JavaScript embed snippet.

Iframe Embed

embed-iframe.html

<!-- Simple iframe embed -->
<iframe
  src="https://forms.veilmail.xyz/form_xxxxx"
  width="100%"
  height="400"
  frameborder="0"
  style="border: none;"
></iframe>

JavaScript Embed

embed-js.html

<!-- Veil Mail form embed -->
<div id="veilmail-form" data-form-id="form_xxxxx"></div>
<script src="https://js.veilmail.xyz/forms.js" async></script>

Field Types

Type	Description
`email`	Email address field with validation
`text`	Single-line text input
`select`	Dropdown with predefined options
`checkbox`	Boolean checkbox (e.g., consent)

Requires the form:read scope for read operations and form:write scope for mutations.