Forms

Create a signup form

Create a new signup form, including its confirmation sender and welcome email if you send them. After creation, the embed snippet at /api/forms/{id}/submit (HTML) or /api/forms/{id}/embed.js (JavaScript widget) can be used on third-party sites. Request keys are snake_case; the older camelCase keys are still accepted. Requires the form:write scope.

post/v1/forms

Request

  • Base URL: https://smtpfa.st/api
  • URL: https://smtpfa.st/api/v1/forms
  • Auth: HTTP bearer

Request body

namestring required
fieldsstring[]

email is always included.

button_textstring
button_colorstring
success_messagestring
double_opt_inboolean
redirect_urlstring nullable

Must start with http:// or https://.

captcha_enabledboolean

Needs turnstile_site_key and turnstile_secret_key.

captcha_provider'turnstile'
turnstile_site_keystring nullable
turnstile_secret_keystring nullable

Write-only. Returned forms expose turnstile_secret_configured instead.

block_disposable_emailsboolean
activeboolean
confirmation_email_fromstring nullable

Sender of the double opt-in confirmation email. The platform address is used when this is unset or its domain is not verified.

welcome_email_enabledboolean

Send a welcome email to each new contact from this form.

welcome_email_fromstring nullable

Sender of the welcome email. Its domain must be verified, or the welcome email is skipped.

welcome_email_subjectstring nullable
welcome_email_markdownstring nullable

Welcome email body as Markdown.

Example request

{
  "name": "Newsletter signup",
  "fields": [
    "email",
    "first_name"
  ],
  "button_text": "Subscribe",
  "button_color": "#10b981",
  "success_message": "Thanks for subscribing!",
  "double_opt_in": true,
  "captcha_provider": "turnstile",
  "block_disposable_emails": true,
  "active": true,
  "confirmation_email_from": "Acme <hello@acme.com>"
}

Response

Form created

objectstring required
idstring required
namestring required
fieldsstring[] required
button_textstring required
button_colorstring required
success_messagestring required
double_opt_inboolean required
redirect_urlstring nullable
captcha_enabledboolean required
captcha_provider'turnstile' required
turnstile_site_keystring nullable
turnstile_secret_configuredboolean required
block_disposable_emailsboolean required
activeboolean required
confirmation_email_fromstring nullable

Sender of the double opt-in confirmation email. Create, retrieve and update return it; list items leave it out.

welcome_email_enabledboolean

Create, retrieve and update return it; list items leave it out.

welcome_email_fromstring nullable

Create, retrieve and update return it; list items leave it out.

welcome_email_subjectstring nullable

Create, retrieve and update return it; list items leave it out.

welcome_email_markdownstring nullable

Create, retrieve and update return it; list items leave it out.

pending_confirmations_countinteger

Signups waiting on their confirmation click. List items leave it out.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "object": "signup_form",
  "id": "clx_form123",
  "name": "Newsletter signup",
  "fields": [
    "email",
    "first_name"
  ],
  "button_text": "Subscribe",
  "button_color": "#10b981",
  "success_message": "Thanks for subscribing!",
  "double_opt_in": true,
  "captcha_provider": "turnstile",
  "block_disposable_emails": true,
  "active": true,
  "confirmation_email_from": "Acme <hello@acme.com>"
}

Changes

No recorded changes to this operation across all 1 revision of this API.