Contacts
Contact management operations.
GET
/audiences/{audience}/contacts
List contacts
Returns the contacts belonging to an audience owned by the authenticated user, newest first.
Supports the JSON:API filter, sort, include, and sparse fields parameters — for
example filter by subscription status. Requires the contacts:read scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
filter
|
query | Exact-match filters, e.g. filter[status]=delivered. Only the fields this endpoint allow-lists are accepted; an unsupported filter returns 400. |
sort
|
query | Comma-separated sort fields; prefix a field with - for descending, e.g. sort=-created_at,name. Defaults to newest-first. Only allow-listed fields are accepted; an unsupported sort returns 400. |
include
|
query | Comma-separated related resources to embed in the response included member (JSON:API compound documents). Example: include=records,webhooks. Nested paths use dot notation, max depth 2. Relationships not declared by the resource, or over-deep paths, return 400. |
fields
|
query | Per-type sparse fieldsets. Example: fields[domains]=name,status restricts the returned attributes for that type. The type must be present in the document and each field must be a known attribute, otherwise 400 is returned. |
page
|
query | Cursor-based pagination, e.g. page[cursor]=eyJpZCI6...&page[size]=50. The cursor is an opaque token issued by the API — take it from the response's links.next / links.prev URLs or meta.next_cursor / meta.prev_cursor; never construct one. size defaults to 25 and is silently capped at 100 (out-of-range or non-numeric values fall back to the default). An invalid or expired cursor falls back to the first page; a cursor replayed with a different sort than it was issued under returns 400; unknown page members such as page[number] return 400. Follow links.next until it is null (or meta.has_more is false) to traverse a collection; links.first restarts traversal. Link URLs carry these parameters URL-encoded (page%5Bcursor%5D=...). |
audience
required
|
path | The audience identifier. |
GET /audiences/{audience}/contacts
curl -X GET https://api.minimailer.app/audiences/{audience}/contacts \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 400 |
The include or fields query parameter is not supported (unknown relationship, over-deep include, or unknown sparse-fieldset type or field).
ErrorDocument
|
| 200 |
Contacts retrieved.
ContactCollectionDocument
|
| 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
|
| 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
|
POST
/audiences/{audience}/contacts
Create a contact
Adds a single contact to an audience owned by the authenticated user, with an email plus
optional name, preferences, and custom fields. Email is normalised (lower-cased and trimmed)
and unique within the audience; adding an address already present returns 422. For adding
many contacts at once use the import endpoint. Requires the contacts:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
audience
required
|
path | The audience identifier. |
Request body
application/vnd.api+json
— CreateContactRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
email
required
|
string | |
name
|
string|null | |
preferences
|
object|null | |
custom_fields
|
object|null |
POST /audiences/{audience}/contacts
curl -X POST https://api.minimailer.app/audiences/{audience}/contacts \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"contacts","attributes":{"email":"...","name":"...","preferences":{},"custom_fields":{}}}}'
Responses
|
Status
|
Description
|
|---|---|
| 201 |
Contact created.
ContactDocument
|
| 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
|
| 415 |
The request Content-Type must be application/vnd.api+json, with no media type parameters other than profile (ext is rejected — no JSON:API extensions are supported — as is any other parameter such as charset).
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
|
POST
/audiences/{audience}/contacts/import
Import contacts
Bulk-adds contacts to an audience owned by the authenticated user in a single request.
Emails are normalised and de-duplicated both against contacts already in the audience and
within the submitted batch; duplicates are skipped, not rejected, so a partially
overlapping import still succeeds. The response reports how many contacts were created
versus skipped. Requires the contacts:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
audience
required
|
path | The audience identifier. |
Request body
application/vnd.api+json
— ImportContactsRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
contacts
required
|
array |
POST /audiences/{audience}/contacts/import
curl -X POST https://api.minimailer.app/audiences/{audience}/contacts/import \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"contacts","attributes":{"contacts":[]}}}'
Responses
|
Status
|
Description
|
|---|---|
| 200 |
Contacts import processed.
ContactImportDocument
|
| 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
|
| 415 |
The request Content-Type must be application/vnd.api+json, with no media type parameters other than profile (ext is rejected — no JSON:API extensions are supported — as is any other parameter such as charset).
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
|
GET
/contacts/{contact}
Show a contact
Returns a single contact belonging to an audience owned by the authenticated user, including
its email, name, subscription status, preferences, and custom fields. Requires the
contacts:read scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
include
|
query | Comma-separated related resources to embed in the response included member (JSON:API compound documents). Example: include=records,webhooks. Nested paths use dot notation, max depth 2. Relationships not declared by the resource, or over-deep paths, return 400. |
fields
|
query | Per-type sparse fieldsets. Example: fields[domains]=name,status restricts the returned attributes for that type. The type must be present in the document and each field must be a known attribute, otherwise 400 is returned. |
contact
required
|
path | The contact identifier. |
GET /contacts/{contact}
curl -X GET https://api.minimailer.app/contacts/{contact} \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 400 |
The include or fields query parameter is not supported (unknown relationship, over-deep include, or unknown sparse-fieldset type or field).
ErrorDocument
|
| 200 |
Contact retrieved.
ContactDocument
|
| 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
|
| 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
|
PATCH
/contacts/{contact}
Update a contact
Updates a contact belonging to an audience owned by the authenticated user — its name,
subscription status, preferences, or custom fields. Requires the contacts:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
contact
required
|
path | The contact identifier. |
Request body
application/vnd.api+json
— UpdateContactRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
email
|
string | |
name
|
string|null | |
preferences
|
object|null | |
custom_fields
|
object|null |
PATCH /contacts/{contact}
curl -X PATCH https://api.minimailer.app/contacts/{contact} \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"contacts","attributes":{"email":"...","name":"...","preferences":{},"custom_fields":{}}}}'
Responses
|
Status
|
Description
|
|---|---|
| 200 |
Contact updated.
ContactDocument
|
| 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
|
| 415 |
The request Content-Type must be application/vnd.api+json, with no media type parameters other than profile (ext is rejected — no JSON:API extensions are supported — as is any other parameter such as charset).
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
|
DELETE
/contacts/{contact}
Delete a contact
Removes a contact from an audience owned by the authenticated user. This deletes the
contact's membership of the audience; it does not add the address to any suppression list.
Requires the contacts:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
contact
required
|
path | The contact identifier. |
DELETE /contacts/{contact}
curl -X DELETE https://api.minimailer.app/contacts/{contact} \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 204 | Contact deleted. |
| 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
|
| 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
|