Send Push Notification API

Send push notifications to specific recipients, contacts, tags, segments, or all contacts. Supports rich notifications with images, action buttons, and deep links.

Setup Required

Before sending push notifications, you must complete Push Setup - configure FCM/APNS credentials and register device tokens.

Endpoint

POST /api/v1/push/send

Headers

X-API-Key: sk_live_your_api_key
Content-Type: application/json

Quick Example

curl -X POST https://api.sendmator.com/api/v1/push/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Order Received!",
    "body": "You have a new order #12345",
    "recipient_type": "direct_push",
    "direct_device_token": "your-fcm-device-token",
    "click_action": "myapp://orders/12345"
  }'

Request Parameters

Required Fields

Field	Type	Description
`title`	string	Push notification title (required if not using template)
`body`	string	Push notification body/message (required if not using template)
`recipient_type`	string	How to target recipients: `direct_push`, `contact`, `tag`, `segment`, `all`

OR use a template:

Field	Type	Description
`template_id`	string	Push template UUID (alternative to title/body)
`template_key`	string	Push template key (alternative to title/body)
`recipient_type`	string	How to target recipients

Recipient-Specific Fields

Recipient Type	Required Field	Type	Description
`direct_push`	`direct_device_token`	string	FCM device token for the target device
`direct_push`	`direct_platform`	string	Platform: `android` or `ios` (optional)
`contact`	`contact_external_id`	string	External ID of the contact
`tag`	`tag`	string[]	Array of tags to match
`segment`	`segment_id`	string	Segment UUID
`all`	(none)	-	Sends to all active contacts with push enabled

Optional Fields for Direct Push

Field	Type	Description
`direct_first_name`	string	Recipient's first name (for personalization)
`direct_last_name`	string	Recipient's last name (for personalization)
`direct_platform`	string	Platform: `android` or `ios`

Rich Notification Fields

Field	Type	Description
`image_url`	string	Image URL for rich push notifications
`click_action`	string	Deep link or URL to open when clicked
`actions`	array	Action buttons (max 3 for Android, max 4 for iOS)
`custom_data`	object	Custom data payload for the app

Action Button Format

{
  "actions": [
    {
      "title": "View Order",
      "action": "myapp://orders/12345",
      "icon": "ic_shopping_cart"
    },
    {
      "title": "Dismiss",
      "action": "dismiss"
    }
  ]
}

Common Optional Fields

Field	Type	Description
`variables`	object	Template variables (key-value pairs)
`metadata`	object	Custom tracking data
`scheduled_at`	string	ISO 8601 UTC timestamp for scheduled send
`message_category`	string	`transactional` (default) or `promotional`
`campaign_name`	string	Campaign name for tracking
`push_identity_id`	string	Push identity UUID (defaults to team default)

Complete Examples

1. Send Direct Push Notification

Send to a specific device token:

curl -X POST https://api.sendmator.com/api/v1/push/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Message",
    "body": "You have a new message from John",
    "recipient_type": "direct_push",
    "direct_device_token": "dGpU7N...:APA91bF...",
    "direct_platform": "android",
    "image_url": "https://example.com/avatar.png",
    "click_action": "myapp://messages/123"
  }'

Response:

{
  "success": true,
  "trigger_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "123",
  "message": "Push notification queued successfully"
}

Use Cases:

Real-time chat notifications
One-time alerts
Direct device messaging
Testing push notifications

2. Send to Contact with Action Buttons

Send to a specific contact with interactive buttons:

curl -X POST https://api.sendmator.com/api/v1/push/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Order Delivered!",
    "body": "Your order #12345 has been delivered",
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "image_url": "https://example.com/package.png",
    "actions": [
      {
        "title": "View Order",
        "action": "myapp://orders/12345"
      },
      {
        "title": "Leave Review",
        "action": "myapp://reviews/new"
      }
    ],
    "custom_data": {
      "order_id": "12345",
      "notification_type": "delivery_confirmation"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "abc123-def456-ghi789",
  "job_id": "124",
  "message": "Push notification queued successfully"
}

Use Cases:

Order updates with quick actions
Interactive notifications
Multi-action alerts
App engagement

Auto-populated Variables: When sending to a contact, their data is automatically available:

{{contact_first_name}} - Contact's first name
{{contact_last_name}} - Contact's last name
{{contact_email}} - Contact's email
{{contact_external_id}} - Contact's external ID

3. Send to Tagged Contacts with Template

Send using a pre-created template to specific segments:

