Consent And Privacy API Boundaries
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.
Know What The API Stores
The public Subscriber API stores Subscriber profile and list-management data. It does not accept separate consent-evidence or lawful-basis evidence fields on Subscriber upserts.
Use the generated OpenAPI document as the source of truth for accepted request fields. If a consent or lawful-basis field is not in the schema, do not send it.
Keep consent proof in the system that collected it unless the proof comes from a Mailrith-hosted form, landing page, GDPR consent page, double opt-in confirmation, or Mailrith support workflow.
- Use Mailrith forms, landing pages, and the GDPR Consent setting when you want Mailrith to capture consent choices.
- Use GDPR consent tags to segment Subscribers who gave email or advertising consent in Mailrith.
- Use Subscriber status, tags, and custom fields for normal sync state from other systems.
- Use import jobs for CSV migrations, bulk CRM syncs, and legacy ESP imports.
For the user-facing workflow around GDPR consent Tags and the consent page, see GDPR FAQ.
Single Subscriber Upserts
POST /v1/subscribers can create or update one Subscriber. This is the best API shape for one-person writes where your system is processing one person at a time.
At minimum, send email. Add profile fields, tags, sequences, custom fields, status, and subscription date only when your source system knows those values. Treat the API response as the saved record and keep Mailrith's returned Subscriber ID if your system needs to refer to the same person later.
When an upsert updates an existing Subscriber, empty or null optional values leave saved Subscriber details unchanged. This includes name, status, country, subscribed_on, and custom_fields. Send a filled-in value only when your system should replace the saved value. New Subscribers need a valid email, while Custom Fields can remain blank.
- Confirm the workspace API key belongs to the workspace where the Subscriber should live.
- Send
emailand any known Subscriber profile fields. - Use
statusonly when the source system is authoritative for the Subscriber's list state. - Use
existing_tag_ids,new_tags,sequence_ids, andcustom_fieldswhen your integration owns that mapping. - Do not send consent-evidence fields that are not listed in the OpenAPI schema.
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": {
"cf_company": "Analytical Engines"
}
}'Webhook Consent Responsibilities
Webhook subscriptions can send Subscriber and event data to systems outside Mailrith. Treat each webhook destination as a connected provider that must have a clear owner, purpose, retention rule, and privacy-review path.
Do not use a webhook receiver to create a second shadow Subscriber database unless that system has the same consent, unsubscribe, restriction, objection, and erasure handling that your Mailrith workspace relies on. If the destination only needs to trigger a workflow, store the Mailrith event ID and Subscriber ID instead of copying every personal field.
Current public webhooks can send Subscriber created, updated, and status-changed events. They do not currently send separate public events for consent withdrawal, privacy request completion, objection, restriction, or erasure.
If a Subscriber asks for access, deletion, restriction, objection, or withdrawal, include webhook destinations in your downstream review. Your integration owner still needs to know what the receiving system stores and how to delete, suppress, or export it.
- Subscribe only to event patterns the destination truly needs.
- Verify signatures before storing or acting on webhook payloads.
- Minimize receiver logs. Avoid storing full payloads when the event ID, Subscriber ID, and action result are enough.
- Keep webhook destination owners and retention notes in your integration inventory.
- Process Subscriber status and profile changes from current webhook events before downstream systems send or track the Subscriber again.
For webhook setup, signing, and duplicate-delivery handling, see Webhook Subscriptions.
Import Job Mappings
API import jobs use CSV text plus mappings. Map the columns that identify the Subscriber, then optionally map country, Subscriber status, and custom fields.
When an import row updates an existing Subscriber, blank mapped custom-field cells leave saved custom-field values unchanged. New Subscribers can leave Custom Fields blank.
Keep your source-list review in your own migration or CRM process before you queue the import.
When you have consent proof for a Subscriber in another system, keep that proof in the source system or migrate it into tags and ordinary Subscriber fields your workspace can use.
- Upload or generate CSV text with stable headers.
- Map Email, Name, Country, Subscriber Status, and custom fields as needed.
- Add tags or sequences only when every imported Subscriber should receive them.
- Store Mailrith's returned job ID and poll the job status until it reaches a final state.
curl -X POST https://api.mailrith.com/v1/jobs/subscriber-imports \
-H "Authorization: Bearer mrk_example_secret_key" \
-H "Idempotency-Key: import-2026-04-11" \
-H "Content-Type: application/json" \
-d '{
"csv_text": "Email,Name,Country,Subscriber Status\nada@example.com,Ada Lovelace,DE,Active",
"mappings": [
{ "csv_column": "Email", "field": { "type": "email" } },
{ "csv_column": "Name", "field": { "type": "name" } },
{ "csv_column": "Country", "field": { "type": "country" } },
{ "csv_column": "Subscriber Status", "field": { "type": "subscriber-status" } }
],
"new_tag_name": "Website Signup"
}'Accepted Subscriber Fields
Use the generated OpenAPI document as the exact contract. The notes below explain the common Subscriber fields in normal integrations.
email is the identity field for Subscriber upserts.
name, status, country, subscribed_on, existing_tag_ids, new_tags, sequence_ids, and custom_fields are the main optional write fields.
country can be sent as a country name or country code. Mailrith returns the saved two-letter country code.
Empty or null optional values in an update mean no change for that saved field. This includes profile fields such as name, status, country, and subscribed_on, plus custom_fields. Send a non-empty value when your integration should replace a saved value.
create_only returns a conflict instead of updating an existing Subscriber with the same email address.
Consent-evidence fields such as lawful basis, consent text, collection time, source URL, IP address, and user agent are not accepted by the public Subscriber API.
- Do not send fields that are not in the OpenAPI schema.
- Do not use tags as proof unless your team has a clear tagging policy and source records outside Mailrith.
- Do not overwrite Subscriber status from a source system unless that system is allowed to control sending eligibility.
- Do not log full request bodies in integration logs unless you have a clear retention and access policy for personal data.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.