Messaging Opted-out Numbers

If you attempt to send a message to a number which has opted out of receiving messages from the number you are sending from, the message will be blocked from sending, and you will receive an error response in the Delivery Receipt (SMS API) or Status Webhook (Messages API).

SMS API

If you attempt to send an SMS message via the SMS API where the number set as the to number has opted out of receiving messages from the number set as from, you should initially receive an HTTP response with a status code of 200, and status field in the response body with a value of 0. This indicates that the message has been successfully submitted for delivery. However, you should subsequently receive a POST request to the webhook address that you set to receive delivery receipts. The body of the request will contain a status field with a value of failed or rejected, and an err-code field with a value of 9. This error code indicates that the user has requested not to receive messages from the sending number.

Example Delivery Receipt Body

{
   "msisdn": "447700900000",
   "to": "AcmeInc",
   "network-code": "12345",
   "messageId": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "price": "0.00000000",
   "status": "failed",
   "scts": "2001011400",
   "err-code": "9",
   "api-key": "abcd1234",
   "message-timestamp": "2020-01-01 12:00:00"
}

Messages API

If you attempt to send an SMS or MMS message via the Messages API where the number set as a the to number has opted out of receiving messages from the number set as from, you should initially receive an HTTP response with a status code of 202, and message_uuid field in the response body with a value for the unique UUID of the message. This indicates that the message has been successfully submitted for delivery. However, you should subsequently receive a POST request to the webhook address that you set to receive status webhooks. The body of the request will contain a message_uuid field with a value identical to the UUID in the initial HTTP response. The request body will also contain a status field with a value of rejected an error field containing an object with details of why the message was rejected. In this case the object should have a title field error code of 1240. This indicates that the user has requested not to receive messages from the sending number.

Example Message Status Webhook Body

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "to": "447700900000",
   "from": "447700900001",
   "timestamp": {},
   "status": "rejected",
   "error": {
      "type": "https://developer.vonage.com/api-errors/messages-olympus#1240",
      "title": 1240,
      "detail": "Illegal Number - You tried to send a message to a blocklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you.",
      "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0000"
   },
   "client_ref": "string",
   "channel": "sms",
   "destination": {
      "network_code": "12345"
   },
   "sms": {
      "count_total": "1"
   }
}