curl -X POST https://api.sendmator.com/api/v1/push/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "flash_sale",
    "recipient_type": "tag",
    "tag": ["premium", "vip"],
    "variables": {
      "discount": "40%",
      "end_time": "6 PM today"
    },
    "click_action": "myapp://sale",
    "message_category": "promotional"
  }'

Response:

{
  "success": true,
  "trigger_id": "pqr901-stu234-vwx567",
  "job_id": "125",
  "message": "Push notification queued successfully"
}

Use Cases:

Flash sales
VIP promotions
Segment-specific campaigns
Time-limited offers

4. Send to All Users

Broadcast to all active users with push enabled:

curl -X POST https://api.sendmator.com/api/v1/push/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "System Maintenance Tonight",
    "body": "App will be offline from 2-3 AM for updates",
    "recipient_type": "all",
    "image_url": "https://example.com/maintenance.png",
    "message_category": "transactional"
  }'

Response:

{
  "success": true,
  "trigger_id": "xyz789-abc123-mno456",
  "job_id": "126",
  "message": "Push notification queued successfully"
}

Use Cases:

System announcements
Emergency alerts
App-wide updates
Maintenance notifications

5. Scheduled Push Notification

Schedule a push notification for future delivery:

curl -X POST https://api.sendmator.com/api/v1/push/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Reminder: Meeting in 1 hour",
    "body": "Team standup at 2:00 PM",
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "click_action": "myapp://calendar/event123",
    "scheduled_at": "2026-03-20T13:00:00Z"
  }'

Response:

{
  "success": true,
  "trigger_id": "lmn012-opq345-rst678",
  "job_id": "127",
  "message": "Push notification scheduled successfully",
  "scheduled_for": "2026-03-20T13:00:00Z",
  "delay_ms": 3600000
}

Use Cases:

Meeting reminders
Event notifications
Time-zone specific sends
Scheduled alerts

6. Rich Notification with Custom Data

Send a rich notification with custom payload:

curl -X POST https://api.sendmator.com/api/v1/push/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment Received",
    "body": "You received $50.00 from Alice",
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "image_url": "https://example.com/money.png",
    "click_action": "myapp://transactions/789",
    "actions": [
      {
        "title": "View Details",
        "action": "myapp://transactions/789"
      },
      {
        "title": "Send Back",
        "action": "myapp://send-money?recipient=alice"
      }
    ],
    "custom_data": {
      "transaction_id": "789",
      "amount": 50.00,
      "sender": "alice",
      "type": "payment_received"
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "def456-ghi789-jkl012",
  "job_id": "128",
  "message": "Push notification queued successfully"
}

Use Cases:

Payment notifications
Transaction alerts
Financial updates
App-specific actions

Response Format

Success Response (201 Created)

{
  "success": true,
  "trigger_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "123",
  "message": "Push notification queued successfully"
}

Field	Type	Description
`success`	boolean	Always `true` for successful requests
`trigger_id`	string	Unique ID to track this send operation
`job_id`	string	Job queue ID for monitoring
`message`	string	Human-readable status message

Error Responses

Missing Required Fields (400)

{
  "statusCode": 400,
  "message": [
    "title should not be empty",
    "body should not be empty"
  ],
  "error": "Bad Request"
}

Invalid Device Token (400)

{
  "statusCode": 400,
  "message": "Invalid FCM device token format",
  "error": "Bad Request"
}

Contact Not Found (404)

{
  "statusCode": 404,
  "message": "Contact with external_id 'user-123' not found",
  "error": "Not Found"
}

No Push Tokens Available (400)

{
  "statusCode": 400,
  "message": "No valid push tokens found for the selected recipients",
  "error": "Bad Request"
}

Push Notification Features

Platform Support

Feature	Android	iOS	Web
Basic notifications	✅	✅	✅
Rich images	✅	✅	✅
Action buttons	✅ (max 3)	✅ (max 4)	✅ (max 2)
Sound	✅	✅	✅
Badge count	✅	✅	❌
Custom data	✅	✅	✅

Message Categories

Category	Description	Queue	Use Cases
transactional	High priority, instant delivery	Priority queue	OTPs, alerts, confirmations
promotional	Normal priority, rate-limited	Normal queue	Marketing, updates, offers

Deep Links

Use deep links to navigate users to specific app screens:

App Deep Links

{
  "click_action": "myapp://orders/12345"
}

Web URLs

{
  "click_action": "https://example.com/products/123"
}

Universal Links (iOS)

