Skip to Content
Server APITransactional push

Transactional push

Transactional templates provide a stable API key for lifecycle messages such as order updates, account alerts, and one-to-one reminders.

Author the template

A template defines:

  • immutable published key;
  • target apps;
  • default and optional fallback locale;
  • typed variables: string, number, boolean, date, and URL;
  • localized title, body, deep link, and custom data;
  • TTL, normal/high priority, per-minute rate limit, and deduplication window;
  • draft and published versions.

Only an active published template can accept public sends.

Request

POST /api/v1/environments/{environmentId}/transactional/{templateKey}/send
Authorization: Bearer engk_…
Content-Type: application/json
{
  "recipient": {
    "type": "EXTERNAL_ID",
    "value": "customer_123"
  },
  "locale": "fr-FR",
  "variables": {
    "first_name": "Ada",
    "amount": 149.9,
    "receipt_url": "https://example.com/receipts/42"
  },
  "idempotencyKey": "receipt-ready:42"
}

Locale resolution uses the requested locale, the template default, and configured fallback. The response reports resolvedLocale and rendering diagnostics.

Idempotency

idempotencyKey is part of the request body for transactional sends. Repeating the same admitted request with the same key returns the established result instead of creating a second logical send. Reusing the key with a conflicting request is rejected.

Use a key derived from the business operation, not from an HTTP attempt:

Good: order-shipped:ORD-2026-1042
Bad:  request-attempt:2026-08-18T12:00:01.123Z

App scope and eligibility

The active template declares target apps. The access key declares allowed apps. Engage sends only through their intersection. Recipient resolution, privacy, subscription, push readiness, suppression, and provider state still apply.

Delivery semantics

202 Accepted means the request entered Engage’s durable delivery pipeline. It does not guarantee provider acceptance, device delivery, display, or open. Use diagnostics and analytics for later states.

Testing

The console can test a template against a test group. The public endpoint intentionally rejects TEST_GROUP; server code should target a profile, external ID, or installation.

AuthenticationTrigger automations