Notifuse
Search…
Notifuse
What is Notifuse
Quick start
Concepts
Platform overview
Contacts
Templates
Integration
Widget 🔔
Backend API
Frontend API
Powered By GitBook
Backend API
The backend API is used by your SaaS server to send messages and sync your users profiles.
In Notifuse, a notification is not a message, it defines which channels the messages will be sent to and contains templates for each language.
When you want to notify your users, you will actually send a message.
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.
The messages.send endpoint accepts a batch of 50 messages max. Messages will be processed in parallel, and emails/sms are sent synchronously.
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
Request payload
Response
1
{
2
"messages": [
3
{
4
"notificationId": "welcome", // REQUIRED
5
"userId": "xxxx", // REQUIRED
6
// optional fields
7
"data": {}, // JSON payload to customize your templates
8
"id": "your-unique-id", // Notifuse will generate one otherwise
9
"userEmail": "[email protected]", // Provide an email if the user doesn't exist yet in Notifuse
10
"userTelephone": "+44 123456789", // International format
11
"userLanguage": "en",
12
"userTimezone": "Europe/London",
13
"userFirstName": "John",
14
"userLastName": "Doe",
15
"userPhotoURL": "https://....jpg",
16
"userCountry": "GB",
17
"incrementId": "xxxx", // Used to increment a counter on similar notifications to avoid spamming your users.
18
19
// Override template settings at the message level
20
"widgetSettingsOverride": {
21
"iconURL": "https://..." // widget notification icon
22
},
23
"emailSettingsOverride": {
24
"subject": "Hello {{ firstName }}", // overrided subject for this message
25
"replyTo": "[email protected]", // replyTo email address
26
"cc": "[email protected],[email protected]", // CC emails separated by a comma
27
"bcc": "[email protected],[email protected]" // BCC emails separated by a comma
28
}
29
},
30
...
31
]
32
}
Copied!
1
{
2
"code": 200,
3
"results": [
4
{"id": "xxxx", "ok": true, "stackIncremented": false},
5
{"id": "xxxx", "ok": false, "stackIncremented": false, "error": "notificationId/invalid"},
6
{"id": "xxxx", "ok": true, "stackIncremented": false, "emailError": "Your sending address is blacklisted."},
7
...
8
]
9
}
Copied!
Message fields
Type
Description
notificationId
String - Required
The notification ID
userId
String - Required
The user ID
data
JSON object
A JSON object that contains the data required to customize your templates.
id
String
Unique message ID. Notifuse will generate one otherwise.
incrementId
String
Increment ID used to increment similar notifications instead of spamming your user. When the stack timeout is passed, a new message is created.
userEmail
String
Provide an email if your notification is sent by email and the user profile doesn't exist yet in Notifuse.
userTelephone
String
Provide a mobile phone number in international format if your notification is sent by SMS and the user profile doesn't exist yet in Notifuse.
userLanguage
String
User preferred language for notifications.
userTimezone
String
User preferred timezone for scheduled notifications.
userFirstName
String
User first name, in case the user profile doesn't exist yet in Notifuse.
userLastName
String
User last name, in case the user profile doesn't exist yet in Notifuse.
userPhotoURL
String
User photo URL, in case the user profile doesn't exist yet in Notifuse.
userCountry
String
User country in ISO format (US, GB, FR...), in case the user profile doesn't exist yet in Notifuse.
widgetSettingsOverride
Object
Object of widget template settings to override.
emailSettingsOverride
Object
Object of email template settings to override.

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.
This endpoint will create the user profiles if they don't exist yet or update them with missing fields. It accepts a batch of 100 users max.
POST https://api.notifuse.com/users.upsert
Request payload
Response
1
{
2
"users": [
3
{
4
"id": "your-user-unique-id",
5
"email": "[email protected]",
6
"telephone": "+44 123456789", // International format
7
"language": "en",
8
"timezone": "Europe/London",
9
"firstName": "John",
10
"lastName": "Doe",
11
"photoURL": "https://....jpg",
12
"country": "GB"
13
},
14
...
15
]
16
}
Copied!
1
{
2
"code": 200,
3
"users": [
4
{"id": "xxxx", "ok": true},
5
{"id": "xxxx", "ok": false, "error": "country/invalid"}
6
...
7
]
8
}
Copied!
​
Integration - Previous
Widget 🔔
Next - Integration
Frontend API
Last modified 24d ago
Copy link
Contents
Authentication
Send messages
Insert / Update users