{
  "click_action": "https://example.com/app/orders/12345"
}

Best Practices

1. Keep Titles and Bodies Concise

# ✅ Good: Short and clear
{
  "title": "New Order",
  "body": "Order #12345 confirmed"
}

# ❌ Avoid: Too long, gets truncated
{
  "title": "Congratulations! Your order has been successfully placed",
  "body": "We are pleased to inform you that your order number 12345..."
}

Recommended Lengths:

Title: 10-15 words (65 characters max)
Body: 30-40 words (240 characters max)

2. Use Rich Media Appropriately

# ✅ Good: Relevant image
{
  "title": "Your package arrived",
  "image_url": "https://cdn.example.com/package.png"
}

# ⚠️ Be cautious: Large images slow delivery
# Keep images under 1MB for best performance

3. Provide Clear Actions

# ✅ Good: Clear, actionable buttons
{
  "actions": [
    { "title": "View", "action": "myapp://order/123" },
    { "title": "Track", "action": "myapp://tracking/123" }
  ]
}

# ❌ Avoid: Vague or too many actions
{
  "actions": [
    { "title": "Click here", "action": "..." },
    { "title": "More info", "action": "..." },
    { "title": "Settings", "action": "..." },
    { "title": "Help", "action": "..." }
  ]
}

4. Test Across Platforms

# Test on all target platforms
{
  "recipient_type": "tag",
  "tag": ["internal-qa-team"]
}

Different platforms render notifications differently:

Android: Test on different manufacturers (Samsung, Google, etc.)
iOS: Test on different iOS versions
Web: Test on different browsers

5. Respect User Preferences

Only send to users who haven't disabled push
Sendmator automatically filters opted-out users
Use transactional category for important updates
Use promotional category for marketing (users can disable)

Custom Data Payload

Pass custom data to your app for handling notification actions:

{
  "custom_data": {
    "screen": "order_details",
    "order_id": "12345",
    "tab": "tracking",
    "analytics_event": "push_order_delivered"
  }
}

Your app can then read this data and:

Navigate to specific screens
Pre-populate forms
Trigger analytics events
Handle custom logic

Multi-Channel Messages

To send messages across multiple channels (Email, SMS, WhatsApp, Push) simultaneously, use the Multi-Channel Trigger API instead of /push/send.

Next Steps

Create Push Templates - Set up reusable push templates
Manage Device Tokens - Handle device registration
Multi-Channel API - Send across multiple channels
API Overview - Explore other endpoints

Endpoint​

Headers​

Quick Example​

Request Parameters​

Required Fields​

Recipient-Specific Fields​

Optional Fields for Direct Push​

Rich Notification Fields​

Action Button Format​

Common Optional Fields​

Complete Examples​

1. Send Direct Push Notification​

2. Send to Contact with Action Buttons​

3. Send to Tagged Contacts with Template​

4. Send to All Users​

5. Scheduled Push Notification​

6. Rich Notification with Custom Data​

Response Format​

Success Response (201 Created)​

Error Responses​

Missing Required Fields (400)​

Invalid Device Token (400)​

Contact Not Found (404)​

No Push Tokens Available (400)​

Push Notification Features​

Platform Support​

Message Categories​

Deep Links​

App Deep Links​

Web URLs​

Universal Links (iOS)​

Best Practices​

1. Keep Titles and Bodies Concise​

2. Use Rich Media Appropriately​

3. Provide Clear Actions​

4. Test Across Platforms​

5. Respect User Preferences​

Custom Data Payload​

Multi-Channel Messages​

Next Steps​

Endpoint

Headers

Quick Example

Request Parameters

Required Fields

Recipient-Specific Fields

Optional Fields for Direct Push

Rich Notification Fields

Action Button Format

Common Optional Fields

Complete Examples

1. Send Direct Push Notification

2. Send to Contact with Action Buttons

3. Send to Tagged Contacts with Template

4. Send to All Users

5. Scheduled Push Notification

6. Rich Notification with Custom Data

Response Format

Success Response (201 Created)

Error Responses

Missing Required Fields (400)

Invalid Device Token (400)

Contact Not Found (404)

No Push Tokens Available (400)

Push Notification Features

Platform Support

Message Categories

Deep Links

App Deep Links

Web URLs

Universal Links (iOS)

Best Practices

1. Keep Titles and Bodies Concise

2. Use Rich Media Appropriately

3. Provide Clear Actions

4. Test Across Platforms

5. Respect User Preferences

Custom Data Payload

Multi-Channel Messages

Next Steps