Messaging

Transactional Messaging

Send one-off messages triggered by your application

Overview

Transactional messages are one-off, API-triggered notifications sent in response to user actions. Unlike campaigns, they're immediate and personalized for specific moments.

Required Permission: campaigns:trigger to send transactional messages.

When to Use Transactional Messages

Transactional

Use for immediate, user-triggered notifications:

Order confirmations
Password resets
Payment receipts
Shipping updates
Account alerts
Verification codes

Campaigns

Use for automated, recurring messages:

Welcome series
Re-engagement
Promotional offers
Weekly digests
Abandoned cart reminders

Send a Transactional Message

Send a message to a specific user via email, SMS, or push notification.

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

async function sendTransactional(userId, templateId, channel, variables) {
  const response = await fetch(
    `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/transactional/send`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        user_id: userId,
        template_id: templateId,
        channel: channel,  // 'email', 'sms', or 'push'
        variables: variables
      })
    }
  );

  return response.json();
}

// Example: Order confirmation via push
await sendTransactional('user_123', 'order_confirmation', 'push', {
  order_id: 'ORD-12345',
  total: '$99.99',
  items_count: 3,
  estimated_delivery: 'Jan 25, 2024'
});

def send_transactional(user_id, template_id, channel, variables):
    response = requests.post(
        f'https://api.flameup.ai/api/v1/workspaces/{WORKSPACE_ID}/transactional/send',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {API_KEY}'
        },
        json={
            'user_id': user_id,
            'template_id': template_id,
            'channel': channel,  # 'email', 'sms', or 'push'
            'variables': variables
        }
    )
    return response.json()

# Example: Order confirmation via push
send_transactional('user_123', 'order_confirmation', 'push', {
    'order_id': 'ORD-12345',
    'total': '$99.99',
    'items_count': 3,
    'estimated_delivery': 'Jan 25, 2024'
})

curl -X POST "https://api.flameup.ai/api/v1/workspaces/{workspace_id}/transactional/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "user_id": "user_123",
    "template_id": "order_confirmation",
    "channel": "push",
    "variables": {
      "order_id": "ORD-12345",
      "total": "$99.99",
      "items_count": 3,
      "estimated_delivery": "Jan 25, 2024"
    }
  }'

Request Body

Field	Type	Required	Description
`user_id`	string	Yes	The user's external_id or Flameup person_id
`template_id`	string	Yes	ID of a pre-defined template
`channel`	string	Yes	Channel to send via: `email`, `sms`, or `push`
`variables`	object	No	Variables for template personalization
`subject`	string	No	Override the template subject (email only)
`body`	string	No	Override the template body
`priority`	integer	No	Message priority (0=low, 1=normal, 2=high, 3=urgent)

Response:

{
  "id": "msg_550e8400e29b41d4a716446655440000",
  "status": "sent",
  "channel": "push",
  "created_at": "2024-01-15T10:30:00Z"
}

Common Examples

// Order confirmation
await sendTransactional('user_123', 'order_confirmation', 'push', {
  order_id: 'ORD-12345',
  total: '$99.99'
});

// Shipping notification
await sendTransactional('user_123', 'order_shipped', 'push', {
  tracking_number: '1Z999AA10123456784'
});

// Delivered notification
await sendTransactional('user_123', 'order_delivered', 'push', {
  order_id: 'ORD-12345'
});

// Password reset
await sendTransactional('user_123', 'password_reset', 'email', {
  reset_token: 'abc123xyz'
});

// New login alert
await sendTransactional('user_123', 'new_login_alert', 'push', {
  device: 'Chrome on Windows',
  location: 'New York, US'
});

// 2FA code
await sendTransactional('user_123', 'verification_code', 'sms', {
  code: '847291'
});

// Payment successful
await sendTransactional('user_123', 'payment_received', 'push', {
  amount: '$49.99',
  payment_id: 'pay_abc123'
});

// Payment failed
await sendTransactional('user_123', 'payment_failed', 'push', {
  amount: '$49.99'
});

// Subscription renewal
await sendTransactional('user_123', 'subscription_renewed', 'email', {
  plan: 'Premium',
  amount: '$19.99'
});

// New follower
await sendTransactional('user_123', 'new_follower', 'push', {
  follower_name: 'John Doe',
  follower_id: 'user_456'
});

// New message
await sendTransactional('user_123', 'new_message', 'push', {
  sender_name: 'Jane',
  message_preview: 'Hey, are you free for lunch?',
  chat_id: 'chat_789'
});

// Comment on post
await sendTransactional('user_123', 'new_comment', 'push', {
  commenter_name: 'Mike',
  comment_preview: 'Great point!',
  post_id: 'post_456'
});

Error Handling

Handle these common error cases in your integration.

User Not Found

{
  "success": false,
  "error": {
    "type": "user_not_found",
    "message": "No user found with the provided ID"
  }
}

No Devices Registered

{
  "success": false,
  "error": {
    "type": "no_devices",
    "message": "User has no registered devices for the target platform"
  }
}

Template Not Found

{
  "success": false,
  "error": {
    "type": "template_not_found",
    "message": "Template 'order_confirmation' not found"
  }
}

Handling in Code

async function sendNotification(userId, templateId, channel, variables) {
  try {
    const response = await fetch(
      `${BASE_URL}/workspaces/${WORKSPACE_ID}/transactional/send`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${API_KEY}`
        },
        body: JSON.stringify({
          user_id: userId,
          template_id: templateId,
          channel: channel,
          variables: variables
        })
      }
    );

    const result = await response.json();

    if (!result.id) {
      switch (result.error?.type) {
        case 'user_not_found':
          console.log('User not found in Flameup');
          break;
        case 'no_devices':
          console.log('User has no push-enabled devices');
          break;
        default:
          console.error('Send failed:', result.error?.message);
      }
      return null;
    }

    return result;
  } catch (error) {
    console.error('Network error:', error);
    throw error;
  }
}

Best Practices

Every transactional message should have a clear purpose and action:

Use clear, specific titles
Include relevant details in the body
Provide deep links for quick actions

Was this page helpful?

Built with Documentation.AI

Last updated today