API reference · v1
Broadcasts
Schedule, send, and measure mass emails. Broadcasts are authored in the app.
List broadcasts
GET
/v1/broadcastsQuery parameters
- Name
limit- Type
- integer
- Description
- Page size. Clamped to 1..200 with a warning if out of range.
- Name
offset- Type
- integer
- Description
- Rows to skip. Negative values clamp to 0 with a warning; above 10000 returns 400 offset_too_large. pagination.hasMore becomes false when the next offset reaches the cap even if totalCount is larger. Records list has no ad-hoc filter; this is not an unlimited export contract.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/broadcasts' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": [
{
"id": "bc_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"contactSchemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"contactSchemaSlug": "string",
"schedulingStatus": "none",
"scheduledFor": "2025-01-15T10:30:00.000Z",
"sendingStartedAt": "2025-01-15T10:30:00.000Z",
"sendingFinishedAt": "2025-01-15T10:30:00.000Z",
"failureReason": "string",
"audience": {
"type": "all"
},
"hasContent": false
}
],
"pagination": {
"limit": 0,
"offset": 0,
"totalCount": 0,
"hasMore": false
},
"warnings": []
}Status codes
- 200A page of broadcasts.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Get a broadcast
GET
/v1/broadcasts/{id}Error: broadcast_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The broadcast id.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/broadcasts/bc_BcwDvBUeSaSDILA5tHgpmU7I' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": {
"id": "bc_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"contactSchemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"contactSchemaSlug": "string",
"schedulingStatus": "none",
"scheduledFor": "2025-01-15T10:30:00.000Z",
"sendingStartedAt": "2025-01-15T10:30:00.000Z",
"sendingFinishedAt": "2025-01-15T10:30:00.000Z",
"failureReason": "string",
"audience": {
"type": "all"
},
"hasContent": false
},
"warnings": []
}Status codes
- 200The broadcast.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Update a broadcast
PATCH
/v1/broadcasts/{id}Updates name, description, scheduledFor, and/or audience before sending starts. At least one field is required. Audience accepts all or an existing segment for the broadcast contact schema; custom filter generation and content authoring are not available here. Concurrent changes or a planning claim can return 409 broadcast_changed; a started send cannot be edited. Supports Idempotency-Key. Cancel/stop/resume/redrive controls are available through app workflows, not this public endpoint.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The broadcast id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request body
Send JSON with Content-Type: application/json. A body is required.
At least one field must be provided. Only name/description/ audience/scheduledFor are updatable; content is not editable through this endpoint. Rejected once sending has started.
- Name
name- Type
- string | null
- Description
- See the request example and OpenAPI schema for this field.
- Name
description- Type
- string | null
- Description
- See the request example and OpenAPI schema for this field.
- Name
audience- Type
- object
- Description
- The audience to point a broadcast at: everyone in its contact schema, or an existing segment. A
custom filteraudience is authored in the maxclicks app, where a human reviews the generated condition before it drives a mass send, and cannot be set here.
- Name
scheduledFor- Type
- string (date-time) | null
- Description
- See the request example and OpenAPI schema for this field.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/broadcasts/bc_BcwDvBUeSaSDILA5tHgpmU7I' \
-X PATCH \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}" \
-H "Content-Type: application/json" \
-d '{
"name": "September customer update"
}'Response
{
"data": {
"id": "bc_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"contactSchemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"contactSchemaSlug": "string",
"schedulingStatus": "none",
"scheduledFor": "2025-01-15T10:30:00.000Z",
"sendingStartedAt": "2025-01-15T10:30:00.000Z",
"sendingFinishedAt": "2025-01-15T10:30:00.000Z",
"failureReason": "string",
"audience": {
"type": "all"
},
"hasContent": false
},
"warnings": []
}Status codes
- 200The updated broadcast.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Send a broadcast
POST
/v1/broadcasts/{id}/sendSchedules a prepared broadcast immediately or for scheduledFor and returns 202. It does not wait for planning or delivery. Content is authored in the app. A pre-existing send schedule, started send, or active planning claim returns 409 broadcast_already_sending. Readiness issues return 422 broadcast_invalid with issues. Supports Idempotency-Key. Read runs to inspect recipients; HTTP acceptance is not proof every recipient received email.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The broadcast id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request body
Send JSON with Content-Type: application/json.
An empty or omitted body sends now; a scheduledFor schedules for later.
- Name
scheduledFor- Type
- string (date-time)
- Description
- See the request example and OpenAPI schema for this field.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/broadcasts/bc_BcwDvBUeSaSDILA5tHgpmU7I/send' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}" \
-H "Content-Type: application/json" \
-d '{}'Response
{
"data": {
"id": "bc_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"contactSchemaId": "sch_BcwDvBUeSaSDILA5tHgpmU7I",
"contactSchemaSlug": "string",
"schedulingStatus": "none",
"scheduledFor": "2025-01-15T10:30:00.000Z",
"sendingStartedAt": "2025-01-15T10:30:00.000Z",
"sendingFinishedAt": "2025-01-15T10:30:00.000Z",
"failureReason": "string",
"audience": {
"type": "all"
},
"hasContent": false
},
"warnings": []
}Status codes
- 202The broadcast was accepted for sending.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
List a broadcast's runs
GET
/v1/broadcasts/{id}/runsOne reduced run record per recipient contact. Error: broadcast_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The broadcast id.
Query parameters
- Name
limit- Type
- integer
- Description
- Page size. Clamped to 1..200 with a warning if out of range.
- Name
offset- Type
- integer
- Description
- Rows to skip. Negative values clamp to 0 with a warning; above 10000 returns 400 offset_too_large. pagination.hasMore becomes false when the next offset reaches the cap even if totalCount is larger. Records list has no ad-hoc filter; this is not an unlimited export contract.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/broadcasts/bc_BcwDvBUeSaSDILA5tHgpmU7I/runs' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": [
{
"id": "bcr_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"contactId": "con_BcwDvBUeSaSDILA5tHgpmU7I",
"contactEmail": "string",
"status": "sent",
"failureReason": "string",
"email": {
"id": "bcr_BcwDvBUeSaSDILA5tHgpmU7I",
"sentAt": "2025-01-15T10:30:00.000Z",
"opensCount": 0,
"clicksCount": 0,
"bounced": false,
"complained": false
}
}
],
"pagination": {
"limit": 0,
"offset": 0,
"totalCount": 0,
"hasMore": false
},
"warnings": []
}Status codes
- 200A page of broadcast runs.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Get a broadcast's aggregated email metrics
GET
/v1/broadcasts/{id}/metricsemail is omitted entirely when the broadcast has no email content yet. Error: broadcast_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The broadcast id.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/broadcasts/bc_BcwDvBUeSaSDILA5tHgpmU7I/metrics' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": {
"email": {
"sent": 0,
"delivered": 0,
"bounced": 0,
"deliveryDelays": 0,
"rejected": 0,
"failed": 0,
"complained": 0,
"unsubscribed": 0,
"opens": 0,
"uniqueOpens": 0,
"clicks": 0,
"uniqueClicks": 0
}
},
"warnings": []
}Status codes
- 200Aggregated send/open/click/bounce metrics.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Working with these endpoints? See error handling, safe retries, client library guides, and the complete OpenAPI schema.