Send Notifications

This section describes API to send push notifications.

Send Push

To send push notifications.

On success, the endpoint confirms that the notification has been queued and delivery has started. To check the delivery status, use the notificationId from the response with Notification Status endpoint.

Endpoint

POST https://app.mpush.cloud/api/send

Parameters (JSON)

Key	Type	Required	Description
topics	array	Yes	Contains a list of all topics to send the push to.
payload.title	string	No	Notification title.
payload.body	string	Yes	Notification body.
payload.badge	int	No	Badge number.
payload.sound	string	No	Specify the sound path to play when the push arrives.
payload.title_loc_key	string	No	Specify the key to a body string in a localization file for the current locale.
payload.title_loc_args	array	No	Specify the values to appear in place of the format specifiers in title_loc_key.
payload.loc_key	string	No	Specify the key to a title string in a localization file for the current locale.
payload.loc_args	array	No	Specify the values to appear in place of the format specifiers in loc_key.
payload.action_loc_key	string	No	Custom sound to play.
payload.launch_image	string	No	Specify the image path to launch at the app launch.
payload.mutable_content	bool	No	Mutable content (only iOS).
payload.content_available	bool	No	Content available (only iOS).
payload.category	string	No	Specify a category (only iOS).
payload.thread_id	int	No	Specify a thread (only iOS).
payload.collapse_id	int	No	Multiple notifications with the same collapse identifier are displayed to the user as a single notification (only iOS).
payload.expiration_at	int	No	A UNIX timestamp (UTC) that identifies the date when the notification is no longer valid and can be discarded.
payload.custom	object	No	An object containing custom data.

This table is used the "dot" notation to show the payload JSON structure.

For a complete reference to all available values to include in the payload we remand to the official documentation: iOS and Android.

Example

This API requires a JSON payload.

curl https://app.mpush.cloud/api/send
-X POST 
-H "Accept: application/json" 
-H "Content-Type: application/json" 
-H "X-MPush-Token: <token>" 
-H "X-MPush-Token: 2" 
-d '<JSON payload>' 

On success is returned an HTTP 200 and JSON like this:

{
  "notificationId": "18f7c750-5cde-4900-84db-2a863afebb91",
  "status": "accepted",
  "message": "Notification queued for processing"
}

Payload examples

Payload example to send a basic notification:

{
  "topics": ["all"],
  "payload": {
    "body": "Hello"
  }
}

Payload example to send a basic notification to multiple topics with custom badge and sound:

{
  "topics": ["news", "user.12", "user.15"],
  "payload": {
    "title": "News!",
    "body": "Hello",
    "badge": 2,
    "sound": "sound.aiff"
  }
}

Payload example to send a notification with an image:

{
  "topics": ["project.all"],
  "payload": {
    "body": "Message with Image",
    "mutable_content": 1,
    "custom": {
      "media_url": "https://link-to-image.com"
    }
  }
}

Payload example to send a notification with localization:

{
  "topics": ["user.23"],
  "payload": {
    "loc_key": "LOCALIZED_PUSH",
    "loc_args": [
      "Name",
      "Surname"
    ]
  }
}

Notification Status

To retrieve the sending status.

When the status value becomes completed, it means the system has finished sending the notification.

Endpoint

GET https://app.mpush.cloud/api/notifications/<notificationId>

Example:

curl https://app.mpush.cloud/api/notifications/<notificationId>
-H "Accept: application/json" 
-H "X-MPush-Token: <token>" 
-H "X-MPush-Token: 2"

On success is returned an HTTP 200 and JSON like this:

{
  "projectId": 1,
  "failedCount": 10,
  "status": "completed",
  "createdAt": 1764100807728,
  "priority": "normal",
  "totalDevices": 1064,
  "topics": [
    "project.all"
  ],
  "notification": {
    "badge": 1,
    "title": "Title",
    "body": "Message"
  },
  "completedAt": 1764100816175,
  "sentCount": 1054,
  "iosCount": 736,
  "updatedAt": 1764100816141,
  "androidCount": 328,
  "id": "18f7c750-5cde-4900-84db-2a863afebb91"
}