API reference · v1
Templates
Send stored message templates. Templates are authored in the app.
List templates
/v1/templatesQuery 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/templates' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": [
{
"id": "tpl_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"transactional": false,
"contentFormat": "mjml",
"contentEditor": "rich",
"content": {
"subject": "string",
"body": "string"
},
"from": {
"type": "domain",
"domainId": "dom_BcwDvBUeSaSDILA5tHgpmU7I",
"code": "string",
"name": "string"
},
"recipientDataPath": [
"string"
],
"expectedDataRepresentation": [
{
"key": "string",
"type": "record",
"schema": "string",
"isArray": false,
"description": "string"
}
],
"communicationTopicId": "ct_BcwDvBUeSaSDILA5tHgpmU7I"
}
],
"pagination": {
"limit": 0,
"offset": 0,
"totalCount": 0,
"hasMore": false
},
"warnings": []
}Status codes
- 200A page of templates.
- 401The credential is missing or invalid:
invalid_api_keyfor an API key,invalid_access_tokenfor an expired or revoked OAuth access token. TheWWW-Authenticateheader names the resource metadata, from which an OAuth client finds the authorization server. - 403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers
insufficient_scope. - 429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
- 500The API failed to process a valid request.
Get a template
/v1/templates/{id}Error: template_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The template id.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/templates/tpl_BcwDvBUeSaSDILA5tHgpmU7I' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": {
"id": "tpl_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"transactional": false,
"contentFormat": "mjml",
"contentEditor": "rich",
"content": {
"subject": "string",
"body": "string"
},
"from": {
"type": "domain",
"domainId": "dom_BcwDvBUeSaSDILA5tHgpmU7I",
"code": "string",
"name": "string"
},
"recipientDataPath": [
"string"
],
"expectedDataRepresentation": [
{
"key": "string",
"type": "record",
"schema": "string",
"isArray": false,
"description": "string"
}
],
"communicationTopicId": "ct_BcwDvBUeSaSDILA5tHgpmU7I"
},
"warnings": []
}Status codes
- 200The template.
- 401The credential is missing or invalid:
invalid_api_keyfor an API key,invalid_access_tokenfor an expired or revoked OAuth access token. TheWWW-Authenticateheader names the resource metadata, from which an OAuth client finds the authorization server. - 403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers
insufficient_scope. - 404The referenced resource was not found.
- 429A request rate or capacity limit was reached. Follow the error code and Retry-After; a capacity refusal can follow durable preparation.
- 500The API failed to process a valid request.
Send a template
/v1/templates/{templateId}/sendRequires Write permission and a stable Idempotency-Key. Renders stored template content and sends to the recipient resolved from data. Read expectedDataRepresentation and send every required key; referenced records are upserted before rendering and configured attribute expansions are applied. Available credits and email allowance are required. There is no subject/body replacement or preview execution parameter. A template without an email channel returns template_not_sendable. Pre-send validation and eligibility failures use request errors (email_limit_reached, sending_disabled, template_not_sendable, domain_not_verified, invalid_data, marketing_requires_contact, recipient_not_subscribed, recipient_suppressed). Records or preparation artifacts can exist before a later failure; an error does not prove that the request made no changes. HTTP 200 exposes emailId, status, and error. status=sent means the provider accepted the durable send attempt, not inbox delivery. A known terminal refusal or cancellation can return status=failed with a generic error. A temporary dispatch refusal returns 429 template_send_retryable with Retry-After. Wait, then retry the same key, template and input. The retry reuses the saved message and recipient. An uncertain delivery or rendering result returns 409 template_send_outcome_unknown without a retry hint. Reconcile it; do not create a new key to force a second send. A confirmed permanent rejection stays failed on retry. Template sends do not return generic response-cache replay headers.
Path parameters
- Name
templateId- Type
- string
- Requirement
- Required
- Description
- The template id.
Headers
- Name
Idempotency-Key- Type
- string
- Requirement
- Required
- Description
- Non-blank identity for one template send. Keep the same API key, template and input when retrying. The identity is scoped to the space and calling API key; using it for a different template or input returns 409 template_send_operation_conflict. A retry resumes the saved preparation or delivery and reuses its exact message and recipient. It does not replay a generic cached HTTP response, return Idempotent-Replay or Operation-Id, or permit key reuse after the generic 24-hour response-cache period. An erased request returns 410 template_send_erased. An unknown result needs reconciliation; do not mint a replacement key.
Request body
Send JSON with Content-Type: application/json. A body is required.
- Name
data- Type
- object
- Requirement
- Required
- Description
- Payload keyed by the template's expected data-representation properties. Minimal identifiers suffice for record properties (e.g.
{ "email": "[email protected]" }for a contact); the platform finds-or-creates the record, then reads it back for rendering.
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/templates/tpl_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 '{
"data": {
"contact": {
"email": "[email protected]"
}
}
}'Response
{
"data": {
"emailId": "email_BcwDvBUeSaSDILA5tHgpmU7I",
"status": "sent",
"error": "string"
},
"warnings": []
}Status codes
- 200The send was processed. Inspect data.status for the delivery result.
- 400The request is invalid, including a missing or blank Idempotency-Key (template_send_operation_required).
- 401The credential is missing or invalid:
invalid_api_keyfor an API key,invalid_access_tokenfor an expired or revoked OAuth access token. TheWWW-Authenticateheader names the resource metadata, from which an OAuth client finds the authorization server. - 402Insufficient credits (
insufficient_credits) for an AI-generation call or a schema with AI auto-fill, or the space's email allowance is exhausted (email_limit_reached). - 403The key lacks permission, or the space is out of scope. An OAuth connection whose user holds the permission but did not grant it answers
insufficient_scope. - 404The referenced resource was not found.
- 409template_send_operation_conflict means this key was already used with a different template or input. template_send_outcome_unknown means an existing rendering or delivery result needs reconciliation. Neither response authorizes a new send identity.
- 410The send or its source data was erased (template_send_erased). The saved operation cannot be retried.
- 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 API rate limit or dispatch capacity is temporarily unavailable. For template_send_retryable, the message can already be prepared. Wait for Retry-After, then retry the unchanged request with the same Idempotency-Key.
- 500The API failed to process a valid request.
- 503The send is still processing (template_send_processing), preparation capacity is full (template_send_capacity_in_use), or the space is paused for maintenance. Retry later with the same identity and input. An uncertain provider result instead returns 409.
Working with these endpoints? See error handling, safe retries, client library guides, and the complete OpenAPI schema.