Skip to main content

Configurable spend limits

Messaging profiles can be configured to limit the cost induced by sending messages from numbers attached to that profile in a day. This feature can be useful for preventing undesired spending due to e.g. bugs in your application, unexpected usage, human error, etc.

Note that there may be a short delay between the limit being reached and the limit being enforced; it may be possible to send additional messages over the spend limit during that period of time.

Set up the feature ​

To make use of this feature, the daily_spend_limit_enabled field of the desired messaging profile must be set to true and the daily_spend_limit field must be set to the desired quoted unitless decimal value in USD (for example: "0.12", "1", "1.23"). This can be done when creating a new messaging profile or when updating an existing one.

Here's an example curl command that will enable this feature and set a spend limit of 10.00 USD on an existing messaging profile:

curl -X PATCH https://api.telnyx.com/v2/messaging_profile/YOUR-PROFILE-ID-HERE \
  -H 'Authorization: Bearer YOUR-TOKEN-HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "daily_spend_limit_enabled": true,
    "daily_spend_limit": "10.00"
  }'

Of course, you'll need to replace YOUR-PROFILE-ID-HERE and YOUR-TOKEN-HERE with appropriate values.

When the limit is reached ​

Once enough messages are sent so that total spend for that profile exceeds the configured limit, Telnyx will begin rejecting outbound message API requests with an HTTP status code of 429 and the following response body:

{
  "errors": [
    {
      "code": "40333",
      "title": "Messaging profile spend limit reached",
      "detail": "The daily spend limit configured on this messaging profile has been reached",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/40333"
      }
    }
  ]
}

You will also be notified via an email and a webhook when a limit is reached. Here's an example webhook body:

{
  "data": {
    "event_type": "messaging-profile.spend-limit-reached",
    "id": "d21a2887-8007-4bb6-bd7d-f2874829918e",
    "occurred_at": "2024-08-20T19:17:08.918+00:00",
    "payload": {
      "configured_limit": "0.01",
      "current_cost": "0.02",
      "profile_id": "be3eb60a-a346-470a-886c-ab4e421711bd"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://example.com/webhook-url"
  }
}

Resetting and overriding a reached limit ​

At midnight UTC, the running total of spend will reset, and outbound messages can be sent until the limit is exceeded again. This is the only way the running total can be reset; changes to the daily_spend_limit and daily_spend_limit_enabled values will not reset the running total.

If you've reached the limit and are no longer able to send messages as a result, but want to temporarily override the limit to send a few more, you can set daily_spend_limit_enabled to false, send your additional messages, and then set it back to true so further messages will be rejected again. Another option is to increase the value of daily_spend_limit to a new desired maximum; once the new value is reached, further messages will be rejected again.