Build and embed signup forms that automatically subscribe contacts to your mailing lists

Forms capture leads directly from your website or landing page. When someone submits a form, they are added to your contacts as subscribed and linked to the configured segment.

Authentication

Management endpoints require an API key or active session (Authorization: Bearer msk_...). The public submit endpoint requires no authentication. Base URL: https://api.misar.io/mail.

Endpoints

Method	Path	Auth	Description
`GET`	`/v1/forms`	API key / session	List forms
`POST`	`/v1/forms`	API key / session	Create form
`GET`	`/v1/forms/:id`	API key / session	Get form + embed code
`PATCH`	`/v1/forms/:id`	API key / session	Update form
`DELETE`	`/v1/forms/:id`	API key / session	Delete form
`GET`	`/v1/forms/:id/submissions`	API key / session	List submissions
`POST`	`/api/public/forms/:id/submit`	None	Submit a form (public)

List forms

GET/mail/v1/forms

List forms with optional filtering and pagination.

Query parameters

pageintegerquerydefault: 1

Page number.

limitintegerquerydefault: 20

Results per page (max 100).

statusstringquery

Filter by status: active or inactive.

curl "https://api.misar.io/mail/v1/forms?status=active" \
  -H "Authorization: Bearer msk_..."

Create a form

POST/mail/v1/forms

Create a new signup form.

Request body

namestringbodyrequired

Internal name.

fieldsarraybodyrequired

Form field definitions.

segment_idstringbody

Segment to add subscribers to.

redirect_urlstringbody

URL to redirect to after successful submission.

settingsobjectbody

Visual and behaviour settings.

Response fields

successboolean

true when the form was created.

dataobject

The created form, including id, name, status, segment_id, redirect_url, fields, settings, submission_count, created_at, and updated_at.

curl -X POST https://api.misar.io/mail/v1/forms \
  -H "Authorization: Bearer msk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter signup — homepage",
    "segment_id": "seg_01hvxyz",
    "redirect_url": "https://yoursite.com/thank-you",
    "fields": [
      { "name": "email", "type": "email", "label": "Email address", "required": true },
      { "name": "firstName", "type": "text", "label": "First name", "required": false }
    ],
    "settings": {
      "submit_label": "Subscribe",
      "success_message": "Thank you for subscribing!"
    }
  }'

{
  "success": true,
  "data": {
    "id": "frm_01hvabc",
    "name": "Newsletter signup — homepage",
    "status": "active",
    "segment_id": "seg_01hvxyz",
    "redirect_url": "https://yoursite.com/thank-you",
    "fields": [...],
    "settings": {...},
    "submission_count": 0,
    "created_at": "2026-05-27T10:00:00Z",
    "updated_at": "2026-05-27T10:00:00Z"
  }
}

Get a form

GET/mail/v1/forms/:id

Returns the full form object including the embed_code field ready to paste into your site.

Path parameters

idstringpathrequired

ID of the form to retrieve.

<div id="misar-form-frm_01hvabc"></div>
<script src="https://mail.misar.io/embed/form.js"
        data-form-id="frm_01hvabc"
        data-container="misar-form-frm_01hvabc"
        integrity="sha384-{FORM_EMBED_SRI_HASH}"
        crossorigin="anonymous"
        async></script>

<iframe
  src="https://mail.misar.io/embed/forms/frm_01hvabc"
  width="100%"
  height="400"
  frameborder="0"
></iframe>

Replace {FORM_EMBED_SRI_HASH} with the current hash from your form's embed code in the MisarMail dashboard. The hash is regenerated whenever the embed script is updated. Using Subresource Integrity ensures your page is protected against CDN-level script tampering.

Update a form

PATCH/mail/v1/forms/:id

Send only the fields you want to change. Updating fields replaces the full fields array.

Path parameters

idstringpathrequired

ID of the form to update.

curl -X PATCH https://api.misar.io/mail/v1/forms/frm_01hvabc \
  -H "Authorization: Bearer msk_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter signup — footer" }'

Delete a form

DELETE/mail/v1/forms/:id

Delete a form. Existing submissions are preserved.

Path parameters

idstringpathrequired

ID of the form to delete.

Response fields

successboolean

true when the form was deleted.

{ "success": true }

List submissions

GET/mail/v1/forms/:id/submissions

List the submissions for a form.

Path parameters

idstringpathrequired

ID of the form.

Query parameters

pageintegerquerydefault: 1

Page number.

limitintegerquerydefault: 20

Results per page (max 100).

Response fields

successboolean

true when the request succeeded.

dataobject

Contains submissions (each with id, contact_id, email, fields, submitted_at, ip_address) and pagination metadata.

curl "https://api.misar.io/mail/v1/forms/frm_01hvabc/submissions?limit=50" \
  -H "Authorization: Bearer msk_..."

{
  "success": true,
  "data": {
    "submissions": [
      {
        "id": "sub_01hvdef",
        "contact_id": "con_01hvghi",
        "email": "[email protected]",
        "fields": { "firstName": "Alex" },
        "submitted_at": "2026-05-26T14:22:00Z",
        "ip_address": "203.0.113.5"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 312,
      "total_pages": 7
    }
  }
}

Public form submit

POST/mail/api/public/forms/:id/submit

No authentication required. This endpoint is called by the embed script or your own frontend. It creates or updates a contact and links them to the segment configured on the form.

Path parameters

idstringpathrequired

ID of the form being submitted.

Request body

emailstringbodyrequired

Contact email address.

firstNamestringbody

Contact's first name.

lastNamestringbody

Contact's last name.

customFieldsobjectbody

Key-value pairs for custom contact fields.

Response fields

successboolean

true when the submission was recorded.

dataobject

Contains contact_id and status.

curl -X POST https://api.misar.io/mail/api/public/forms/frm_01hvabc/submit \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Alex",
    "customFields": { "company": "Acme Inc" }
  }'

{
  "success": true,
  "data": {
    "contact_id": "con_01hvghi",
    "status": "subscribed"
  }
}

If the email already exists, the contact record is updated with any new field values. The contact's status is set to subscribed unless they are currently unsubscribed, in which case the submission is recorded but the status is not changed.

Your plan includes a limit on the number of active forms. Attempting to activate a form beyond your plan limit returns a 402 error. Check your plan on the billing page.