Transactional Push

Overview

Flameup's transactional push API sends a notification to a user's device. Use it for notifications triggered by user actions like order confirmations, password resets, and account alerts.

Push Notifications

Send Push Notification

Endpoint: POST /api/v1/workspaces/{workspace_id}/push/send

This sends to exactly one device: the first of the person's active tokens. There is no way on this route to pick a platform or fan out to every device a person has. The fields below — content, targeting and template context — are the complete set the endpoint honours.

async function sendPush(externalId, title, body, options = {}) {
  const response = await fetch(
    `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/push/send`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        external_id: externalId,
        title: title,
        body: body,
        ...options
      })
    }
  );

  return response.json();
}

// Example: Order confirmation
await sendPush('user_12345',
  'Order Confirmed!',
  'Your order #ORD-12345 has been confirmed. Total: $99.99',
  {
    action_url: 'myapp://orders/ORD-12345'
  }
);

import requests

def send_push(external_id, title, body, **options):
    response = requests.post(
        f'https://api.flameup.ai/api/v1/workspaces/{WORKSPACE_ID}/push/send',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {API_KEY}'
        },
        json={
            'external_id': external_id,
            'title': title,
            'body': body,
            **options
        }
    )
    return response.json()

# Example: Order confirmation
send_push(
    'user_12345',
    'Order Confirmed!',
    'Your order #ORD-12345 has been confirmed. Total: $99.99',
    action_url='myapp://orders/ORD-12345'
)

curl -X POST "https://api.flameup.ai/api/v1/workspaces/your_workspace_id/push/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "external_id": "user_12345",
    "title": "Order Confirmed!",
    "body": "Your order #ORD-12345 has been confirmed. Total: $99.99",
    "action_url": "myapp://orders/ORD-12345"
  }'

Request Body

Response

Always 200 when the request itself was processed — check the status field:

{
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sent",
  "sent_at": "2024-01-15T10:30:00Z",
  "provider": "fcm",
  "provider_id": "projects/myapp/messages/abc123"
}

sent is as much as the API can tell you. FCM has no status-check API, so there is no endpoint that can report delivery beyond what the send response already said.

Send policy

A workspace can carry a send policy (dashboard → workspace settings, settings.send_policy) that constrains push delivery — and it applies to this API, not just to campaigns. When the policy blocks a send, the response is still 200, with "status": "policy_suppressed". The suppressed message is dropped, not queued — it is not retried when the window reopens.

Three rules can suppress a transactional send:

• Quiet hours — a local-time window (e.g. 22:00–08:00 in the workspace's policy timezone) during which nothing is pushed. Never bypassable.
• Daily cap (max_pushes_per_day) — a per-user cap that resets at local midnight in the policy timezone.
• Rolling-window cap (max_pushes_per_window over window_hours) — a per-user cap over a sliding window of 1–168 hours, counted in absolute time with no calendar reset. Configured as both-or-neither with window_hours.

Send to many people at once

Endpoint: POST /api/v1/workspaces/{workspace_id}/push/send/batch

Up to 1000 recipients in one request, each rendered and sent individually.

{
  "title": "Your order shipped",
  "body": "Hi {{name}}, it's on its way",
  "recipients": [
    { "user_id": "550e8400-e29b-41d4-a716-446655440000", "device_token": "…",
      "platform": "android", "variables": { "name": "Jane" } }
  ]
}

Requires push:send.

Response (200) — one result per recipient, in request order, plus a summary. Recipient results use the same status values as single send (sent / skipped / policy_suppressed), with one addition: "failed" when that recipient's send errored (bad UUID, provider failure):

{
  "results": [
    { "message_id": "…", "status": "sent", "provider": "fcm", "sent_at": "…" },
    { "message_id": "", "status": "failed", "error": "failed to send push notification", "sent_at": "…" }
  ],
  "summary": { "total": 2, "sent": 1, "failed": 1, "processed": "2026-08-28T10:30:00Z" }
}

One trap in the summary: summary.sent counts every non-failed result — skipped and policy_suppressed recipients count as "sent" there. To know who actually got a push, walk results and count status === "sent".

Validating tokens

Endpoint: POST .../push/tokens/validate (requires push:send)

Checks a device_token + platform pair and returns {"valid": true|false}. Be aware this is a format check only — token length and shape per platform. It does not ask FCM whether the token is live, so a well-formed revoked token still validates. The reliable liveness signal is a delivery failure, which marks the stored token invalid automatically (see Devices — Token Lifecycle).

Push Notification Examples

// Order confirmation
await sendPush(externalId, 'Order Confirmed!',
  'Your order #ORD-12345 is confirmed. Total: $99.99', {
    action_url: 'myapp://orders/ORD-12345'
});

// Shipping notification
await sendPush(externalId, 'Your order has shipped!',
  'Track your package: 1Z999AA10123456784', {
    action_url: 'myapp://tracking/1Z999AA10123456784'
});

// Delivered notification
await sendPush(externalId, 'Package delivered!',
  'Your order #ORD-12345 has been delivered.', {
    action_url: 'myapp://orders/ORD-12345/review'
});

// New login alert
await sendPush(externalId, 'New Login Detected',
  'New sign-in from Chrome on Windows in New York, US', {
    action_url: 'myapp://security'
});

// Password changed
await sendPush(externalId, 'Password Changed',
  'Your password was changed. If this wasn\'t you, contact support.');

// Payment successful
await sendPush(externalId, 'Payment Received',
  'We received your payment of $49.99. Thank you!', {
    action_url: 'myapp://receipts/pay_abc123'
});

// Payment failed
await sendPush(externalId, 'Payment Failed',
  'Your payment of $49.99 was declined. Please update your card.', {
    action_url: 'myapp://billing'
});

// New follower
await sendPush(externalId, 'John Doe is now following you',
  'Tap to view their profile', {
    action_url: 'myapp://profile/user_456',
    image_url: 'https://example.com/avatars/user_456.jpg'
});

// New message
await sendPush(externalId, 'New message from Jane',
  'Hey, are you free for lunch?', {
    action_url: 'myapp://chat/chat_789'
});

Error Handling

The single-send route splits outcomes across the HTTP status and the body's status field. A 200 is not proof anything was sent — the no-device case, the suppressed-token case, an unsubscribed or suppressed person, and a policy suppression all come back 200:

Single send never returns 200 with "status": "failed" — that value exists only in per-recipient batch results.

Handling in Code

async function sendNotification(externalId, title, body, options) {
  const result = await sendPush(externalId, title, body, options);

  if (!result.status) {
    // HTTP-level error body: 404 unknown external_id, 500 provider failure
    console.error('Push request failed:', result.error);
    return null;
  }

  if (result.status !== 'sent') {
    // 'skipped' or 'policy_suppressed' — a 200, but the user got nothing.
    console.warn('Push not delivered:', result.status, result.error);
    // Fall back to another channel
    return null;
  }

  return result;
}

Best Practices

// No lookup step. The id you already have is the id the API wants.
await sendPush('user_123', 'Order Confirmed!', 'Your order is on its way');