# Subscribers API



> The subscribers resource is the core subscriber write surface in `v1`. This guide explains when to list, when to upsert, 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

- Category: API Resources

- Reading time: 8 min read



## 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 touch this resource first because website forms, CRMs, payment systems, migration scripts, and internal tools all need to create or update people.

The public subscribers API is built around listing and upserting. Listing lets you read subscribers in pages. Upserting lets you send one subscriber by email and let Mailrith decide whether to create a new record or update an existing one.

Use upserts whenever the source system may send the same person more than once. That is common with signup forms, CRM updates, imports, and retrying background jobs.

1. Confirm the workspace API key points to the workspace where you want the subscriber record to be created or updated.
2. For one subscriber, call `POST /v1/subscribers` with the email address and any known profile fields.
3. Add tags or custom-field values in the same request when your source system already knows them.
4. Read the response and store the returned subscriber ID if the external system needs a Mailrith reference.
5. 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.
6. After a migration or sync, use cursor pagination to list subscribers back and compare a sample against [Subscribers](https://mailrith.com/docs/subscribers.md) in the app.

- Use 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 list endpoints for sync, audits, reporting, and pre-migration checks.
- Keep subscriber API calls server-side because they may include private subscriber data.
- Read the 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 it when another system needs to mirror Mailrith subscriber state, build reports, or confirm a migration result.

`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 workspace is selected by the API key. This avoids accidentally writing subscribers into the wrong workspace.

Related OpenAPI operation groups:
- Subscribers

## Upsert Request Shape

The public API uses snake_case field names. Keep your request body close to the OpenAPI schema rather than copying internal app names or database column names.

At minimum, send an email address. Add optional values only when your source system knows them. If a field is unknown, leave it out instead of sending empty placeholder data.

`new_tags` is useful when the source system owns labels that may not exist in Mailrith yet. Existing tag IDs are useful 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 is more than a single request. Decide how the integration will handle duplicates, missing emails, tag mapping, retry behavior, and partial failures before turning it on for real subscriber data.

When importing a large subscriber list, use the async import job API instead of sending thousands of single upsert calls from a tight loop. Use single upserts for event-like changes such as one signup, one CRM update, or one checkout.

- Normalize emails in your source system before sending them, but let Mailrith's response be the final saved result.
- Skip records with no valid email address instead of creating incomplete subscribers.
- Map source tags and fields before a migration so you do not create confusing duplicate labels.
- Use cursor pagination when reading subscribers back for verification.
- Avoid logging full subscriber payloads in systems where personal data does not belong.



## Related Guides

- [Tags API](https://mailrith.com/developers/tags.md): The tags surface gives integrations a lightweight way to manage subscriber labels. This guide explains when tags are the right choice, when custom fields are better, how to list or create tags, and how to name tags so real workspace users understand them.

- [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, create definitions, and avoid breaking forms or reports with unsafe schema changes.

- [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 results without confusing queued work with completed work.