Skip to content
CognizyCognizyHelp
Sign in
In this area

Email

Send transactional email directly, without creating an inbox conversation. Uses a Cognizy template or a body you supply; draws on the plan allowance and then the wallet.

Send an email

post/v1/public/email/messages

Accepts Idempotency-Key

Sends one email or a batch. Content comes either from a Cognizy template (templateId) or from subject + html/text in the request; {{variables}} are resolved per recipient. Returns 202 with the queued email id (or a list, for a batch). Pass an Idempotency-Key header to retry safely without sending twice. The send is refused up front if the monthly allowance and wallet balance together do not cover it.

Parameters

idempotency-keystringrequired· header

Body (JSON)required

tostring (email)optional
Single recipient. Use this OR recipients for a batch — never both. Recipients never see each other; every address gets its own message.
recipientsobject[]optional
Batch of recipients, each with its own variables. Max 1000 per request — split larger sends across calls, or use a campaign.
recipients[].tostring (email)required
recipients[].variablesobjectoptional
Values for the {{variables}} in the template or body, for this recipient only. Keys are used as-is: {"contact.firstName": "Maria"} fills {{contact.firstName}}.
templateIdstringoptional
Id of an email template created in Cognizy. Its subject and HTML are used, with {{variables}} resolved per recipient. Omit to send subject + html/text directly.
subjectstringoptional
Subject line. Required without a template; with one, overrides the template subject. Supports {{variables}}.
htmlstringoptional
HTML body. Supports {{variables}}. Ignored when templateId is set.
textstringoptional
Plain-text body, for clients that do not render HTML. Derived from the HTML when omitted.
replyTostring (email)optional
Reply-To for this message, when replies should not go to the channel sender.
variablesobjectoptional
Variables applied to every recipient. Per-recipient variables win on conflict.

Responses

  • 202Email accepted and queued
  • 400Invalid payload, unknown template or quota exhausted

Examples

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/email/messages" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "to": "maria@exemplo.com",
  "recipients": [
    {
      "to": "maria@exemplo.com",
      "variables": {
        "contact.firstName": "Maria",
        "order.id": "#1234"
      }
    }
  ],
  "templateId": "clx123abc456",
  "subject": "Seu pedido {{order.id}} foi enviado",
  "html": "<p>Olá {{contact.firstName}}, seu pedido saiu para entrega.</p>",
  "text": "Olá {{contact.firstName}}, seu pedido saiu para entrega.",
  "replyTo": "suporte@empresa.com",
  "variables": {
    "organization.name": "Acme"
  }
}'

List email templates

get/v1/public/email/templates

Templates available to templateId, with the {{variables}} each one expects — so an integration can discover what to send without opening the dashboard.

Parameters

No parameters.

Responses

  • 200

Examples

bash
curl -X GET "https://api.cognizy.ai/api/v1/public/email/templates" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Get the status of a sent email

get/v1/public/email/messages/{id}

Statuses: QUEUED → SENT → DELIVERED → OPENED/CLICKED, or BOUNCED/FAILED. Status never moves backwards, so a late provider event cannot undo a further one.

Parameters

idstringrequired· path
OutboundEmail id returned by POST

Responses

  • 200

Examples

bash
curl -X GET "https://api.cognizy.ai/api/v1/public/email/messages/<id>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Full reference