# 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. - Human page: https://mailrith.com/developers/subscribers - Markdown page: https://mailrith.com/developers/subscribers.md - Category: API Resources - Reading time: 8 min read - Last updated: 2026-07-13 - Related keywords: Subscribers API, Subscribers API developer docs, API Resources, API Resources developer docs, Mailrith developer docs, Mailrith public API, Sync Subscribers, Endpoint Overview, Upsert Request Shape, Subscriber Sync Checklist, Consent And Privacy API Boundaries, Tags API, Custom Fields API, Import and Export Jobs ## 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 List and upsert subscribers with practical guidance for identity, tags, fields, syncs, and imports. ## 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. 1. Confirm that the workspace API key belongs to the workspace where you want Mailrith to create or update the subscriber record. 2. For one subscriber, call `POST /v1/subscribers` with the email address and any profile fields your source system knows. 3. 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. 4. Include tags or custom-field values in the same request when your source system already has them. 5. Read the API response and store the returned subscriber ID if the external system needs a Mailrith reference for the same person. 6. For many subscribers, use [Import and Export Jobs](https://mailrith.com/developers/jobs.md) instead of sending thousands of single upserts in a tight loop. 7. After a migration or sync, use cursor pagination to list subscribers. Compare a sample of returned subscriber records with the same subscribers in [Subscribers](https://mailrith.com/docs/subscribers.md) 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. Related OpenAPI operation groups: - Subscribers ## Upsert 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. **Upsert Example** ```bash 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. ## Related Guides - [Consent And Privacy API Boundaries](https://mailrith.com/developers/consent-and-lawful-basis.md): The public Subscriber API stores profile and list-management data, not separate consent-evidence fields. This guide explains the API boundary, safe Subscriber upserts, imports, webhooks, and when to use Mailrith-hosted GDPR consent workflows. - [Tags API](https://mailrith.com/developers/tags.md): The tags API gives integrations a lightweight way to manage subscriber labels. This guide explains when to use tags, when to use custom fields instead, how to list or create tags, and how to name tags so workspace users understand each label. - [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. - [Import and Export Jobs](https://mailrith.com/developers/jobs.md): Imports and exports are asynchronous in `v1`. This guide explains when to queue a job, how import mappings and export filters work at a high level, how to use idempotency, and how to monitor final job status without confusing queued work with completed work.