# 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. - Human page: https://mailrith.com/developers/consent-and-lawful-basis - Markdown page: https://mailrith.com/developers/consent-and-lawful-basis.md - Category: API Concepts - Reading time: 9 min read - Last updated: 2026-06-13 - Related keywords: Consent And Privacy API Boundaries, Consent And Privacy API Boundaries developer docs, API Concepts, API Concepts developer docs, Mailrith developer docs, Mailrith public API, Know What The API Stores, Single Subscriber Upserts, Webhook Consent Responsibilities, Import Job Mappings, Accepted Subscriber Fields, Subscribers API, Import and Export Jobs, API Reference ## 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 Understand which Subscriber privacy fields the public API accepts and when to use Mailrith-hosted consent workflows instead. ## 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](https://mailrith.com/docs/gdpr-faq.md). ## 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 still need a valid `email` and values for required custom fields. 1. Confirm the workspace API key belongs to the workspace where the Subscriber should live. 2. Send `email` and any known Subscriber profile fields. 3. Use `status` only when the source system is authoritative for the Subscriber's list state. 4. Use `existing_tag_ids`, `new_tags`, `sequence_ids`, and `custom_fields` when your integration owns that mapping. 5. Do not send consent-evidence fields that are not listed in the OpenAPI schema. **Upsert Subscriber** ```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": { "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](https://mailrith.com/developers/webhook-subscriptions.md). ## 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 still need values for required custom fields. 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. 1. Upload or generate CSV text with stable headers. 2. Map Email, Name, Country, Subscriber Status, and custom fields as needed. 3. Add tags or sequences only when every imported Subscriber should receive them. 4. Store Mailrith's returned job ID and poll the job status until it reaches a final state. **Import With Country And Status** ```bash 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. ## Related Guides - [Subscribers API](https://mailrith.com/developers/subscribers.md): 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. - [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. - [API Reference](https://mailrith.com/developers/api-reference.md): The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use the API reference to find exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.