---
title: "Create or upsert a subscriber"
method: POST
path: "/v1/subscribers"
tags: ["Subscribers"]
---

# Create or upsert a subscriber

`POST /v1/subscribers`

## Request

- Base URL: `https://api.mailrith.com`
- URL: `https://api.mailrith.com/v1/subscribers`
- Auth: HTTP bearer

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.

## Headers

- `Idempotency-Key` string

## Request body

- SubscriberUpsertRequest
  - `email` string, email, required
  - `name` string
  - `status` 'Active' | 'Unconfirmed' | 'Unsubscribed' | 'Complained' | 'Bounced' | 'Blocked'
  - `country` string, nullable: Two-letter country code or country name. Mailrith stores Subscriber country as a two-letter country code.
  - `subscribed_on` string: Subscriber-local subscription date in YYYY-MM-DD format.
  - `create_only` boolean: When true, Mailrith returns a 409 conflict instead of updating an existing subscriber with the same email.
  - `custom_fields` object: Custom field values keyed by custom field ID. For Multi Select fields, send an array of option names or a comma-separated string. Blank optional values leave saved values unchanged when updating an existing subscriber, and filled-in invalid values are rejected.
  - `consent_evidence` ConsentEvidence: Compact evidence required when the public API makes a Subscriber Active. Keep raw consent text, IP addresses, and user-agent data in your evidence system; Mailrith stores only this version, reference, URL, and optional SHA-256 digest.
    - `lawful_basis` string, required
    - `consent_text_version` string, nullable
    - `collected_at` string, required: When the consent evidence was collected, as ISO 8601 with an explicit UTC offset. This must not be later than Mailrith's server time. Do not treat a workspace-local clock as UTC; use the evidence record's confirmed timestamp.
    - `source_url` string, uri, nullable
    - `evidence_reference` string, required
    - `technical_evidence_hash` string, nullable

## Response `200`

Existing subscriber was updated

- object
  - `data` Subscriber, required
    - `self` string, required: Stable relative Public API path for retrieving this resource.
    - `id` string, required
    - `email` string, email, required
    - `name` string, required
    - `status` 'Active' | 'Unconfirmed' | 'Unsubscribed' | 'Complained' | 'Bounced' | 'Blocked', required
    - `country` string, nullable, required: Two-letter country code or country name. Mailrith stores Subscriber country as a two-letter country code.
    - `subscribed_at` string, date-time, required
    - `last_opened_at` string, date-time, nullable
    - `tags` TagSummary[], required
      - `id` string, required
      - `name` string, required
    - `sequence_ids` string[], required
    - `custom_fields` object, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `201`: Subscriber was created
- `400`: Request is invalid
- `401`: Authentication is required or invalid
- `409`: Request conflicts with an existing resource or current state

---

[API](https://skmtc.dev/mailrith/apis/mailrith-api.md) · [All operations](https://skmtc.dev/mailrith/apis/mailrith-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailrith/apis/mailrith-api/revisions/41f09536f2da?raw)