Audiences
Audience management operations.
POST
/audiences
Create an audience
Creates an audience — a named list that groups contacts for marketing campaigns — for the
authenticated user. Add contacts to it individually via
POST /audiences/{audience}/contacts or in bulk via the import endpoint, then
target it from a campaign. Requires the contacts:write scope.
Request body
application/vnd.api+json
— CreateAudienceRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
name
required
|
string | |
description
|
string|null |
POST /audiences
curl -X POST https://api.minimailer.app/audiences \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"audiences","attributes":{"name":"...","description":"..."}}}'
Responses
|
Status
|
Description
|
|---|---|
| 201 |
Audience created.
AudienceDocument
|
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The authenticated token does not have permission to perform this action.
ErrorDocument
|
| 404 |
The referenced domain does not exist.
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
/audiences
List audiences
Returns the authenticated user's audiences, newest first, with the JSON:API
sort, include, and sparse fields parameters. Requires the contacts:read scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
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=...). |
GET /audiences
curl -X GET https://api.minimailer.app/audiences \ -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 |
Audiences retrieved.
AudienceCollectionDocument
|
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The authenticated token does not have permission to perform this action.
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
/audiences/{audience}
Show an audience
Returns a single audience owned by the authenticated user. Use the include parameter to
embed related contacts in the response. 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. |
audience
required
|
path | The audience identifier. |
GET /audiences/{audience}
curl -X GET https://api.minimailer.app/audiences/{audience} \ -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 |
Audience retrieved.
AudienceDocument
|
| 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
/audiences/{audience}
Update an audience
Updates an audience owned by the authenticated user, such as its name. Its contacts are
managed through the audience's contacts relationship, not this endpoint. Requires the
contacts:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
audience
required
|
path | The audience identifier. |
Request body
application/vnd.api+json
— UpdateAudienceRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
name
|
string | |
description
|
string|null |
PATCH /audiences/{audience}
curl -X PATCH https://api.minimailer.app/audiences/{audience} \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"audiences","attributes":{"name":"...","description":"..."}}}'
Responses
|
Status
|
Description
|
|---|---|
| 200 |
Audience updated.
AudienceDocument
|
| 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
/audiences/{audience}
Delete an audience
Deletes an audience owned by the authenticated user along with its membership. Campaigns
that targeted the audience are retained, including their historical statistics. Their
audience relationship is returned with data: null when requested via include=audience.
Deletion is refused with 409 while a campaign targeting the audience is scheduled,
sending, or paused — cancel that campaign first. Requires the contacts:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
audience
required
|
path | The audience identifier. |
DELETE /audiences/{audience}
curl -X DELETE https://api.minimailer.app/audiences/{audience} \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 204 | Audience 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
|
| 409 |
A campaign targeting this audience is scheduled, sending, or paused; cancel it before deleting the audience.
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
|