Forms API
The forms API lets integrations manage capture forms outside the app. This guide explains when to list, create, update, or delete forms, how forms depend on fields and tags, and how to update live forms without breaking website signups.
Manage Forms
Forms are Mailrith capture points that collect subscriber information. You can show a form on a website, embed a form in a flow, or manage a form during a migration from another email platform.
Use the public forms API when an external builder, migration script, agency tool, or internal admin system needs to manage Mailrith forms without requiring a user to click through the app.
Forms often depend on subscriber fields, tags, and consent choices. Review those dependencies before you create or update forms programmatically.
- List existing forms before you create a replacement, especially during migration work.
- Confirm that the required tags and custom fields already exist in the workspace.
- Create or update the form using the public schema from API Reference.
- Return the saved form ID to your external system so the system can store a stable reference.
- Ask a Mailrith user to test the live form path as described in Forms. The test succeeds when the form loads, accepts a test subscriber, and applies the expected fields, tags, and consent choices.
- Do not delete an old form until you have removed the old website embed or signup link.
- List forms when an integration needs an inventory of existing capture points.
- Create forms when another system owns form setup and needs to keep Mailrith in sync.
- Update forms when the external source of truth changes form copy, fields, tags, or enabled state.
- Delete forms only after the capture point has intentionally been removed and no active website or workflow still depends on the form.
Endpoint Overview
GET /v1/forms returns forms in the authenticated workspace. Item endpoints let you inspect, update, or delete one form.
POST /v1/forms creates a form. Build the payload from the OpenAPI schema so fields, settings, and enabled state match what Mailrith expects.
If a form writes to custom fields or applies tags, make sure those fields and tags exist before you create the form. This order keeps the form usable as soon as Mailrith saves it.
/v1/forms List forms
Returns forms from the authenticated workspace.
View Schema /v1/forms Create a form
Creates a form in the authenticated workspace.
View Schema /v1/forms/{form_id} Get a form
Returns a form from the authenticated workspace.
View Schema /v1/forms/{form_id} Update a form
Updates an existing form without creating a new form.
View Schema /v1/forms/{form_id} Delete a form
Deletes a form from the authenticated workspace.
View Schema /v1/forms/{form_id}/submissions List form submissions
Returns recent real submissions for one form, including the subscriber who submitted the form. Requires both `forms:read` and `subscribers:read`.
View Schemacurl "https://api.mailrith.com/v1/forms?limit=25" \
-H "Authorization: Bearer mrk_example_secret_key"Change Forms Safely
Forms are often connected to live websites. A programmatic form update can affect new subscribers immediately, so treat every form change as user-facing even when the API call is small.
Before you delete or replace a form, confirm where the form is embedded, which tags the form applies, which custom fields the form collects, and what fallback plan you will use if the connected website has not been updated yet.
- Update a form in place when existing embeds must keep working.
- Create a new form when the new capture flow has a different purpose or consent path.
- Keep form names descriptive so users can identify each form in the Mailrith app.
- After you change a form, submit a test subscriber through the real embed or integration path.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.