Subscribers API
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.
Sync Subscribers
Subscribers are the people in a Mailrith workspace subscriber list. Most integrations use this resource first because website forms, CRMs, payment systems, migration scripts, and internal tools often need to create or update subscribers.
The public subscribers API focuses on listing and upserting. Listing lets you read subscribers in pages. Upserting lets you send one subscriber email address and have Mailrith either create a new subscriber record or update the existing record for that email address.
Use upserts when the source system may send the same person more than once. Duplicate sends are common with signup forms, CRM updates, imports, and retried background jobs.
- Confirm that the workspace API key belongs to the workspace where you want Mailrith to create or update the subscriber record.
- For one subscriber, call
POST /v1/subscriberswith the email address and any profile fields your source system knows. - When your source system collected permission, keep that proof in the source system or map it to clear tags and ordinary Subscriber fields your workspace can use.
- Include tags or custom-field values in the same request when your source system already has them.
- Read the API response and store the returned subscriber ID if the external system needs a Mailrith reference for the same person.
- For many subscribers, use Import and Export Jobs instead of sending thousands of single upserts in a tight loop.
- After a migration or sync, use cursor pagination to list subscribers. Compare a sample of returned subscriber records with the same subscribers in Subscribers in the app.
- Use the email address as the stable identity for an upsert request.
- Send known profile fields, tag IDs, new tag names, sequence enrollment choices, and custom-field values in the same request when your integration has them.
- Use tags or custom fields only when your integration has a clear source-of-truth mapping for those values.
- Use list endpoints for sync, audits, reporting, and pre-migration checks.
- Keep subscriber API calls server-side because the requests and responses may include private subscriber data.
- Read the API response after an upsert and store Mailrith's returned subscriber ID if your system needs to refer to the same person later.
Endpoint Overview
GET /v1/subscribers returns subscribers in pages. Use this endpoint when another system needs to mirror Mailrith subscriber state, build reports, or confirm that a migration created or updated the expected subscriber records.
POST /v1/subscribers creates or updates one subscriber. The request can also attach existing tags, create new tags, write custom-field values, and connect the subscriber to other Mailrith subscriber features supported by the contract.
Do not send a workspace ID. The API key selects the workspace. This prevents the request from accidentally writing subscribers into the wrong workspace.
/v1/subscribers List subscribers
Returns subscribers in the authenticated workspace, sorted from newest to oldest.
View Schema /v1/subscribers Create or upsert a subscriber
Creates a new subscriber when the email does not exist in the workspace. If the email already exists, the API updates the existing subscriber unless create_only is true.
View Schema /v1/subscribers/{subscriber_id} Update a subscriber
Updates profile fields, status, custom fields, tags, or sequence assignments for one subscriber. Fields omitted from the request stay unchanged. Blank optional custom field values also leave saved values unchanged, and filled-in invalid values are rejected.
View Schema /v1/subscribers/{subscriber_id}/sequences/{sequence_id} Add a subscriber to a sequence
Adds the selected subscriber to the selected sequence. If the subscriber is already in the sequence, the API returns the subscriber unchanged.
View Schema /v1/subscribers/{subscriber_id}/sequences/{sequence_id} Remove a subscriber from a sequence
Removes the selected subscriber from the selected sequence. If the subscriber is not in the sequence, the API returns the subscriber unchanged.
View Schema /v1/subscribers/{subscriber_id}/tags/{tag_id} Remove a tag from a subscriber
Removes the selected tag from a subscriber. If the subscriber does not have the tag, the API returns the subscriber unchanged.
View SchemaUpsert Request Shape
The public API uses snake_case field names. Match your request body to the OpenAPI schema instead of copying internal app names or database column names.
At minimum, send an email address. Add optional fields only when your source system knows the field values. If a field value is unknown, leave the field out instead of sending an empty placeholder.
If an existing Subscriber already has saved details, sending an empty or null optional value does not clear that detail. Leave unknown values out, or send a filled-in value when your source system should replace what Mailrith has saved.
For permission-aware syncs, send only fields listed in the OpenAPI schema. Keep consent proof in the source system or use Mailrith-hosted consent workflows when you want Mailrith to capture proof.
Use new_tags when the source system owns labels that may not exist in Mailrith yet. Use existing tag IDs when the integration has already mapped source labels to Mailrith tags.
curl -X POST https://api.mailrith.com/v1/subscribers \
-H "Authorization: Bearer mrk_example_secret_key" \
-H "Content-Type: application/json" \
-d '{
"email": "ada@example.com",
"name": "Ada Lovelace",
"status": "Active",
"new_tags": ["Website Signup"],
"custom_fields": {
"company": "Analytical Engines"
}
}'Subscriber Sync Checklist
A reliable subscriber sync needs more than one request. Before you turn on the sync for real subscriber data, decide how the integration will handle duplicate subscribers, missing email addresses, tag mapping, retry behavior, and partial failures.
When you import a large subscriber list, use the async import job API instead of sending thousands of single upsert calls in a tight loop. Use single upserts for event-like changes, such as one signup, one CRM update, or one checkout.
- Normalize email addresses in your source system before sending them, but treat Mailrith's response as the final saved subscriber record.
- Skip source records with no valid email address instead of creating incomplete subscribers.
- Map source tags and fields before a migration so the migration does not create confusing duplicate labels.
- Use cursor pagination when you read subscribers back for verification.
- Avoid logging full subscriber payloads in systems where personal data does not belong.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.