Opt Outs - Remove

Service:

Communication

API Version:

2026-01-23

Remove phone numbers from the optouts list.

POST {endpoint}/sms/optouts:remove?api-version=2026-01-23

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string (url)	The communication resource, for example https://my-resource.communication.azure.com
api-version	query	True	string	Version of API to invoke.

Request Body

Name	Required	Type	Description
from	True	string minLength: 1	The sender's identifier (typically phone number in E.164 format) that is owned by the authenticated account.
recipients	True	OptOutRecipient[]	A single opt out recipient number.

Responses

Name	Type	Description
200 OK	OptOutResponse	Success
400 Bad Request	BadRequestErrorResponse	Bad Request
401 Unauthorized	StandardErrorResponse	Unauthorized

Examples

Opt In

Sample request

HTTP

POST {endpoint}/sms/optouts:remove?api-version=2026-01-23

{
  "from": "+18001234567",
  "recipients": [
    {
      "to": "+15555555551"
    },
    {
      "to": "+123"
    },
    {
      "to": "+15555555553"
    }
  ]
}

Sample response

Status code:

200

{
  "value": [
    {
      "to": "+15555555551",
      "httpStatusCode": 200
    },
    {
      "to": "+123",
      "httpStatusCode": 400,
      "errorMessage": "Invalid recipient phone number format"
    },
    {
      "to": "+15555555553",
      "httpStatusCode": 500,
      "errorMessage": "Internal Server Error"
    }
  ]
}

Status code:

400

{
  "error": {
    "code": "InvalidApiVersion",
    "message": "The HTTP resource that matches the request URI 'https://global.sms.int.communication.microsoft.com/sms/optouts:remove' does not support the API version '2024-12-10w-preview'.",
    "innerError": null
  }
}

Status code:

401

{
  "error": {
    "code": "Unauthorized",
    "message": ""
  }
}

Definitions

Name	Description
BadRequestErrorResponse	Bad Request error response that can represent both validation errors and standard API errors.
ErrorDetail	Error detail information.
OptOutRecipient	A single opt out recipient number.
OptOutRequest	An opt out request.
OptOutResponse	Response for an opt out request. Validate the returned items in the response to see which recipients were successfully added or removed from the opt outs list.
OptOutResponseItem
StandardErrorResponse	Standard error response format.

BadRequestErrorResponse

Object

Bad Request error response that can represent both validation errors and standard API errors.

Name	Type	Description
error	ErrorDetail	Error detail information (for standard API errors).
errors	object	Dictionary of field-specific validation errors (for validation errors).
status	integer (int32)	The HTTP status code (for validation errors).
title	string	A short, human-readable summary of the problem type (for validation errors).
traceId	string	The trace identifier for the request (for validation errors).
type	string	A URI reference that identifies the problem type (for validation errors).

ErrorDetail

Object

Error detail information.

Name	Type	Description
code	string	The error code.
innerError	object	Additional error details.
message	string	The error message.

OptOutRecipient

Object

A single opt out recipient number.

Name	Type	Description
to	string minLength: 1	The recipient's phone number (in E.164 format).

OptOutRequest

Object

An opt out request.

Name	Type	Description
from	string minLength: 1	The sender's identifier (typically phone number in E.164 format) that is owned by the authenticated account.
recipients	OptOutRecipient[]	A single opt out recipient number.

OptOutResponse

Object

Response for an opt out request. Validate the returned items in the response to see which recipients were successfully added or removed from the opt outs list.

Name	Type	Description
value	OptOutResponseItem[]

OptOutResponseItem

Object

Name	Type	Description
errorMessage	string	Optional error message in case of 4xx/5xx errors.
httpStatusCode	integer (int32)
isOptedOut	boolean	Optional flag specifying if number was Opted Out from receiving messages
to	string minLength: 1	The recipient phone number (in E.164 format).

StandardErrorResponse

Object

Standard error response format.

Name	Type	Description
error	ErrorDetail	Error detail information.