Getting started

HoneyNotify gives your application one API for registering devices, sending push notifications, tracking engagement, and automating follow-up messages across iOS, Android, and the web.

This guide takes you from an empty app to a traceable test notification. You will need a HoneyNotify account, an app in the dashboard, and a device token from APNs, Firebase Cloud Messaging, or a browser Push subscription.

If you want to explore the native integration before building your own app, start with the ready-to-build iOS and Android demo apps. They provide configurable full-screen WebView projects with HoneyNotify registration and notification handling already connected.

The integration in one minute#

Every HoneyNotify integration has two trust zones:

1. Your backend uses a secret server key to send notifications and manage app data.
2. Your mobile or web client uses a restricted public client key to register its push token and report engagement events.

Never place a ps_live_ server key in an app binary, browser bundle, public repository, support ticket, or analytics event. Public clients should only receive a ps_public_ key.

1. Create an app and keys#

Sign in to the HoneyNotify dashboard, create an app, and add the push-provider credentials for each platform you support. Then create:

• a server API key with notifications:write for the code that sends messages;
• a public mobile client key for device registration and event tracking; and
• optionally a read-only server key with notifications:read for reporting tools.

Copy each key when it is shown. Store server keys in your secret manager or environment, not in source control.

export HONEYNOTIFY_API_KEY="ps_live_replace_me"
export HONEYNOTIFY_API_URL="https://api.honeynotify.com"

2. Register a device#

Registration is an upsert: sending the same provider token again refreshes the device details instead of creating a second active device.

curl --request POST "$HONEYNOTIFY_API_URL/v1/devices/register" \
  --header "Authorization: Bearer ps_public_replace_me" \
  --header "Content-Type: application/json" \
  --data '{
    "platform": "ios",
    "push_token": "apns-device-token",
    "external_user_id": "customer_123",
    "locale": "en-GB",
    "timezone": "Europe/London",
    "tags": {
      "plan": "pro",
      "marketing_opt_in": true
    }
  }'

A new registration returns 201 Created; a refresh returns 200 OK.

{
  "device_id": "0e83059e-715d-45b8-911b-30d36519c863",
  "created": true
}

Keep the device_id in the client. It is used for event attribution and for disabling the device when the user logs out or unsubscribes.

3. Send a notification#

Notification creation is asynchronous and requires an Idempotency-Key. Generate a new unique value for each logical send, then reuse that value if your request must be retried.

curl --request POST "$HONEYNOTIFY_API_URL/v1/notifications" \
  --header "Authorization: Bearer $HONEYNOTIFY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-ready-7815-v1" \
  --data '{
    "name": "Order 7815 ready",
    "title": "Your order is ready",
    "body": "Tap to see collection details.",
    "target": {
      "type": "user",
      "external_user_id": "customer_123"
    },
    "click_url": "myapp://orders/7815",
    "data": {
      "order_id": "7815"
    },
    "priority": "transactional",
    "interruption_level": "active"
  }'

An immediate send returns 202 Accepted with a notification UUID.

{
  "notification_id": "b39ddcd7-2892-4c3d-8145-0ce3bc9e3ec4",
  "status": "queued"
}

queued means HoneyNotify accepted the work. It does not mean APNs or FCM accepted every recipient, and provider acceptance does not guarantee that an operating system displayed the notification.

4. Inspect delivery#

Retrieve the notification summary, then inspect recipient-level results or lifecycle events.

curl "$HONEYNOTIFY_API_URL/v1/notifications/b39ddcd7-2892-4c3d-8145-0ce3bc9e3ec4" \
  --header "Authorization: Bearer $HONEYNOTIFY_API_KEY"

curl "$HONEYNOTIFY_API_URL/v1/notifications/b39ddcd7-2892-4c3d-8145-0ce3bc9e3ec4/recipients?page=1&limit=50" \
  --header "Authorization: Bearer $HONEYNOTIFY_API_KEY"

Use the SDK to submit received, confirmed_delivered, opened, clicked, or dismissed events. This separates provider acceptance from what actually happened on the device.

5. Make it production-ready#

• Use identity verification before accepting an external_user_id from an untrusted client.
• Register refreshed APNs/FCM tokens whenever the operating system changes them.
• Track opens from the notification interaction callback, not merely at app launch.
• Treat 429 and 5xx responses as retryable, with backoff and jitter.
• Reuse the original idempotency key when retrying a send.
• Add a signed webhook for delivery or engagement events needed by your backend.
• Use segments or templates for repeatable campaigns rather than rebuilding payloads ad hoc.

Continue with the demo apps, API fundamentals, SDK integration, or the complete API reference.