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 authenticated token does not have permission to perform this action.
ErrorDocument
|
| 404 |
The requested resource could not be found.
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 caller exceeded the API rate limit.
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 authenticated token does not have permission to perform this action.
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 caller exceeded the API rate limit.
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 authenticated token does not have permission to perform this action.
ErrorDocument
|
| 404 |
The requested resource could not be found.
ErrorDocument
|
| 422 |
The request document failed validation.
ValidationErrorDocument
|
| 409 |
The request conflicts with the endpoint or current state: 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. (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 caller exceeded the API rate limit.
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 authenticated token does not have permission to perform this action.
ErrorDocument
|
| 404 |
The requested resource could not be found.
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 caller exceeded the API rate limit.
ErrorDocument
|