Custom Fields API
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.
Manage the Workspace Field Schema
Custom fields are structured fields that a workspace stores on subscriber records. Examples include plan, company, location, signup source, renewal date, lead score, and account owner.
Custom fields are different from tags because each custom field has a type. The type tells Mailrith forms, subscriber profiles, and segments how to display, collect, and compare the field value.
Create or map custom fields before you write subscriber values to those fields. This order helps prevent migrations from writing important subscriber data to the wrong field or losing useful type information.
- List existing custom fields with
GET /v1/custom-fields. - Map each external field to an existing Mailrith field ID when both fields have the same meaning.
- Create new custom fields before you import subscriber values that require a typed field.
- Use controlled choices for plan, region, lifecycle stage, or any other field where spelling must stay consistent.
- Write subscriber field values only after the field definition exists.
- Ask a Mailrith user to review the field in Custom Fields, Forms, and Segments. The field is ready for live targeting when the label, type, choices, and usage match the intended subscriber data.
- Use text fields for free-form values, such as company name.
- Use select fields when subscribers or users must choose from controlled answers, such as plan or region.
- Use date or number fields when segments need to compare dates or numbers.
- Keep labels plain and user-friendly because workspace users see those labels in the app.
- Do not delete fields until you know which forms, segments, imports, or subscriber records depend on those fields.
Endpoint Overview
GET /v1/custom-fields lists the workspace schema. Use the API response to map external field names to Mailrith field IDs before you start a sync or migration.
POST /v1/custom-fields creates a new field definition. Item endpoints let you inspect, update, or delete one field when your integration owns that schema.
Use care when you update custom fields. Renaming a field is usually safe when users understand the new label. Changing a field meaning or type can confuse forms, segments, and reports that already use the field.
/v1/custom-fields List custom fields
Returns custom fields in the authenticated workspace.
View Schema /v1/custom-fields Create a custom field
Creates a workspace-scoped custom-field definition.
View Schema /v1/custom-fields/{custom_field_id} Get a custom field
Returns one custom field from the authenticated workspace.
View Schema /v1/custom-fields/{custom_field_id} Update a custom field
Updates a custom-field definition for the authenticated workspace.
View Schema /v1/custom-fields/{custom_field_id} Delete a custom field
Deletes a custom-field definition from the authenticated workspace.
View Schemacurl "https://api.mailrith.com/v1/custom-fields?limit=50" \
-H "Authorization: Bearer mrk_example_secret_key"curl -X POST https://api.mailrith.com/v1/custom-fields \
-H "Authorization: Bearer mrk_example_secret_key" \
-H "Content-Type: application/json" \
-d '{
"label": "Plan",
"type": "Single Select",
"settings": {
"options": ["Free", "Pro", "Enterprise"]
}
}'Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.