The backend API is used by your SaaS server to send messages and sync your users profiles.

The backend API endpoint is: https://api.notifuse.com/ and the data is sent as JSON.

Wanna play with the API? Run this API collection in Postman​

Authentication

All the following methods require to be authenticated with the Authorization HTTP header and your project API Key like this: Authorization: Bearer YOUR_PROJECT_API_KEY

The project API Key is provided in your projects settings.

Send messages

When you send a message to a user, the required fields are notificationId and userId. If the user you are sending a message to, doesn't exist yet in Notifuse, it will be automatically created. The user profile fields (userEmail, userTelephone...) provided with your message, will update the user profile in Notifuse if missing.

If you don't provide a unique id for your messages, Notifuse will generate one. If you provide an id and you send it many times, an error "id/exists" will be returned for your message.

The endpoint returns the results for each message. If nothing bad happened on the Notifuse side, the ok field will be true.

If an error occurred within Notifuse, the ok field will be false and the error field will be set.

If an error occurred with the email and/or SMS provider, the ok field will still be true but the emailError and/or smsError fields will be set.

POST https://api.notifuse.com/messages.send

{
    "messages": [
        {
            "notificationId": "welcome", // REQUIRED
            "userId": "xxxx", // REQUIRED
            // optional fields
            "data": {}, // JSON payload to customize your templates
            "id": "your-unique-id", // Notifuse will generate one otherwise
            "userEmail": "xxxx@xxxx.com", // Provide an email if the user doesn't exist yet in Notifuse
            "userTelephone": "+44 123456789", // International format
            "userLanguage": "en",
            "userTimezone": "Europe/London",
            "userFirstName": "John",
            "userLastName": "Doe",
            "userPhotoURL": "https://....jpg",
            "userCountry": "GB",
            "incrementId": "xxxx", // Used to increment a counter on similar notifications to avoid spamming your users.
            
            // Override template settings at the message level
            "widgetSettingsOverride": {
                "iconURL": "https://..." // widget notification icon
            },
            "emailSettingsOverride": {
                "replyTo": "email@gmail.com", // replyTo email address
                "cc": "email1@gmail.com,email2@gmail.com", // CC emails separated by a comma
                "bcc": "email1@gmail.com,email2@gmail.com" // BCC emails separated by a comma
            }
        },
        ...
    ]
}

{
    "code": 200,
    "results": [
        {"id": "xxxx", "ok": true, "stackIncremented": false},
        {"id": "xxxx", "ok": false, "stackIncremented": false, "error": "notificationId/invalid"},
        {"id": "xxxx", "ok": true, "stackIncremented": false, "emailError": "Your sending address is blacklisted."},
        ...
    ]
}

Insert / Update users

It is important to import your contacts (= users) into Notifuse before sending notifications so you can avoid attaching the user profile fields (userEmail, userLanguage etc...) when you send messages (see Send Message).

This endpoint will create the user profiles if they don't exist yet or update them with missing fields.

POST https://api.notifuse.com/users.upsert

{
    "users": [
        {
            "id": "your-user-unique-id",
            "email": "xxxx@xxxx.com",
            "telephone": "+44 123456789", // International format
            "language": "en",
            "timezone": "Europe/London",
            "firstName": "John",
            "lastName": "Doe",
            "photoURL": "https://....jpg",
            "country": "GB"
        },
        ...
    ]
}

{
    "code": 200,
    "users": [
        {"id": "xxxx", "ok": true},
        {"id": "xxxx", "ok": false, "error": "country/invalid"}
        ...
    ]
}

​