Batch Single Push API

Last updated：2025-06-30

Batch Single Push API

Function Description

Used for batch single push messages, allowing multiple target users to receive pushes in one call. Supports pushing via registration_id or alias:

Push via registration_id: POST /v4/batch/push/regid
Push via alias: POST /v4/batch/push/alias
Capability Limits:
- Maximum 500 push targets per request
- Supports concurrent processing for efficiency
- Returns partial success results during rate limiting
- This API and the Push API share the same QPS quota. Using the batch push API to push 1 regid or 1 alias consumes 1 QPS quota of the Push API.

Authentication

Add authentication field in HTTP Header:

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

This code block in the floating window

Generation method: base64(username:password)
- username = Application AppKey
- password = Master Secret
Access path: Console → Application Settings → Application Info

Endpoints

Batch push via registration_id

POST /v4/batch/push/regid

              
              POST /v4/batch/push/regid

This code block in the floating window

Batch push via alias

POST /v4/batch/push/alias

              
              POST /v4/batch/push/alias

This code block in the floating window

Request Examples

1. Batch push via registration_id

curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "registration_id_1", "platform": "android", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android", "builder_id": 1, "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false }, "custom_args": { "business": "info" } }, { "target": "registration_id_2", "platform": "ios", "notification": { "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \  
  -H "Content-Type: application/json" \  
  -u "AppKey:MasterSecret" \  
  -d '{  
    "requests": [  
      {  
        "target": "registration_id_1",  
        "platform": "android",  
        "notification": {  
          "android": {  
            "alert": "Hi, Push!",  
            "title": "Send to Android",  
            "builder_id": 1,  
            "extras": { "newsid": 321 
            }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        },  
        "custom_args": { "business": "info" }  
      },  
      {  
        "target": "registration_id_2",  
        "platform": "ios",  
        "notification": {  
          "ios": {  
            "alert": "Hi, MTPush!",  
            "sound": "default",  
            "badge": "+1",  
            "extras": { "newsid": 321 
            }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      }  
    ]  
  }'

This code block in the floating window

2. Batch push via alias

curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "user_alias_1", "platform": "all", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android" }, "ios": { "alert": "Hi, MTPush!", "sound": "default" } }, "options": { "time_to_live": 60, "apns_production": false } }, { "target": "user_alias_2", "platform": "ios", "notification": { "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \  
  -H "Content-Type: application/json" \  
  -u "AppKey:MasterSecret" \  
  -d '{  
    "requests": [  
      {  
        "target": "user_alias_1",  
        "platform": "all",  
        "notification": {  
          "android": { "alert": "Hi, Push!", "title": "Send to Android" },  
          "ios": { "alert": "Hi, MTPush!", "sound": "default" }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      },  
      {  
        "target": "user_alias_2",  
        "platform": "ios",  
        "notification": {  
          "ios": {  
            "alert": "Hi, MTPush!",  
            "sound": "default",  
            "badge": "+1",  
            "extras": { "newsid": 321 }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      }  
    ]  
  }'

This code block in the floating window

Request Parameters

Request body structure:

{ "requests": [ { "target": "string", // Required, push target (registration_id or alias) "platform": "string", // Required, push platform (android/ios/all) "notification": "object", // Optional, notification content (refer to Push API) "message": "object", // Optional, custom message (refer to Push API), cannot coexist with notification "options": "object", // Optional, push options (refer to Push API) "custom_args": "object" // Optional, parameters passed to client } ] }

              
              {  
  "requests": [  
    {  
      "target": "string",     // Required, push target (registration_id or alias)  
      "platform": "string",   // Required, push platform (android/ios/all)  
      "notification": "object",  // Optional, notification content (refer to Push API)  
      "message": "object",     // Optional, custom message (refer to Push API), cannot coexist with notification  
      "options": "object",     // Optional, push options (refer to Push API)  
      "custom_args": "object"  // Optional, parameters passed to client  
    }  
  ]  
}

This code block in the floating window

Parameter descriptions:

Field	Required	Type	Description
`requests`	Yes	array	Batch request array (max 500 items, `target` must be unique per batch)
`target`	Yes	string	Target value: - `/regid` endpoint: `registration_id` - `/alias` endpoint: `alias`
`platform`	Yes	string	Push platform: `android`, `ios`, or `all`
`notification`	No	object	Notification content (same structure as single push API)
`message`	No	object	Custom message (same structure as single push API)
`options`	No	object	Push options (e.g. `time_to_live`, `apns_production`)
`custom_args`	No	object	Custom passthrough parameters

Response Examples

Successful response (all succeeded)

{ "results": { "registration_id_1": { "target": "registration_id_1", "success": true, "msg_id": 2460001 }, "registration_id_2": { "target": "registration_id_2", "success": true, "msg_id": 2460002 } } }

              
              {
  "results": {
    "registration_id_1": {
      "target": "registration_id_1",
      "success": true,
      "msg_id": 2460001
    },
    "registration_id_2": {
      "target": "registration_id_2",
      "success": true,
      "msg_id": 2460002
    }
  }
}

This code block in the floating window

Successful response (partial rate limiting)

{ "rate_limit_info": { "message": "Some requests were rate limited during batch processing", "rate_limit_occurred": true }, "results": { "170976fa8a0771c2647": { "target": "170976fa8a0771c2647", "success": false, "error": { "code": 23008, "message": "Rate limit exceeded for the API" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": false, "error": { "code": 23008, "message": "Rate limit exceeded for the API" } } } }

              
              {
    "rate_limit_info": {
        "message": "Some requests were rate limited during batch processing",
        "rate_limit_occurred": true
    },
    "results": {
        "170976fa8a0771c2647": {
            "target": "170976fa8a0771c2647",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Rate limit exceeded for the API"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Rate limit exceeded for the API"
            }
        }
    }
}

This code block in the floating window

Failed response (global error)

{ "error": { "code": 21004, "message": "basic auth failed" } }

              
              {  
  "error": {  
    "code": 21004,  
    "message": "basic auth failed"  
  }  
}

This code block in the floating window

Failed response (parameter error)

{ "error": { "code": 21003, "message": "Parameter value is invalid" } }

              
              {  
  "error": {  
    "code": 21003,  
    "message": "Parameter value is invalid"  
  }  
}

This code block in the floating window

Error Code Reference

Error Code	Description	Resolution	HTTP Status
Global Error Codes
21004	Basic authentication failed	Check AppKey/MasterSecret	401
21008	AppKey length is not 24 characters	Verify AppKey format	400
21038	No push permission for the app	Check app configuration	400
21043	No push permission (pending payment)	Resolve billing issue	400
23009	IP not in allowlist	Add server IP to allowlist	400
21009	Internal system error (do not retry)	Contact technical support	400
Rate Limit Errors
23008	API rate limit reached	Retry failed items if partial success	400
Parameter Errors
21003	Invalid parameter value	Check request body format	400
21015	Invalid request parameters	Validate required fields	400
21016	Parameter validation failed	Check field types and value ranges	400

Full error codes: Create Push API - Response

Notes

Rate Limit Handling: Returns partial success results during rate limiting (msg_id for succeeded + error for failed).
Duplicate Check: All target or cid values must be unique within a batch.
Quantity Limit: Maximum 500 targets per request.
Error Handling: Global errors (e.g. auth failure) immediately terminate without partial results.