# 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. - Human page: https://mailrith.com/developers/forms - Markdown page: https://mailrith.com/developers/forms.md - Category: API Resources - Reading time: 6 min read - Last updated: 2026-07-13 - Related keywords: Forms API, Forms API developer docs, API Resources, API Resources developer docs, Mailrith developer docs, Mailrith public API, Manage Forms, Endpoint Overview, Change Forms Safely, Custom Fields API, Subscribers API, Webhook Subscriptions API ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What this guide covers Manage Mailrith capture forms from external form builders, migrations, and admin tools. ## 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. 1. List existing forms before you create a replacement, especially during migration work. 2. Confirm that the required tags and custom fields already exist in the workspace. 3. Create or update the form using the public schema from [API Reference](https://mailrith.com/developers/api-reference.md). 4. Return the saved form ID to your external system so the system can store a stable reference. 5. Ask a Mailrith user to test the live form path as described in [Forms](https://mailrith.com/docs/forms.md). The test succeeds when the form loads, accepts a test subscriber, and applies the expected fields, tags, and consent choices. 6. 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. Related OpenAPI operation groups: - Forms **List Forms** ```bash curl "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. ## Related Guides - [Custom Fields API](https://mailrith.com/developers/custom-fields.md): Custom fields define the typed workspace schema shared by subscribers, forms, and segments. This guide explains how to choose field types, map external data sources, create field definitions, and avoid schema changes that break forms or reports. - [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the main way integrations write Subscriber data in `v1`. This guide explains when to list subscribers, when to upsert subscribers, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests. - [Webhook Subscriptions API](https://mailrith.com/developers/webhook-subscriptions.md): Webhook subscriptions let external systems receive Mailrith events for syncs, dashboards, fulfillment, and audit trails. This guide explains when to use webhooks, how to manage subscriptions, why you must store the signing secret immediately, and how receivers should verify and deduplicate deliveries.