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 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 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 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.
Send a template
/v1/templates/{templateId}/sendRenders 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. Supports Idempotency-Key. Pre-send validation/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). The result exposes emailId, status, and error. status=sent means the provider accepted the durable send attempt, not inbox delivery. HTTP 200 status=failed collapses retryable refusals, terminal refusals, cancellation, and unknown provider outcomes into one public state with a generic error. It does not prove non-delivery or establish whether another send is safe. Preserve emailId and the original operation key and reconcile in the app; do not create a new key to force a second send. A stored template without an email channel can return null status/emailId/error.
Path parameters
- Name
templateId- Type
- string
- Requirement
- Required
- Description
- The template 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.
- 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.
- 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.
- 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.
- 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.
Working with these endpoints? See error handling, safe retries, client library guides, and the complete OpenAPI schema.