Subscribers API
The subscribers resource is the core write surface in `v1`. Use it to sync contacts into a workspace and keep external systems aligned with Mailrith audience state.
4 min read
Sync subscribers
The subscribers surface gives you the two primitives most integrations need first: list the current workspace audience and create or upsert by email.
Upserts are stable for form submissions, CRM syncs, and migration scripts where the caller may see the same contact more than once.
Endpoints
List subscribers for read-side syncs, then use POST /v1/subscribers to create or update a contact, attach existing tags, create new tags, and store custom-field values in one request.
/v1/subscribers List subscribers
Returns subscribers in the authenticated workspace, ordered 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 existing subscriber is updated instead.
View schemaUpsert request shape
Use snake_case field names on the public surface. The request supports both existing tag ids and new tag names so external callers can avoid a preflight create-tag step when needed.
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"
}
}'Need help shipping an integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.
Related guides
Read the tag catalog and create tags programmatically for targeting and automation.
Read the typed custom-field schema available to the authenticated workspace.
Create async subscriber import and export jobs and poll them to completion.