Messaging

Messaging APIs

Send push notifications and emails to your users

Overview

Flameup provides APIs to send messages directly to your users. Use these for transactional notifications triggered by user actions like order confirmations, password resets, and account alerts.

Push Notifications

Send to iOS and Android devices via FCM

Send transactional emails via Resend

SMS (Coming Soon)

Send text messages via Twilio

Push Notifications

Send push notifications to a user's registered devices.

Required: User must have a registered device token. See Devices API for registration.

Send Push Notification

Endpoint: POST /api/v1/push/send

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

  return response.json();
}

// Example: Order confirmation
await sendPush('550e8400-e29b-41d4-a716-446655440000',
  'Order Confirmed!',
  'Your order #ORD-12345 has been confirmed. Total: $99.99',
  {
    action_url: 'myapp://orders/ORD-12345',
    ios_badge: 1
  }
);

import requests

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

# Example: Order confirmation
send_push(
    '550e8400-e29b-41d4-a716-446655440000',
    'Order Confirmed!',
    'Your order #ORD-12345 has been confirmed. Total: $99.99',
    action_url='myapp://orders/ORD-12345',
    ios_badge=1
)

curl -X POST "https://api.flameup.ai/api/v1/push/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Order Confirmed!",
    "body": "Your order #ORD-12345 has been confirmed. Total: $99.99",
    "action_url": "myapp://orders/ORD-12345",
    "ios_badge": 1
  }'

Request Body

Field	Type	Required	Description
`person_id`	string	Yes	Flameup person UUID
`title`	string	Yes	Notification title (max 255 chars)
`body`	string	Yes	Notification body text
`platform`	string	No	Target platform: `ios`, `android`, or `all` (default). Web coming soon.
`image_url`	string	No	URL for rich notification image
`action_url`	string	No	Deep link URL when notification is tapped
`priority`	string	No	Delivery priority: `low`, `normal`, `high`
`ttl`	integer	No	Time to live in seconds
`custom_data`	object	No	Custom key-value payload for your app

iOS Options

Field	Type	Description
`ios_badge`	integer	App badge count
`ios_sound`	string	Notification sound (e.g., `default`)
`ios_category`	string	Action category for interactive notifications

Android Options

Field	Type	Description
`android_channel_id`	string	Notification channel ID
`android_icon`	string	Notification icon resource name
`android_color`	string	Icon color (e.g., `#FF0000`)
`android_sound`	string	Notification sound

Response

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

Field	Description
`message_id`	Flameup message ID
`status`	`pending`, `sent`, `delivered`, or `failed`
`sent_at`	Timestamp when sent
`provider`	Push provider used (`fcm`)
`provider_id`	External message ID from provider
`error`	Error message (only if failed)

Push Notification Examples

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

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

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

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

// Password changed
await sendPush(personId, 'Password Changed',
  'Your password was changed. If this wasn\'t you, contact support.', {
    priority: 'high'
});

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

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

// New follower
await sendPush(personId, '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(personId, 'New message from Jane',
  'Hey, are you free for lunch?', {
    action_url: 'myapp://chat/chat_789',
    ios_badge: 5
});

Email

Send transactional emails to your users.

Send Email

Endpoint: POST /api/v1/messaging/send-email

async function sendEmail(to, subject, htmlBody, textBody) {
  const response = await fetch(
    'https://api.flameup.ai/api/v1/messaging/send-email',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        workspaceId: WORKSPACE_ID,
        to: Array.isArray(to) ? to : [to],
        subject: subject,
        htmlBody: htmlBody,
        textBody: textBody
      })
    }
  );

  return response.json();
}

// Example: Password reset email
await sendEmail(
  'user@example.com',
  'Reset Your Password',
  '<h1>Password Reset</h1><p>Click <a href="https://myapp.com/reset?token=abc123">here</a> to reset your password.</p>',
  'Click this link to reset your password: https://myapp.com/reset?token=abc123'
);

def send_email(to, subject, html_body, text_body=None):
    response = requests.post(
        'https://api.flameup.ai/api/v1/messaging/send-email',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {API_KEY}'
        },
        json={
            'workspaceId': WORKSPACE_ID,
            'to': to if isinstance(to, list) else [to],
            'subject': subject,
            'htmlBody': html_body,
            'textBody': text_body
        }
    )
    return response.json()

# Example: Password reset email
send_email(
    'user@example.com',
    'Reset Your Password',
    '<h1>Password Reset</h1><p>Click <a href="https://myapp.com/reset?token=abc123">here</a>.</p>',
    'Click this link to reset your password: https://myapp.com/reset?token=abc123'
)

curl -X POST "https://api.flameup.ai/api/v1/messaging/send-email" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "workspaceId": "your_workspace_id",
    "to": ["user@example.com"],
    "subject": "Reset Your Password",
    "htmlBody": "<h1>Password Reset</h1><p>Click <a href="https://myapp.com/reset?token=abc123">here</a>.</p>",
    "textBody": "Click this link to reset your password: https://myapp.com/reset?token=abc123"
  }'

Request Body

Field	Type	Required	Description
`workspaceId`	string	Yes	Your workspace ID
`to`	array	Yes	Array of recipient email addresses
`subject`	string	Yes	Email subject line
`htmlBody`	string	No	HTML email body
`textBody`	string	No	Plain text email body
`from`	string	No	Sender email address
`replyTo`	string	No	Reply-to email address

At least one of htmlBody or textBody must be provided.

Response

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Email sent successfully",
  "provider": "resend"
}

Error Handling

Handle these common error cases in your integration.

Push Errors

{
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "No valid device tokens found for user"
}

Common push errors:

No device tokens registered for user
Invalid or expired device token
FCM configuration missing for workspace

Email Errors

{
  "success": false,
  "error": "Invalid recipient email address"
}

Common email errors:

Invalid email format
Email provider configuration missing
Rate limit exceeded

Handling in Code

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

    if (result.status === 'failed') {
      console.error('Push failed:', result.error);
      // Fallback to email or in-app notification
      return null;
    }

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

Best Practices

The Push API requires the Flameup person_id (UUID), not your external user ID. Look up the person first or store the person_id when you create users:

// When creating a user, store the person_id
const person = await createPerson({ userId: 'user_123', ... });
// Save person.id for later push notifications

Was this page helpful?

Last updated 4 weeks ago

Built with Documentation.AI