What is the best practice for sending bulk notifications with the createMessage API to avoid timeouts?

When sending a large number of notifications in a single /createMessage API call, you may hit client-side timeout errors. This can happen even when our servers ultimately process the request successfully.

The recommended best practice is to reduce the number of recipients (the batch size) per API request rather than raising your client's timeout.

Why reduce the batch size?

• Faster processing: smaller requests are processed more quickly, which keeps your HTTP client from timing out while waiting for a response.
• Better failure isolation: if one small batch errors out, only that batch is affected. If a single large request fails, everything in it fails.

API limits to respect

• Recipients per request (hard limit): the devices array accepts no more than 1000 tokens/HWIDs, the users array no more than 1000 User IDs, and to (email, SMS and similar channels) no more than 1000 items. Split larger audiences across several requests.
• Request rate: non-enterprise accounts can send at most 600 /createMessage and/or /createTargetedMessage requests per minute. Requests that target 10 devices or fewer via the devices parameter are exempt from this throttle for any account type, as long as API messaging tracing is disabled. Scheduled pushes are always saved to Message History and are therefore always throttled.
• Targeting precedence: if devices is present, filter and conditions are ignored. If users is specified together with devices or to, the latter are ignored.

Batches in the low hundreds of recipients are a good starting point: comfortably under the 1000-item cap and small enough to return quickly.

Note on billing

The number of API requests you make does not affect your billing. Sending the same number of notifications across many small requests costs the same as one large request.