Recipients
Recipient privacy and right-to-forget operations.
/recipients/{recipient}/forget
Submit a right-to-forget request
Submits a GDPR right-to-erasure ("right to be forgotten") request for a recipient email address across the authenticated user's sending domains. MiniMailer records the request in a durable ledger and dispatches an asynchronous scrub that removes the recipient's personal data from every store while preserving a non-reversible hash for audit and re-erasure on backup restore.
The operation is idempotent: repeating it for an already-scrubbed recipient is a harmless
no-op. Because erasure runs asynchronously, a 202-style acceptance means the request is
recorded, not that scrubbing has finished. Requires the compliance:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
recipient
required
|
path | The recipient email address. |
curl -X DELETE https://api.minimailer.app/recipients/{recipient}/forget \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 202 | Right-to-forget request accepted and processing. |
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
ErrorDocument
|
| 422 |
The request document failed validation.
ValidationErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
ErrorDocument
|
/recipients/{recipient}/data
Request a recipient data export
Submits a GDPR Article 15 subject-access export for a recipient email address across the authenticated user's sending domains. The export is assembled asynchronously and delivered out of band; the acceptance response echoes the non-reversible recipient hash used to correlate the request with the completed export.
Requires the compliance:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
recipient
required
|
path | The recipient email address. |
curl -X GET https://api.minimailer.app/recipients/{recipient}/data \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 202 | Recipient data export request accepted and processing. |
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
ErrorDocument
|
| 422 |
The request document failed validation.
ValidationErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
ErrorDocument
|
/recipient-consents
Record a recipient consent
Appends a consent record for a recipient on one of your sending domains, giving you the
demonstrable proof of consent GDPR Article 7(1) requires. Capture the consent_type
(opt_in, double_opt_in, list_import, or manual), the consent_source, the exact
consent_text shown, and optionally the recipient's IP and user agent.
The ledger is append-only: nothing is ever deleted, so the consent history stays intact —
a later consent for the same recipient is a new record, and a withdrawal stamps the
withdrawal timestamp onto the latest matching record (see the withdraw operation). The
stored hash survives a right-to-forget erasure to preserve the audit trail. Requires the
compliance:write scope.
Request body
application/vnd.api+json
— CreateRecipientConsentRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
recipient_email
required
|
string | |
consent_type
required
|
string | |
consent_source
required
|
string | |
consent_text
required
|
string | |
ip_address
|
string|null | |
user_agent
|
string|null |
curl -X POST https://api.minimailer.app/recipient-consents \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"recipient-consents","attributes":{"recipient_email":"...","consent_type":"...","consent_source":"...","consent_text":"...","ip_address":"...","user_agent":"..."}}}'
Responses
|
Status
|
Description
|
|---|---|
| 201 |
Recipient consent recorded.
RecipientConsentDocument
|
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
ErrorDocument
|
| 404 |
The resource does not exist, or it belongs to another account. The two cases return the same status, error code and detail by design, so the error document does not confirm that an identifier is in use.
ErrorDocument
|
| 422 |
The request document failed validation.
ValidationErrorDocument
|
| 409 |
The request conflicts with the endpoint or current state. Branch on the error code: conflict — the document's resource type does not match the endpoint, its id does not match the resource being updated, or an idempotency key was reused with a different payload; agent_category_conflict — the agent_id names an identity already bound to the other kind of mail (one agent identity sends either transactional or marketing mail, never both; an identity dormant for 30 days may rebind). (Creating with a client-generated id and updating relationships on an endpoint that does not support them return 403 instead.)
ErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
ErrorDocument
|
/recipient-consents/withdraw
Withdraw a recipient consent
Records a GDPR Article 7(3) consent withdrawal: stamps the withdrawal timestamp and
channel onto the latest consent record matching the domain, recipient email, and
consent_type. The ledger stays append-only — the consent record is never deleted, and
earlier records for the same recipient are left untouched.
The recipient is matched by the stored email hash, so a withdrawal can still be recorded
after a right-to-forget erasure has scrubbed the cleartext address. Responds 404 when no
matching consent exists or when the latest one is already withdrawn. withdrawn_via
defaults to api when omitted.
A recipient's own unsubscribe records a withdrawal automatically (with the unsubscribe as
the channel), so this endpoint is for withdrawals that reach you out-of-band — a reply, a
phone call, a regulator request. Requires the compliance:write scope.
Request body
application/vnd.api+json
— WithdrawRecipientConsentRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
recipient_email
required
|
string | |
consent_type
required
|
string | |
withdrawn_via
|
string | The channel the withdrawal arrived through. Defaults to `api`. |
curl -X POST https://api.minimailer.app/recipient-consents/withdraw \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"recipient-consents","attributes":{"recipient_email":"...","consent_type":"...","withdrawn_via":"..."}}}'
Responses
|
Status
|
Description
|
|---|---|
| 200 |
Consent withdrawal recorded on the latest matching record.
RecipientConsentDocument
|
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
ErrorDocument
|
| 404 |
The resource does not exist, or it belongs to another account. The two cases return the same status, error code and detail by design, so the error document does not confirm that an identifier is in use.
ErrorDocument
|
| 422 |
The request document failed validation.
ValidationErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
ErrorDocument
|