Sms - Send

Sends a SMS message from a phone number that belongs to the authenticated account.

POST {endpoint}/sms?api-version=2021-03-07

URI Parameters

Name In Required Type Description
endpoint
path True
  • string

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

The sender's phone number in E.164 format that is owned by the authenticated account.

message True
  • string

The contents of the message that will be sent to the recipient. The allowable content is defined by RFC 5724.

smsRecipients True

The recipient's phone number in E.164 format. In this version, a minimum of 1 and upto 100 recipients in the list are supported.

smsSendOptions

Optional configuration for sending SMS messages.

Responses

Name Type Description
202 Accepted

Accepted

Examples

SuccessfulSend

Sample Request

POST https://contoso.communication.azure.com//sms?api-version=2021-03-07

{
  "from": "+18001110000",
  "smsRecipients": [
    {
      "to": "+11234567890"
    },
    {
      "to": "+11234567891"
    },
    {
      "to": "+112345678901"
    },
    {
      "to": "+11234567892"
    },
    {
      "to": "+11234567893",
      "repeatabilityRequestId": "fda6d242-46aa-4247-8bf6-619a1206f9c3",
      "repeatabilityFirstSent": "Mon, 01 Apr 2019 06:22:03 GMT"
    },
    {
      "to": "+11234567894",
      "repeatabilityRequestId": "fda6d242-46aa-4247-8bf6-619a1206f9c3"
    }
  ],
  "message": "Hello world!",
  "smsSendOptions": {
    "enableDeliveryReport": true,
    "tag": "testSmsRequest"
  }
}

Sample Response

{
  "value": [
    {
      "to": "+11234567890",
      "messageId": "Outgoing_20200610203725bfd4ba70-70bf-4f77-925d-c0bdb5161bb3",
      "httpStatusCode": 202,
      "successful": true
    },
    {
      "to": "+11234567891",
      "messageId": "Outgoing_2020061020025100d1-d07e-4b19-b25d-13525d552822",
      "httpStatusCode": 202,
      "successful": true
    },
    {
      "to": "+112345678901",
      "httpStatusCode": 400,
      "errorMessage": "Invalid To phone number format.",
      "successful": false
    },
    {
      "to": "+11234567892",
      "messageId": "Outgoing_2020061020025100d1-d07e-4b19-b25d-13525d552822",
      "httpStatusCode": 503,
      "errorMessage": "ServiceUnavailable",
      "successful": false
    },
    {
      "to": "+11234567893",
      "messageId": "Outgoing_2020061020025100d1-d07e-4b19-b25d-13525d552822_noam",
      "httpStatusCode": 202,
      "repeatabilityResult": "accepted",
      "successful": true
    },
    {
      "to": "+11234567894",
      "messageId": "Outgoing_2020061020025100d1-d07e-4b19-b25d-13525d552822",
      "httpStatusCode": 400,
      "repeatabilityResult": "rejected",
      "errorMessage": "Request sent with Invalid DateTime value for repeatability-first-sent. Expected is DateTime ,RFC1123 pattern.",
      "successful": false
    }
  ]
}

Definitions

SendMessageRequest

Represents the properties of a send message request.

SmsRecipient

Recipient details for sending SMS messages.

SmsSendOptions

Optional configuration for sending SMS messages.

SmsSendResponse

Response for a successful or multi status send Sms request.

SmsSendResponseItem

Response for a single recipient.

SendMessageRequest

Represents the properties of a send message request.

Name Type Description
from
  • string

The sender's phone number in E.164 format that is owned by the authenticated account.

message
  • string

The contents of the message that will be sent to the recipient. The allowable content is defined by RFC 5724.

smsRecipients

The recipient's phone number in E.164 format. In this version, a minimum of 1 and upto 100 recipients in the list are supported.

smsSendOptions

Optional configuration for sending SMS messages.

SmsRecipient

Recipient details for sending SMS messages.

Name Type Description
repeatabilityFirstSent
  • string

MUST be sent by clients to specify that a request is repeatable. Repeatability-First-Sent is used to specify the date and time at which the request was first created.eg- Tue, 26 Mar 2019 16:06:51 GMT

repeatabilityRequestId
  • string

If specified, the client directs that the request is repeatable; that is, the client can make the request multiple times with the same Repeatability-Request-ID and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-ID is an opaque string representing a client-generated, 36-character hexadecimal case-insensitive encoding of a UUID (GUID), identifier for the request.

to
  • string

The recipient's phone number in E.164 format.

SmsSendOptions

Optional configuration for sending SMS messages.

Name Type Description
enableDeliveryReport
  • boolean

Enable this flag to receive a delivery report for this message on the Azure Resource EventGrid.

tag
  • string

Use this field to provide metadata that will then be sent back in the corresponding Delivery Report.

SmsSendResponse

Response for a successful or multi status send Sms request.

Name Type Description
value

Response for a single recipient.

SmsSendResponseItem

Response for a single recipient.

Name Type Description
errorMessage
  • string

Optional error message in case of 4xx/5xx/repeatable errors.

httpStatusCode
  • integer

HTTP Status code.

messageId
  • string

The identifier of the outgoing Sms message. Only present if message processed.

repeatabilityResult enum:
  • accepted
  • rejected

The result of a repeatable request with one of the case-insensitive values accepted or rejected.

successful
  • boolean

Indicates if the message is processed successfully or not.

to
  • string

The recipient's phone number in E.164 format.