openapi: 3.1.0 info: title: API Overview | Sinch version: "v1" description: Sinch SMS API is one of the easiest APIs we offer and enables you to add fast and reliable global SMS to your applications. Send single messages, scheduled batch messages, use available message templates and more. contact: name: Support url: www.sinch.com email: Support@sinch.com license: name: MIT url: "https://www.sinch.com/toc" servers: - url: "https://{region}.sms.api.sinch.com" description: Global API variables: region: default: us enum: - us - eu - au - br - ca x-enumDescriptions: us: United States eu: Europe au: Australia br: Brazil ca: Canada security: - BearerAuth: [] webhooks: incomingSMS: summary: Incoming SMS post: tags: - Webhooks - Inbounds summary: Incoming SMS description: |- An inbound message is a message sent to one of your short codes or long numbers from a mobile phone. To receive inbound message callbacks, a URL needs to be added to your REST API. This URL can be specified in your [Dashboard](https://dashboard.sinch.com/sms/api). operationId: incomingSMS requestBody: description: The incoming message to your sinch number content: application/json: schema: oneOf: - type: object $ref: '#/components/schemas/MOText' - type: object $ref: '#/components/schemas/MOBinary' - type: object $ref: '#/components/schemas/MOMedia' examples: Text MO: value: body: This is a test message. from: "16051234567" id: 01XXXXX21XXXXX119Z8P1XXXXX operator_id: string received_at: 2022-08-24T14:15:22Z sent_at: 2022-08-24T14:15:22Z to: "13185551234" type: mo_text Binary MO: value: body: VGV4dCBtZXNzYWdl from: "16051234567" id: 01XXXXX21XXXXX119Z8P1XXXXX operator_id: operator received_at: 2022-08-24T14:15:22Z sent_at: 2022-08-24T14:15:22Z to: "13185551234" type: mo_binary udh: 10010203040506070809000a0b0c0d0e0f Media MO: value: body: subject: "Test subject" message: "Test message" media: - url: "https://some.s3.example.com/inbounds" contentType: "image/png" status: "UPLOADED" code: 0 from: "+11203494390" id: 01XXXXX21XXXXX119Z8P1XXXXX received_at: 2019-08-24T14:15:22Z sent_at: 2019-08-24T14:15:22Z to: "11203453453" type: mo_media responses: "200": description: A `2xx` status code indicates that the data was received successfully. "400": description: A `4xx` status counts as a permanent failure and will not trigger any retries, except for `429`. "429": description: The callback will be retried and the callback throughput will be lowered. "500": description: A `5xx` status code will trigger a retry. security: [] deliveryReport: summary: Delivery Report post: tags: - Webhooks - Delivery reports summary: Delivery Report description: |- A delivery report contains the status and status code for each recipient of a batch. To get a delivery report callback for a message or batch of messages, set the `delivery_report` field accordingly when [creating a batch](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/SendSMS). The following is provided so you can better understand our webhooks/callbacks. Configuration of both webhooks and the type of delivery report requested happens when sending a batch. #### Callback URL The callback URL can either be provided for each batch or provisioned globally for your account in your [Sinch Customer Dashboard](https://dashboard.sinch.com/sms/api/rest). Learn how to configure a webhook/callback here. #### Type The `type` is the type of delivery report webhook. The response will vary depending on the webhook delivery report you selected when the batch was sent, so choose the appropriate selection under "One of". - The `delivery_report_sms` and `delivery_report_mms` types are documented under Delivery report. These are reports containing either [a full report or summary report](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/SendSMS!path=0/delivery_report&t=request), depending on your selection at the time the batch was sent. - The `recipient_delivery_report_sms` and `recipient_delivery_report_mms` delivery report types are documented under Recipient delivery report. These are delivery reports for recipient phone numbers. If you set `per_recipient` for the `delivery_report` parameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch. If you set `per_recipient_final`, a recipient report gets sent to you for the final status of each recipient in your batch. operationId: deliveryReport requestBody: description: "" content: application/json: schema: oneOf: - $ref: "#/components/schemas/DeliveryReport" - $ref: "#/components/schemas/RecipientDeliveryReport" examples: Delivery report: $ref: "#/components/examples/SmsDeliveryReport" Recipient delivery report: $ref: "#/components/examples/SmsRecipientDeliveryReport" MMS delivery report: $ref: "#/components/examples/MmsDeliveryReport" MMS recipient delivery report: $ref: "#/components/examples/MmsRecipientDeliveryReport" responses: "200": description: A `2xx` status code indicates that the data was received successfully. "400": description: A `4xx` status counts as a permanent failure and will not trigger any retries, except for `429`. "429": description: The callback will be retried and the callback throughput will be lowered. "500": description: A `5xx` status code will trigger a retry. security: [] paths: "/xms/v1/{service_plan_id}/batches": parameters: - $ref: "#/components/parameters/service_plan_id" post: tags: - Batches summary: Send operationId: SendSMS description: |- Send a message or a batch of messages. Depending on the length of the body, one message might be split into multiple parts and charged accordingly. Any groups targeted in a scheduled batch will be evaluated at the time of sending. If a group is deleted between batch creation and scheduled date, it will be considered empty. Be sure to use the correct region in the server URL. requestBody: content: application/json: schema: oneOf: - $ref: "#/components/schemas/TextRequest" - $ref: "#/components/schemas/BinaryRequest" - $ref: "#/components/schemas/MediaRequest" examples: BatchSendFillInText: $ref: "#/components/examples/BatchSendFillInText" BatchSendFillInBinary: $ref: "#/components/examples/BatchSendFillInBinary" BatchSendFillInMedia: $ref: "#/components/examples/BatchSendFillInMedia" BatchSendBasicSMSText: $ref: "#/components/examples/BatchSendBasicSMSText" BatchSendBasicSMSBinary: $ref: "#/components/examples/BatchSendBasicSMSBinary" BatchSendBasicCardMMS: $ref: "#/components/examples/BatchSendBasicCardMMS" BatchSendBasicMediaMMS: $ref: "#/components/examples/BatchSendBasicMediaMessage" BatchMessageWExpiryText: $ref: "#/components/examples/BatchMessageWExpiryText" BatchMessageWExpiryBinary: $ref: "#/components/examples/BatchMessageWExpiryBinary" BatchMessageCustomDeliveryReportURLText: $ref: "#/components/examples/BatchMessageCustomDeliveryReportURLText" BatchMessageCustomDeliveryReportURLBinary: $ref: "#/components/examples/BatchMessageCustomDeliveryReportURLBinary" BatchParameterizedMessageText: $ref: "#/components/examples/BatchParameterizedMessageText" BatchParameterizedMediaMessageText: $ref: "#/components/examples/BatchParameterizedMediaMessageText" description: "Default schema is Text if type is not specified." responses: "201": description: Created. A successful response, or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: oneOf: - $ref: "#/components/schemas/TextResponse" - $ref: "#/components/schemas/BinaryResponse" - $ref: "#/components/schemas/MediaResponse" examples: TextResponseExample: $ref: "#/components/examples/TextResponse" get: summary: List Batches operationId: ListBatches description: With the list operation you can list batch messages created in the last 14 days that you have created. This operation supports pagination. tags: - Batches security: - BearerAuth: [] parameters: - name: page description: The page number starting from 0. schema: type: integer in: query example: 4 - name: page_size schema: type: integer default: 30 maximum: 100 example: 50 in: query description: |- Determines the size of a page. - name: from in: query schema: type: string example: 44345,45607 description: "Only list messages sent from this sender number. Multiple originating numbers can be comma separated. Must be phone numbers or short code." - name: start_date in: query schema: type: string description: |- Only list messages received at or after this date/time. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`. Default: Now-24 - name: end_date in: query schema: type: string description: "Only list messages received before this date/time. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`." - name: client_reference in: query description: Client reference to include required: false schema: maxLength: 2048 minLength: 0 type: string example: myReference responses: "200": description: OK. A successful response, or an [Error](/docs/sms/api-reference/status-codes/). headers: {} content: application/json: schema: $ref: '#/components/schemas/ApiBatchList' examples: ApiBatchListExample: $ref: "#/components/examples/ApiBatchList" "/xms/v1/{service_plan_id}/inbounds": parameters: - $ref: "#/components/parameters/service_plan_id" get: summary: List incoming messages tags: - Inbounds security: - BearerAuth: [] operationId: ListInboundMessages description: With the list operation, you can list all inbound messages that you have received. This operation supports pagination. Inbounds are returned in reverse chronological order. parameters: - $ref: "#/components/parameters/page" - name: page_size schema: type: integer maximum: 100 default: 30 in: query description: |- Determines the size of a page - name: to schema: type: string example: +14155553421, +13435552671, +14325552677 in: query description: |- Only list messages sent to this destination. Multiple phone numbers formatted as either E.164 or short codes can be comma separated. - name: start_date schema: type: string default: Now-24 format: ISO-8601 in: query description: |- Only list messages received at or after this date/time. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`. Default: Now-24 - name: end_date schema: type: string format: ISO-8601 example: "2016-10-02T09:34:18.542Z" in: query description: "Only list messages received before this date/time. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`." - name: client_reference in: query description: |- Using a client reference in inbound messages requires additional setup on your account. Contact your account manager to enable this feature. Only list inbound messages that are in response to messages with a previously provided client reference. required: false schema: maxLength: 2048 minLength: 0 type: string example: myReference responses: "200": description: OK. A successful response , or an [Error](/docs/sms/api-reference/status-codes/). headers: {} content: application/json: schema: $ref: "#/components/schemas/ApiInboundList" "/xms/v1/{service_plan_id}/inbounds/{inbound_id}": parameters: - $ref: "#/components/parameters/service_plan_id" - $ref: "#/components/parameters/inbound_id" get: summary: Retrieve inbound message description: This operation retrieves a specific inbound message with the provided inbound ID. operationId: RetrieveInboundMessage tags: - Inbounds security: - BearerAuth: [] responses: "200": description: OK. A successful response , or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: oneOf: - type: object $ref: '#/components/schemas/MOText' - type: object $ref: '#/components/schemas/MOBinary' - type: object $ref: '#/components/schemas/MOMedia' examples: MOTextExample: $ref: "#/components/examples/MOText" "/xms/v1/{service_plan_id}/batches/dry_run": parameters: - $ref: "#/components/parameters/service_plan_id" post: security: - BearerAuth: [] summary: Dry run description: This operation will perform a dry run of a batch which calculates the bodies and number of parts for all messages in the batch without actually sending any messages. operationId: Dry_Run tags: - Batches requestBody: content: application/json: schema: oneOf: - $ref: "#/components/schemas/TextRequest" - $ref: "#/components/schemas/BinaryRequest" - $ref: "#/components/schemas/MediaRequest" examples: DryRunFillIn: $ref: "#/components/examples/DryRunFillIn" DryRunParameters: $ref: "#/components/examples/DryRunParameters" parameters: - schema: type: boolean example: true in: query name: per_recipient description: Whether to include per recipient details in the response - schema: type: integer maximum: 1000 default: 100 example: 500 in: query name: number_of_recipients description: Max number of recipients to include per recipient details for in the response responses: "200": description: OK. A successful response , or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: $ref: "#/components/schemas/DryRunResponse" examples: DryRunResponseExample: $ref: "#/components/examples/DryRunResponse" "/xms/v1/{service_plan_id}/batches/{batch_id}": parameters: - $ref: "#/components/parameters/service_plan_id" - $ref: "#/components/parameters/batch_id" get: summary: Get a batch message operationId: GetBatchMessage description: This operation returns a specific batch that matches the provided batch ID. tags: - Batches security: - BearerAuth: [] responses: "200": description: OK. A successful response , or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: oneOf: - $ref: '#/components/schemas/TextResponse' - $ref: '#/components/schemas/BinaryResponse' - $ref: '#/components/schemas/MediaResponse' examples: RetrieveMessageResponseExample: $ref: "#/components/examples/TextResponse" post: summary: Update a Batch message operationId: UpdateBatchMessage description: This operation updates all specified parameters of a batch that matches the provided batch ID. tags: - Batches security: - BearerAuth: [] requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/ApiUpdateTextMtMessage' - $ref: '#/components/schemas/ApiUpdateBinaryMtMessage' - $ref: '#/components/schemas/ApiUpdateMmsMtMessage' examples: BatchUpdateFillIn: $ref: "#/components/examples/BatchUpdateFillIn" BatchRemovePhoneNumbers: $ref: "#/components/examples/BatchRemovePhoneNumbers" BatchAddPhoneNumbers: $ref: "#/components/examples/BatchAddPhoneNumbers" responses: "200": description: A successful response , or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: oneOf: - $ref: '#/components/schemas/TextResponse' - $ref: '#/components/schemas/BinaryResponse' - $ref: '#/components/schemas/MediaResponse' examples: UpdatedMessageResponseExample: $ref: "#/components/examples/TextResponse" BinaryResponseExample: $ref: "#/components/examples/BinaryResponse" MediaResponseExample: $ref: "#/components/examples/MediaResponse" put: summary: Replace a batch operationId: ReplaceBatch description: This operation will replace all the parameters of a batch with the provided values. It is the same as cancelling a batch and sending a new one instead. tags: - Batches security: - BearerAuth: [] requestBody: content: application/json: schema: oneOf: - $ref: "#/components/schemas/TextRequest" - $ref: "#/components/schemas/BinaryRequest" - $ref: "#/components/schemas/MediaRequest" examples: TextRequestExample: $ref: "#/components/examples/TextRequest" BinaryRequestExample: $ref: "#/components/examples/BinaryRequest" MediaRequestExample: $ref: "#/components/examples/MediaRequest" responses: "200": description: A successful response , or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: oneOf: - $ref: '#/components/schemas/TextResponse' - $ref: '#/components/schemas/BinaryResponse' - $ref: '#/components/schemas/MediaResponse' delete: summary: Cancel a batch message operationId: CancelBatchMessage description: |- A batch can be canceled at any point. If a batch is canceled while it's currently being delivered some messages currently being processed might still be delivered. The delivery report will indicate which messages were canceled and which weren't. Canceling a batch scheduled in the future will result in an empty delivery report while canceling an already sent batch would result in no change to the completed delivery report. tags: - Batches security: - BearerAuth: [] responses: "200": description: Batch deleted or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: oneOf: - $ref: '#/components/schemas/TextResponse' - $ref: '#/components/schemas/BinaryResponse' - $ref: '#/components/schemas/MediaResponse' examples: CancelBatchResponseExample: $ref: '#/components/examples/CancelBatchResponse' "/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report": parameters: - $ref: "#/components/parameters/service_plan_id" - $ref: "#/components/parameters/batch_id" get: summary: Retrieve a delivery report description: |- Delivery reports can be retrieved even if no callback was requested. The difference between a summary and a full report is only that the full report contains the phone numbers in E.164 format for each status code. security: - BearerAuth: [] tags: - Delivery reports operationId: GetDeliveryReportByBatchId parameters: - schema: type: string enum: [summary, full] default: summary in: query name: type description: |- The type of delivery report. - A `summary` will count the number of messages sent per status. - A `full` report give that of a `summary` report but in addition, lists phone numbers. - schema: type: string example: "Queued,Dispatched,Delivered" in: query name: status description: Comma separated list of delivery_report_statuses to include - schema: type: string example: "400,405" in: query name: code description: Comma separated list of delivery_receipt_error_codes to include responses: "202": description: Accepted, or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: $ref: "#/components/schemas/DeliveryReport" examples: Delivery Report: $ref: "#/components/examples/SmsDeliveryReport" Mms Delivery Report: $ref: "#/components/examples/MmsDeliveryReport" "/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/{recipient_msisdn}": parameters: - $ref: "#/components/parameters/service_plan_id" - $ref: "#/components/parameters/batch_id" - $ref: "#/components/parameters/recipient_msisdn" get: summary: Retrieve a recipient delivery report security: - BearerAuth: [] tags: - Delivery reports operationId: GetDeliveryReportByPhoneNumber description: A recipient delivery report contains the message status for a single recipient phone number. responses: "200": description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: $ref: '#/components/schemas/RecipientDeliveryReport' examples: Delivery Report: $ref: "#/components/examples/SmsRecipientDeliveryReport" Mms Delivery Report: $ref: "#/components/examples/MmsRecipientDeliveryReport" "/xms/v1/{service_plan_id}/delivery_reports": get: tags: - Delivery reports summary: Retrieve a list of delivery reports description: |- Get a list of finished delivery reports. This operation supports pagination. operationId: getDeliveryReports parameters: - $ref: "#/components/parameters/service_plan_id" - name: page in: query description: The page number starting from 0. required: false schema: minimum: 0 type: integer default: 0 example: 4 - name: page_size in: query description: |- Determines the size of a page. required: false schema: maximum: 100 minimum: 1 type: integer default: 30 example: 50 - name: start_date in: query description: |- Only list messages received at or after this date/time. Default: 24h ago required: false schema: type: string format: YYYY-MM-DDThh:mm:ss.SSSZ - name: end_date in: query description: Only list messages received before this date/time. required: false schema: type: string format: YYYY-MM-DDThh:mm:ss.SSSZ example: 2022-10-02T09:34:18.542Z - name: status in: query description: Comma separated list of delivery report statuses to include. required: false schema: type: string example: "Queued,Dispatched,Delivered" - name: code in: query description: Comma separated list of delivery receipt error codes to include. required: false schema: type: string example: "400,405" - name: client_reference in: query description: Client reference to include required: false schema: maxLength: 2048 minLength: 0 type: string example: myReference responses: "200": description: A successful response , or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: $ref: '#/components/schemas/DeliveryReportList' examples: SmsListDeliveryReports: $ref: "#/components/examples/SmsListDeliveryReports" security: - BearerAuth: [] "/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_feedback": parameters: - $ref: "#/components/parameters/service_plan_id" - $ref: "#/components/parameters/batch_id" post: tags: - Batches summary: Send delivery feedback for a message description: |- Send feedback if your system can confirm successful message delivery. Feedback can only be provided if `feedback_enabled` was set when batch was submitted. **Batches**: It is possible to submit feedback multiple times for the same batch for different recipients. Feedback without specified recipients is treated as successful message delivery to all recipients referenced in the batch. Note that the `recipients` key is still required even if the value is empty. **Groups**: If the batch message was creating using a group ID, at least one recipient is required. Excluding recipients (an empty recipient list) does not work and will result in a failed request. operationId: deliveryFeedback requestBody: description: A list of phone numbers (MSISDNs) that successfully received the message. content: application/json: schema: $ref: '#/components/schemas/ApiDeliveryFeedback' required: true responses: "202": description: Accepted, or an [Error](/docs/sms/api-reference/status-codes/). A successful response will return an empty 202 HTTP response, indicating that the request has been received and is processing. security: - BearerAuth: [] "/xms/v1/{service_plan_id}/groups": parameters: - $ref: "#/components/parameters/service_plan_id" get: summary: List Groups operationId: ListGroups description: |- With the list operation you can list all groups that you have created. This operation supports pagination. Groups are returned in reverse chronological order. security: - BearerAuth: [] tags: - Groups parameters: - schema: type: integer minimum: 0 default: 0 in: query name: page description: |- The page number starting from 0. example: 50 - schema: type: integer maximum: 100 minimum: 0 default: 30 in: query name: page_size description: |- Determines the size of a page. example: 50 responses: "200": description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: $ref: "#/components/schemas/GroupList" examples: GroupListExample: $ref: "#/components/examples/GroupList" post: summary: Create a group operationId: CreateGroup description: |- This endpoint allows you to create a group of recipients. A new group must be created with a group name. This is represented by the `name` field which can be up to 20 charecters. In addition, there are a number of optional fields: - `members` field enables groups to be created with an initial list of contacts - `auto_update` allows customers to auto subscribe to a new group. This contains three fields. The `to` field contains the group creator's number. (This number **must be provisioned by contacting your account manager**.) The `add` and `remove` fields are objects containing the keywords that customers need to text to join or leave a group. security: - BearerAuth: [] tags: - Groups requestBody: content: application/json: schema: $ref: "#/components/schemas/groupObject" examples: GroupCreateFillIn: $ref: "#/components/examples/GroupCreateFillIn" CreateGroup: $ref: "#/components/examples/CreateGroup" GroupCreateParent: $ref: "#/components/examples/GroupCreateParent" responses: "201": description: Created, or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: $ref: "#/components/schemas/createGroupResponse" examples: createGroupResponseExample: $ref: "#/components/examples/createGroupResponse" "/xms/v1/{service_plan_id}/groups/{group_id}": parameters: - $ref: "#/components/parameters/service_plan_id" - $ref: "#/components/parameters/group_id" get: summary: Retrieve a group description: This operation retrieves a specific group with the provided group ID. operationId: RetrieveGroup tags: - Groups responses: "200": description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: $ref: "#/components/schemas/createGroupResponse" post: summary: Update a group description: |- With the update group operation, you can add and remove members in an existing group as well as rename the group. This method encompasses a few ways to update a group: 1. By using `add` and `remove` arrays containing phone numbers, you control the group movements. Any list of valid numbers in E.164 format can be added. 2. By using the `auto_update` object, your customer can add or remove themselves from groups. 3. You can also add or remove other groups into this group with `add_from_group` and `remove_from_group`. #### Other group update info - The request will not be rejected for duplicate adds or unknown removes. - The additions will be done before the deletions. If an phone number is on both lists, it will not be apart of the resulting group. - Updating a group targeted by a batch message scheduled in the future is allowed. Changes will be reflected when the batch is sent. operationId: UpdateGroup security: - BearerAuth: [] tags: - Groups requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateGroup" examples: GroupAddRemoveList: $ref: "#/components/examples/GroupAddRemoveList" GroupAutoUpdate: $ref: "#/components/examples/GroupAutoUpdate" GroupAutoUpdateSharedShortCode: $ref: "#/components/examples/GroupAutoUpdateSharedShortCode" GroupUpdateAdd: $ref: "#/components/examples/GroupUpdateAdd" GroupUpdateRemove: $ref: "#/components/examples/GroupUpdateRemove" GroupUpdateNameKeepMembers: $ref: "#/components/examples/GroupUpdateNameKeepMembers" responses: "200": description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: $ref: "#/components/schemas/createGroupResponse" put: security: - BearerAuth: [] summary: Replace a group operationId: ReplaceGroup description: |- The replace operation will replace all parameters, including members, of an existing group with new values. Replacing a group targeted by a batch message scheduled in the future is allowed and changes will be reflected when the batch is sent. tags: - Groups requestBody: content: application/json: schema: $ref: "#/components/schemas/ReplacedGroup" examples: GroupReplaceGroup: $ref: "#/components/examples/GroupReplaceGroup" responses: "200": description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: $ref: "#/components/schemas/createGroupResponse" delete: tags: - Groups summary: Delete a group description: This operation deletes the group with the provided group ID. operationId: deleteGroup parameters: - name: service_plan_id in: path required: true $ref: '#/components/parameters/service_plan_id' schema: type: string - name: group_id in: path required: true $ref: '#/components/parameters/group_id' schema: type: string responses: "200": description: A successful response , or an [Error](/docs/sms/api-reference/status-codes/). security: - BearerAuth: [] "/xms/v1/{service_plan_id}/groups/{group_id}/members": parameters: - $ref: "#/components/parameters/service_plan_id" - $ref: "#/components/parameters/group_id" get: summary: Get phone numbers for a group description: |- This operation retrieves the members of the group with the provided group ID. security: - BearerAuth: [] operationId: GetMembers tags: - Groups responses: "200": description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/). content: application/json: schema: type: array items: $ref: "#/components/schemas/msisdn" components: examples: MediaRequest: summary: media request example value: to: - 15551231234 - 15551256344 body: url: https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png BinaryRequest: summary: binary request example value: to: - 15551231234 - 15551256344 body: Hi ${name}! How are you? udh: abcxaf123 TextRequest: summary: example text request value: to: - 15551231234 - 15551256344 body: Hi ${name}! How are you? DryRunResponse: summary: example dry run response value: number_of_recipients: 1 number_of_messages: 1 per_recipient: - recipient: 15551231234 number_of_parts: 1 body: Test Message encoding: GSM ApiUpdateTextMtMessage: summary: example message response value: id: 01FC66621XXXXX119Z8PMV1QPQ to: - 15551231234 - 15551256344 from: 15551231234 canceled: false parameters: "{parameter_key}": "{msisdn}": string default: string body: Hi ${name}! How are you? type: mt_text created_at: '2019-08-24T14:15:22Z' modified_at: '2019-08-24T14:15:22Z' delivery_report: none send_at: '2019-08-24T14:15:22Z' expire_at: '2019-08-24T14:15:22Z' callback_url: string client_reference: myReference feedback_enabled: false flash_message: false truncate_concat: true max_number_of_message_parts: 1 from_ton: 6 from_npi: 18 createGroupResponse: summary: example group response value: id: 01FC66621XXXXX119Z8PMV1QPU name: My new customers size: 2 created_at: '2019-08-24T14:15:22Z' modified_at: '2019-08-24T14:15:22Z' child_groups: - 01FC66621XXXXX119Z8PMV1AHY auto_update: to: 15551231234 add: join remove: leave msisdn: summary: phone number response value: - "+453234457784" ApiInboundList: summary: List of incoming messages value: count: 1 page: 0 inbounds: - body: Test Message client_reference: ABC123 from: "+11203494390" id: 01FC66621XXXXX119Z8PMV1QPA operator_id: '35000' received_at: '2019-08-24T14:15:22Z' sent_at: '2019-08-24T14:15:22Z' to: '11203453453' type: mo_text page_size: 50 MOText: summary: Mobile originating message value: body: Test message client_reference: ABC123 from: "+11203494390" id: 01FC66621XXXXX119Z8PMV1QPA operator_id: '35000' received_at: '2019-08-24T14:15:22Z' sent_at: '2019-08-24T14:15:22Z' to: '11203453453' type: mo_text MOMedia: summary: Mobile originating message value: body: subject: Test subject message: Test message media: - url: "https://some.s3.example.com/inbounds" contentType: 'image/jpeg' status: UPLOADED code: 0 from: "+11203494390" id: 01FC66621XXXXX119Z8PMV1QPA received_at: '2019-08-24T14:15:22Z' sent_at: '2019-08-24T14:15:22Z' to: '11203453453' type: mo_media CancelBatchResponse: summary: batch message example value: id: 01FC66621XXXXX119Z8PMV1QPQ to: - 15551231234 - 15551256344 from: 15551231234 canceled: true parameters: "{parameter_key}": "{msisdn}": 15551231234 default: string body: Hi ${name}! How are you? type: mt_text created_at: '2019-08-24T14:15:22Z' modified_at: '2019-08-24T14:15:22Z' delivery_report: none send_at: '2019-08-24T14:15:22Z' expire_at: '2019-08-24T14:15:22Z' callback_url: myCallbackUrl client_reference: myReference feedback_enabled: false flash_message: false truncate_concat: true max_number_of_message_parts: 1 from_ton: 6 from_npi: 18 TextResponse: summary: batch message example value: id: 01FC66621XXXXX119Z8PMV1QPQ to: - 15551231234 - 15551256344 from: 15551231234 canceled: false parameters: "{parameter_key}": "{msisdn}": 15551231234 default: string body: Hi ${name}! How are you? type: mt_text created_at: '2019-08-24T14:15:22Z' modified_at: '2019-08-24T14:15:22Z' delivery_report: none send_at: '2019-08-24T14:15:22Z' expire_at: '2019-08-24T14:15:22Z' callback_url: myCallbackUrl client_reference: myReference feedback_enabled: false flash_message: false truncate_concat: true max_number_of_message_parts: 1 from_ton: 6 from_npi: 18 BinaryResponse: summary: binary response example value: id: 01FC66621XXXXX119Z8PMV1QPQ to: - 15551231234 - 15551256344 from: 15551231234 canceled: false parameters: "{parameter_key}": "{msisdn}": 15551231234 default: string body: "YOUR_base64_message_body" udh: "abcxaf123" type: mt_binary created_at: '2019-08-24T14:15:22Z' modified_at: '2019-08-24T14:15:22Z' delivery_report: none send_at: '2019-08-24T14:15:22Z' expire_at: '2019-08-24T14:15:22Z' callback_url: myCallbackUrl client_reference: myReference feedback_enabled: false from_ton: 6 from_npi: 18 MediaResponse: summary: media response example value: id: 01FC66621XXXXX119Z8PMV1QPQ to: - 15551231234 - 15551256344 from: 15551231234 canceled: false parameters: "{parameter_key}": "{msisdn}": 15551231234 default: string body: url: example.source.jpg message: your image type: mt_media created_at: '2019-08-24T14:15:22Z' modified_at: '2019-08-24T14:15:22Z' delivery_report: none send_at: '2019-08-24T14:15:22Z' expire_at: '2019-08-24T14:15:22Z' callback_url: myCallbackUrl client_reference: myReference feedback_enabled: false strict_validation: false ApiBatchList: summary: API batch list example value: count: "2" page: "1" batches: - id: "abc123" to: - "01234567" from: "01234567" canceled: false body: "Test message" udh: "abcxaf123" type: "mt_text" created_at: "2023-11-11T09:00:20.0" modified_at: "2023-11-11T09:00:20.0" delivery_report: none send_at: "2023-11-11T09:00:20.0" expire_at: "" callback_url: "" client_reference: "xyz" feedback_enabled: false flash_message: false truncate_concat: "false" max_number_of_message_parts: "1" from_ton: "0" from_npi: "0" - id: "def345" to: - "07654321" from: "012346790" canceled: false body: "Test Message 2" udh: "abcxaf123" type: "mt_text" created_at: "2023-11-11T09:00:20.0" modified_at: "2023-11-11T09:00:20.0" delivery_report: none send_at: "2023-11-11T09:00:20.0" expire_at: "2023-11-11T09:00:20.0" callback_url: "" client_reference: "abc" feedback_enabled: false flash_message: false truncate_concat: "false" max_number_of_message_parts: "1" from_ton: "0" from_npi: "0" page_size: "10" BatchSendFillInBinary: summary: Binary - fill-in value: from: "YOUR_Sinch_virtual_number" to: ["YOUR_recipient_number"] body: "YOUR_base64_message_body" delivery_report: "summary" type: "mt_binary" udh: "YOUR_user_data_header" BatchSendFillInMedia: summary: Media - fill-in value: from: "YOUR_Sinch_virtual_number" to: ["YOUR_recipient_number"] body: { "url": "YOUR_media_link", "message": "Optional Text Message" } delivery_report: "summary" type: "mt_media" BatchSendFillInText: summary: Text - fill-in value: from: "YOUR_Sinch_virtual_number" to: ["YOUR_recipient_number"] body: "YOUR_message_body" delivery_report: "summary" type: "mt_text" BatchSendBasicSMSBinary: summary: Binary - Basic SMS example value: from: "12345" to: ["+15551231212"] body: "U2FtcGxlIG1lc3NhZ2Uu" delivery_report: "full" type: "mt_binary" udh: "YOUR_user_data_header" BatchSendBasicSMSText: summary: Text - Basic SMS example value: from: "12345" to: ["+15551231212"] body: "Programmers are tools for converting caffeine into code. We just got a new shipment of mugs! Check them out: https://tinyurl.com/4a6fxce7!" delivery_report: "full" type: "mt_text" BatchSendBasicMediaMessage: summary: Media - Media only MMS value: from: "12345" to: ["15551231212"] body: { "url": "https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png", } type: "mt_media" BatchSendBasicCardMMS: summary: Media - Card MMS value: from: "12345" to: ["15551231212"] body: { "url": "https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png", "message": "Text message from Sinch!" } type: "mt_media" BatchMessageWExpiryBinary: summary: Binary - Batch message with expiry value: from: "12345" to: ["+12345678901", "+19876543210"] body: "U2FtcGxlIG1lc3NhZ2Uu" delivery_report: "summary" type: "mt_binary" udh: "YOUR_user_data_header" BatchMessageWExpiryText: summary: Text - Batch message with expiry value: from: "12345" to: ["+12345678901", "+19876543210"] body: "This is a message that will stop attempting to send after three hours." delivery_report: "summary" type: "mt_text" BatchParameterizedMessageText: summary: Text - Parameterized message value: from: "12345" to: ["+12345678910", "+449876543210"] body: "Hi ${name}! Are you in for next week?" delivery_report: "summary" type: "mt_text" parameters: name: +12345678910: "Joe" default: "there" BatchParameterizedMediaMessageText: summary: Media - Parameterized message value: from: "12345" to: ["+12345678910", "+449876543210"] body: { "url": "https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png", "message": "Hi ${name}! Are you in for next week?" } delivery_report: "summary" type: "mt_media" parameters: name: +12345678910: "Joe" default: "there" BatchMessageCustomDeliveryReportURLBinary: summary: Binary - Batch message with custom delivery report URL value: from: "12345" to: ["+12345678910", "+449876543210"] body: "U2FtcGxlIG1lc3NhZ2Uu" delivery_report: "summary" callback_url: "http://www.example.com" type: "mt_binary" udh: "YOUR_user_data_header" BatchMessageCustomDeliveryReportURLText: summary: Text - Batch message with custom delivery report URL value: from: "12345" to: ["+12345678910", "+449876543210"] body: "There's a fine line between a numerator and a denominator that only a fraction of people understand." delivery_report: "summary" callback_url: "http://www.example.com" type: "mt_text" DryRunFillIn: summary: Dry Run value: from: "YOUR_virtual_number" to: ["YOUR_numbers_sending_to", "another_number"] body: "YOUR body text here" parameters: name: "Phone_number_of_recipient" : "recipient_name" default: "default_in_place_of_name" DryRunParameters: summary: Dry run batch with parameters # description: Test out a batch with a name parameter without actually sending it. value: from: "12345" to: ["+12345678910", "+449876543210"] body: "Hi ${name}! Our latest survey shows that 3 out of 4 people make up 75% of the world's population." parameters: name: +12345678910: "Joe" default: "there" BatchGetSpecificNumberBatchesInTimeFrame: summary: Get a specific number of batches within a certain time frame # description: Retrieve the first 30 batches from the last 24 hours. value: page: 1 page_size: 30 start_date: Now-24 BatchGetSpecificPage: summary: Get a specific page from a batch with multiple pages # description: Get the third page of a batch with 50 pages from the last 48 hours. value: page: 3 page_size: 50 start_date: Now-48 BatchGetSpecificDate: summary: Get a batch from a specific date # description: Retrieve batches created on June 23rd, 2021 UTC. value: start_date: "2022-06-23T0000" end_date: "2022-06-23T2400" BatchGetSpecificBatches: summary: Get multiple, specific batches # description: Retrieve batches 44345 and 45607. value: from: 44345,45607 BatchUpdateFillIn: summary: Update value: to_remove: ["YOUR_numbers", "to_remove", "as_strings_in_array", "with_country_code", "16267890123"] to_add: ["YOUR_numbers", "to_add"] BatchRemovePhoneNumbers: summary: Remove a group of phone numbers from a batch # description: Remove five phone numbers from batch 12345. value: to_remove: ["11111111111", "29999999999", "15551234567", "1123456789", "15559876543"] BatchAddPhoneNumbers: summary: Add phone numbers to a batch # description: Add two phone numbers to batch 12345 value: to_add: ["123456789", "987654321"] DeliveryReportSummary: summary: Summary report response # description: Gives a summary report of how many messages were sent, the status code and the status description. value: type: "delivery_report_sms" batch_id: "{batch_id}" total_message_count: 3 statuses: - code: 400 status: "Queued" count: 1 - code: 0 status: "Delivered" count: 2 DeliveryReportFull: summary: Full report # description: Gives a full report of the number of messages sent, status codes, status descriptions and an array of the numbers sent to/failed messages. value: type: "delivery_report_sms" batch_id: "{batch_id}" total_message_count: 3 statuses: - code: 400 status: "Queued" count: 1 recipients: ["123456789"] - code: 0 status: "Delivered" count: 2 recipients: ["987654321", "123459876"] DeliveryReportSpecificNumber: summary: For a specific number # description: Pulls up a report for a specific phone number or short code value: type: "recipient_delivery_report_sms" batch_id: "{batch_id}" total_message_count: 1 statuses: - code: 400 status: "Queued" count: 1 recipients: ["123456789"] SmsDeliveryReport: summary: SMS delivery report value: batch_id: 01FC66621XXXXX119Z8PMV1QPQ statuses: - code: 0 count: 1 recipients: - "44231235674" status: Delivered total_message_count: 1 type: delivery_report_sms MmsDeliveryReport: summary: MMS delivery report value: batch_id: 01FC66621XXXXX119Z8PMV1QPQ statuses: - code: 0 count: 1 recipients: - "44231235674" status: Delivered total_message_count: 1 type: delivery_report_mms MmsRecipientDeliveryReport: summary: MMS recipient delivery report value: at: 2022-08-30T08:16:08.930Z batch_id: 01FC66621XXXXX119Z8PMV1QPQ code: 0 recipient: "44231235674" status: Delivered type: recipient_delivery_report_mms SmsRecipientDeliveryReport: summary: SMS recipient delivery report value: type: "recipient_delivery_report_sms" batch_id: "01FC66621XXXXX119Z8PMV1QPQ" recipient: "+44231235674" code: 401 status: "Dispatched" at: "2022-08-30T08:16:08.930Z" SmsListDeliveryReports: summary: List delivery reports value: count: 1 page: 0 page_size: 2 delivery_reports: - applied_originator: "My Originator" at: "2019-08-24T14:15:22Z" batch_id: "01FC66621XXXXX119Z8PMV1QPQ" client_reference: "my_client_reference" code: 0 encoding: "GSM" number_of_message_parts: 1 operator: "35000" operator_status_at: "2019-08-24T14:15:22Z" recipient: "15551231234" status: "Delivered" type: "recipient_delivery_report_sms" GroupCreateFillIn: summary: Create a group - fill in value: members: ["member_MSISDNs", "as_strings_in_array", "16051234567"] name: "YOUR_group_name" CreateGroup: summary: Create a group value: members: ["123456789", "987654321"] name: "Atlanta Pythonistas" GroupAutoUpdate: summary: Update a group based on customer keyword response # description: Create auto update group for members sending MOs to `443456789012`. Keyword JOIN will add them to the group, keyword STOP will remove them from the group. value: name: "Homeowners" auto_update: to: "443456789012" add: first_word: "Join" remove: first_word: "Stop" GroupAutoUpdateSharedShortCode: summary: Create auto an update group for a shared short code value: name: "Patients at Clinic 2" auto_update: to: "54321" add: first_word: "West2" second_word: "Join" remove: first_word: "West2" second_word: "Stop" GroupAddRemoveList: summary: Add or remove a list of phone numbers value: add: ["+14058961234", "+447911123456", "+55987654321"] remove: ["+4612345678", "+15551235555"] GroupCreateParent: summary: Create a parent group description: Create a parent group that includes all members of groups with a certain ID. value: name: "New Munster" child_groups: ["01FC66621XXXXX119Z8PMV1QPQ", "01AB61221XXXXX119X8PMV1ABA"] GroupUpdateAdd: summary: Add or remove members from another group value: add_from_group: "01FC66621XXXXX119Z8PMV1QPQ" remove_from_group: "01AB61221XXXXX119X8PMV1ABA" GroupUpdateRemove: summary: Rename a group without changing its members value: name: "New group name" GroupUpdateNameKeepMembers: summary: Remove the name of a group without changing its members value: name: "string" GroupReplaceGroup: summary: Replace a group value: members: ["123456789", "987654321"] name: "New Name of the Group" ListGroupQuantity: summary: Retrieve the first 30 groups value: page: 0 count: 30 ListGroupPage: summary: Retrieve a certain page with a defined page size # description: Retrieve the third page of groups with a page size of 50. value: page: 3 page_size: 50 GroupList: summary: Retrieve a list of groups value: page: 50 page_size: 50 count: 1 groups: - name: My First Group members: ["+14155553421", "+13435552671", "+14325552677"] child_groups: [] auto_update: to: "+453234457784" add: first_word: join second_word: add remove: first_word: leave second_word: remove schemas: GroupList: type: object properties: page: type: integer description: "The requested page." example: 50 page_size: type: integer description: "The number of groups returned in this request" example: 50 count: type: integer description: "The total number of groups." example: 1 groups: type: array items: $ref: "#/components/schemas/groupObject" DryRunResponse: type: object properties: number_of_recipients: type: integer description: The number of recipients in the batch number_of_messages: type: integer description: The total number of SMS message parts to be sent in the batch per_recipient: type: array description: "The recipient, the number of message parts to this recipient, the body of the message, and the encoding type of each message" items: type: object properties: recipient: type: string number_of_parts: type: integer body: type: string encoding: type: string ReplacedGroup: type: object required: - members properties: name: type: string maxItems: 20 description: |- Name of group. members: type: array maxItems: 10000 description: |- The initial members of the group. Constraints: Elements must be phone numbers in E.164 format MSISDNs. items: $ref: "#/components/schemas/msisdn" UpdateGroup: type: object properties: name: type: [string, "null"] maxLength: 20 description: The name of the group. Omitting `name` from the JSON body will leave the name unchanged. To remove an existing name set, name explicitly to the JSON value `null`. add: type: array description: Add a list of phone numbers (MSISDNs) to this group. The phone numbers are a strings within an array and must be in E.164 format. remove: type: array description: Remove a list of phone numbers (MSISDNs) to this group.The phone numbers are a strings within an array and must be in E.164 format. add_from_group: type: string description: |- Copy the members from the another group into this group. Constraints: Must be valid group ID remove_from_group: type: string description: |- Remove the members in a specified group from this group. Constraints: Must be valid group ID auto_update: type: object properties: to: type: string description: |- Short code or long number addressed in MO. Constraints: Must be valid phone number or short code which has been **provisioned by your account manager**. add: type: object properties: first_word: type: string pattern: '^\w+$' description: |- Keyword to be sent in MO to add phone number to a group opt-in keyword like "JOIN". If `auto_update.to` is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code. Constraints: Must be one word. maxLength: 15 second_word: type: string pattern: '^\w+$' description: |- Opt-in keyword like "JOIN" if auto_update.to is shared short code. Constraints: Must be one word. maxLength: 15 remove: type: object description: Keyword to be sent in MO to remove from a group. properties: first_word: type: string pattern: '^\w+$' description: |- Opt-out keyword. For example, "LEAVE" if `auto_update.to` is a dedicated long/short number or a unique brand keyword like "Sinch" (if it is a shared short code). Constraints: Must be one word. maxLength: 15 second_word: type: string pattern: '^\w+$' description: |- Opt-out keyword. For example, "LEAVE" if `auto_update.to` is a shared short code. Constraints: Must be one word. maxLength: 15 recipients: type: array items: $ref: '#/components/schemas/msisdn' errorResponseObj: type: object properties: code: type: string description: The error code. See [error codes](/docs/sms/api-reference/#error-codes). text: type: string description: The human readable description of the error. GroupAutoUpdate: required: - to type: object properties: to: type: string description: |- Short code or long number addressed in MO. Constraints: Must be valid phone number or short code which has been **provisioned by your account manager**. format: E.164 example: +15551231234 add: $ref: '#/components/schemas/addKeyword' remove: $ref: '#/components/schemas/removeKeyword' addKeyword: type: string removeKeyword: type: string createGroupResponse: type: object properties: id: type: string description: The ID used to reference this group. example: 01FC66621XXXXX119Z8PMV1QPU name: maxLength: 20 minLength: 1 type: string description: Name of group, if set. example: My new customers size: type: integer description: The number of members currently in the group. format: int32 readOnly: true example: 2 created_at: type: string description: |- Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ format: date-time readOnly: true modified_at: type: string description: |- Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ format: date-time readOnly: true child_groups: maxItems: 10 minItems: 0 uniqueItems: true type: array description: |- Phone numbers (MSISDNs) of child group will be included in this group. If present, this group will be auto populated. Constraints: Elements must be group IDs. example: - 01FC66621XXXXX119Z8PMV1AHY items: $ref: '#/components/schemas/MtGroupId' auto_update: $ref: '#/components/schemas/GroupAutoUpdate' MtGroupId: type: object description: |- Phone numbers (MSISDNs) of a child group will be included in this group. If present, this group will be auto populated. Constraints: Elements must be group IDs. example: - 01FC66621XXXXX119Z8PMV1AHY ApiGroup: type: object properties: id: type: string description: Unique identifier for the group readOnly: true example: 01FC66621XXXXX119Z8PMV1QPQ DeliveryReportList: type: object properties: count: type: integer description: The total number of entries matching the given filters. format: int64 example: 1 page: type: integer description: The requested page. format: int32 example: 0 page_size: type: integer description: The number of entries returned in this request. format: int32 example: 2 delivery_reports: type: array description: The page of delivery reports matching the given filters. items: $ref: '#/components/schemas/RecipientDeliveryReport' RecipientDeliveryReport: properties: applied_originator: type: string description: "The default originator used for the recipient this delivery\ \ report belongs to, if default originator pool configured and no originator\ \ set when submitting batch." at: type: string format: date-time description: "A timestamp of when the Delivery Report was created in the Sinch service. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`." batch_id: type: string description: The ID of the batch this delivery report belongs to example: 01FC66621XXXXX119Z8PMV1QPQ readOnly: true client_reference: type: string description: "The client identifier of the batch this delivery report belongs to, if set when submitting batch." code: type: integer format: int32 description: The detailed [status code](/docs/sms/api-reference/sms/tag/Delivery-reports/#tag/Delivery-reports/section/Delivery-report-error-codes). encoding: type: string description: Applied encoding for message. Present only if smart encoding is enabled. enum: - GSM - UNICODE example: GSM number_of_message_parts: type: integer format: int32 description: The number of parts the message was split into. Present only if `max_number_of_message_parts` parameter was set. example: 1 operator: type: string description: "The operator that was used for delivering the message to this recipient, if enabled on the account by Sinch." example: "35000" operator_status_at: type: string format: date-time description: "A timestamp extracted from the Delivery Receipt from the originating SMSC. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`." recipient: type: string description: Phone number that was queried. example: "15551231234" status: type: string description: The simplified status as described in _Delivery Report Statuses_. example: Delivered x-enumDescriptions: Queued: Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account. Dispatched: Intermediate type. Message has been dispatched and accepted for delivery by the SMSC. Aborted: Final type. Message was aborted before reaching the SMSC. Cancelled: Final type. Message was cancelled by user before reaching SMSC. Failed: Final type. Message failed to be delivered. Delivered: Final type. Message has been delivered. Expired: Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short. Rejected: Final type. Message was rejected by the SMSC. Deleted: Final type. Message was deleted by the SMSC. Unknown: Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received. type: type: string description: The recipient delivery report type. enum: - recipient_delivery_report_sms - recipient_delivery_report_mms required: - at - batch_id - code - recipient - status - type title: Recipient delivery report DeliveryReport: properties: batch_id: type: string description: The ID of the batch this delivery report belongs to. example: 01FC66621XXXXX119Z8PMV1QPQ readOnly: true client_reference: type: string description: The client identifier of the batch this delivery report belongs to, if set when submitting batch. statuses: type: array description: Array with status objects. Only status codes with at least one recipient will be listed. items: $ref: '#/components/schemas/MessageDeliveryStatus' total_message_count: type: integer format: int32 description: The total number of messages in the batch. example: 2 minimum: 0 type: type: string description: The delivery report type. enum: - delivery_report_sms - delivery_report_mms required: - batch_id - statuses - total_message_count - type title: Delivery report MessageDeliveryStatus: description: Array with status objects. Only status codes with at least one recipient will be listed. properties: code: type: integer format: int32 description: The detailed [status code](/docs/sms/api-reference/sms/tag/Delivery-reports/#tag/Delivery-reports/section/Delivery-report-error-codes). count: type: integer format: int32 description: The number of messages that currently has this code. example: 2 minimum: 1 recipients: type: array description: Only for `full` report. A list of the phone number recipients which messages has this status code. example: - "15551231234" - "15551256344" items: type: string description: Only for `full` report. A list of the phone number recipients which messages has this status code. example: "[\"15551231234\",\"15551256344\"]" uniqueItems: true status: type: string description: The simplified status as described in _Delivery Report Statuses_. example: Delivered x-enumDescriptions: Queued: Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account. Dispatched: Intermediate type. Message has been dispatched and accepted for delivery by the SMSC. Aborted: Final type. Message was aborted before reaching the SMSC. Cancelled: Final type. Message was cancelled by user before reaching SMSC. Failed: Final type. Message failed to be delivered. Delivered: Final type. Message has been delivered. Expired: Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short. Rejected: Final type. Message was rejected by the SMSC. Deleted: Final type. Message was deleted by the SMSC. Unknown: Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received. required: - code - count - recipients - status ApiBatchList: properties: count: type: integer format: int64 description: The total number of entries matching the given filters. example: 1 page: type: integer format: int32 description: The requested page. example: 0 batches: type: array description: The page of batches matching the given filters. items: oneOf: - $ref: '#/components/schemas/BinaryResponse' - $ref: '#/components/schemas/MediaResponse' - $ref: '#/components/schemas/TextResponse' page_size: type: integer format: int32 description: The number of entries returned in this request. example: 30 ApiUpdateBinaryMtMessage: allOf: - $ref: '#/components/schemas/ApiUpdateMtMessage' - type: object properties: body: type: string description: "The message content Base64 encoded. \n \n Max 140 bytes\ \ together with udh." udh: type: string description: The UDH header of a binary message HEX encoded. Max 140 bytes together with body. type: type: string description: SMS in binary format enum: - mt_binary from_ton: maximum: 6 minimum: 0 type: integer description: The type of number for the sender number. Use to override the automatic detection. format: int32 from_npi: maximum: 18 minimum: 0 type: integer description: Number Plan Indicator for the sender number. Use to override the automatic detection. format: int32 title: Update binary message ApiUpdateMmsMtMessage: allOf: - $ref: '#/components/schemas/ApiUpdateMtMessage' - type: object properties: body: $ref: '#/components/schemas/MediaBody' parameters: $ref: '#/components/schemas/parameterObj' type: type: string description: MMS enum: - mt_media strict_validation: default: false type: boolean description: | Whether or not you want the media included in your message to be checked against [Sinch MMS channel best practices](/docs/mms/bestpractices/). If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed. title: Update media message ApiUpdateMtMessage: type: object properties: from: type: string description: Sender number. Must be valid phone number, short code or alphanumeric. example: +15551231234 type: type: string to_add: type: array description: List of phone numbers and group IDs to add to the batch. items: $ref: '#/components/schemas/MtDestination' maxItems: 1000 minItems: 1 to_remove: type: array description: List of phone numbers and group IDs to remove from the batch. items: $ref: '#/components/schemas/MtDestination' maxItems: 1000 minItems: 1 delivery_report: type: string description: "Request delivery report callback. \n \n Note that delivery\ \ reports can be fetched from the API regardless of this setting. " x-enumDescriptions: none: No delivery report callback will be sent. summary: A single delivery report callback will be sent. full: A single delivery report callback will be sent which includes a list of recipients per delivery status. per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC. per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC. send_at: type: string format: date-time description: | If set, in the future the message will be delayed until `send_at` occurs. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`. Constraints: Must be before expire_at. If set in the past, messages will be sent immediately. expire_at: type: string format: date-time description: | If set, the system will stop trying to deliver the message at this point. Constraints: Must be after `send_at` Default: 3 days after `send_at` callback_url: type: string description: | Override the default callback URL for this batch. Constraints: Must be valid URL. maxLength: 2048 minLength: 0 ApiUpdateTextMtMessage: allOf: - $ref: '#/components/schemas/ApiUpdateMtMessage' - type: object properties: parameters: $ref: '#/components/schemas/parameterObj' body: type: string description: The message content example: "Hi ${name}! How are you?" maxLength: 2000 minLength: 0 type: type: string description: Regular SMS enum: - mt_text from_ton: maximum: 6 minimum: 0 type: integer description: The type of number for the sender number. Use to override the automatic detection. format: int32 from_npi: maximum: 18 minimum: 0 type: integer description: Number Plan Indicator for the sender number. Use to override the automatic detection. format: int32 max_number_of_message_parts: minimum: 1 type: integer description: Message will be dispatched only if it is not split to more parts than Max Number of Message Parts format: int32 truncate_concat: type: boolean description: If set to true the message will be shortened when exceeding one part. flash_message: type: boolean description: Shows message on screen without user interaction while not saving the message to the inbox. default: false title: Update text message ApiInboundList: properties: count: type: integer format: int64 description: The total number of inbounds matching the given filters example: 1 page: type: integer format: int32 description: The requested page. example: 0 inbounds: type: array description: The page of inbounds matching the given filters. items: oneOf: - $ref: '#/components/schemas/MOText' - $ref: '#/components/schemas/MOBinary' - $ref: '#/components/schemas/MOMedia' page_size: type: integer format: int32 description: The number of inbounds returned in this request. example: 50 ApiMoMessage: type: object description: The page of inbounds matching the given filters. properties: client_reference: type: string description: |- If this inbound message is in response to a previously sent message that contained a client reference, then this field contains *that* client reference. Utilizing this feature requires additional setup on your account. Contact your account manager to enable this feature. from: type: string description: The phone number that sent the message. More info example: "+11203494390" id: type: string description: The ID of this inbound message. example: 01FC66621XXXXX119Z8PMV1QPA operator_id: type: string description: The MCC/MNC of the sender's operator if known. example: "35000" received_at: type: string format: date-time description: |- When the system received the message. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`. sent_at: type: string format: date-time description: |- When the message left the originating device. Only available if provided by operator. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`. to: type: string description: The Sinch phone number or short code to which the message was sent. example: "11203453453" type: type: string readOnly: true required: - from - id - received_at - to - type MOBinary: allOf: - $ref: '#/components/schemas/ApiMoMessage' - type: object properties: body: type: string description: | The message content Base64 encoded. Max 140 bytes together with udh. type: type: string description: SMS in binary format enum: - mo_binary readOnly: true udh: type: string description: The UDH header of a binary message HEX encoded. Max 140 bytes together with body. required: - body - from - id - received_at - to - udh title: Binary MO MOText: allOf: - $ref: '#/components/schemas/ApiMoMessage' - type: object properties: body: type: string maxLength: 2000 minLength: 0 type: type: string description: Regular SMS enum: - mo_text readOnly: true required: - body - from - id - received_at - to title: Text MO MOMedia: allOf: - $ref: '#/components/schemas/ApiMoMessage' - type: object properties: body: type: object $ref: '#/components/schemas/MOMediaBody' type: type: string description: MMS enum: - mo_media readOnly: true required: - body - from - id - received_at - to title: Media MO ApiDeliveryFeedback: type: object required: - recipients properties: recipients: type: array description: A list of phone numbers (MSISDNs) that have successfully received the message. The key is required, however, the value can be an empty array (`[]`) for *a batch*. If the feedback was enabled for *a group*, at least one phone number is required. items: type: string description: List of recipients confirmed to have received their message. example: recipients: - "+15551231234" - "+15551256344" parameterObj: type: object additionalProperties: true properties: '{parameter_key}': maxLength: 16 minLength: 1 pattern: "^[A-Za-z0-9_\\-.]+$" type: object properties: '{msisdn}': maxLength: 1600 type: string description: The key is the recipient that should have the `parameter_key` replaced with the value default: maxLength: 1600 type: string description: |- The fall-back value for omitted recipient phone numbers MSISDNs. description: |- The name of the parameter that will be replaced in the message body. Letters A-Z and a-z, digits 0-9 and .-_ allowed. description: |- Contains the parameters that will be used for customizing the message for each recipient. [Click here to learn more about parameterization](/docs/sms/resources/message-info/message-parameterization). MtDestination: type: string description: |- List of phone numbers and group IDs that will receive the batch. More info. format: E.164 example: - +15551231234 - +15551256344 TextRequest: required: - body - to type: object properties: to: maxItems: 1000 minItems: 1 type: array description: List of Phone numbers and group IDs that will receive the batch. More info format: E.164 example: - +15551231234 - +15551256344 items: $ref: '#/components/schemas/MtDestination' from: type: string description: "Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured." example: +15551231234 parameters: $ref: '#/components/schemas/parameterObj' body: maxLength: 2000 minLength: 0 type: string description: The message content example: "Hi ${name}! How are you?" type: type: string description: Regular SMS enum: - mt_text delivery_report: type: string description: Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. default: none x-enumDescriptions: none: No delivery report callback will be sent. summary: A single delivery report callback will be sent. full: A single delivery report callback will be sent which includes a list of recipients per delivery status. per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC. per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC. send_at: type: string description: |- If set in the future, the message will be delayed until `send_at` occurs. Must be before `expire_at`. If set in the past, messages will be sent immediately. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`. format: date-time example: "2024-08-07T12:34:56.789Z" expire_at: type: string description: |- If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`. format: date-time callback_url: maxLength: 2048 minLength: 0 type: string description: Override the *default* callback URL for this batch. Must be a valid URL. Learn how to set a default callback URL here. client_reference: maxLength: 2048 minLength: 0 type: string description: The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch feedback_enabled: type: boolean description: "If set to `true`, then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery." default: false flash_message: type: boolean description: Shows message on screen without user interaction while not saving the message to the inbox. default: false truncate_concat: type: boolean description: If set to `true` the message will be shortened when exceeding one part. max_number_of_message_parts: minimum: 1 type: integer description: Message will be dispatched only if it is not split to more parts than Max Number of Message Parts format: int32 from_ton: maximum: 6 minimum: 0 type: integer description: The type of number for the sender number. Use to override the automatic detection. format: int32 from_npi: maximum: 18 minimum: 0 type: integer description: Number Plan Indicator for the sender number. Use to override the automatic detection. format: int32 TextResponse: type: object properties: id: type: string description: Unique identifier for batch readOnly: true example: 01FC66621XXXXX119Z8PMV1QPQ to: maxItems: 1000 minItems: 1 type: array description: "List of Phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)" format: E.164 example: - +15551231234 - +15551256344 items: $ref: '#/components/schemas/MtDestination' from: type: string description: "Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured." example: +15551231234 canceled: type: boolean description: Indicates if the batch has been canceled or not. readOnly: true default: false parameters: $ref: '#/components/schemas/parameterObj' body: maxLength: 2000 minLength: 0 type: string description: The message content example: "Hi ${name}! How are you?" type: type: string description: Regular SMS enum: - mt_text readOnly: true # campaign_id: # type: string # description: "The [campaign and service IDs](https://dashboard.sinch.com/sms/us-campaigns) this message belongs to. You generate your own campaign and service IDs. US only." created_at: type: string description: "Timestamp for when batch was created. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):`YYYY-MM-DDThh:mm:ss.SSSZ`." format: date-time readOnly: true modified_at: type: string description: "Timestamp for when batch was last updated. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):`YYYY-MM-DDThh:mm:ss.SSSZ`." format: date-time readOnly: true delivery_report: type: string description: "Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. " default: none x-enumDescriptions: none: No delivery report callback will be sent. summary: A single delivery report callback will be sent. full: A single delivery report callback will be sent which includes a list of recipients per delivery status. per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC. per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC. send_at: type: string description: "If set in the future, the message will be delayed until `send_at` occurs. Must be before `expire_at`. If set in the past, messages will be sent immediately. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`." format: date-time expire_at: type: string description: "If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`." format: date-time callback_url: maxLength: 2048 minLength: 0 type: string description: "Override the default callback URL for this batch. Must be valid URL." client_reference: maxLength: 2048 minLength: 0 type: string description: The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch example: "myReference" feedback_enabled: type: boolean description: If set to `true`, then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery. default: false flash_message: type: boolean description: Shows message on screen without user interaction while not saving the message to the inbox. default: false truncate_concat: type: boolean description: If set to `true` the message will be shortened when exceeding one part. max_number_of_message_parts: minimum: 1 type: integer description: Message will be dispatched only if it is not split to more parts than Max Number of Message Parts format: int32 from_ton: maximum: 6 minimum: 0 type: integer description: The type of number for the sender number. Use to override the automatic detection. format: int32 from_npi: maximum: 18 minimum: 0 type: integer description: Number Plan Indicator for the sender number. Use to override the automatic detection. format: int32 groupObject: type: object properties: name: type: string maxLength: 20 description: "Name of the group" members: type: array maxItems: 10000 items: $ref: "#/components/schemas/msisdn" description: |- "Initial list of phone numbers in E.164 format MSISDNs for the group." child_groups: type: array description: |- Phone numbers (MSISDNs) of child group will be included in this group. If present then this group will be auto populated. Constraints: Elements must be group IDs. maxItems: 10 items: type: string description: Group ID auto_update: type: object properties: to: type: string description: |- Short code or long number addressed in MO. Constraints: Must be valid phone number or short code which has been **provisioned by your account manager**. add: type: object properties: first_word: type: string pattern: '^\w+$' description: |- Keyword to be sent in MO to add phone number to a group opt-in keyword like "JOIN". If `auto_update.to` is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code. Constraints: Must be one word. maxLength: 15 second_word: type: string pattern: '^\w+$' description: |- Opt-in keyword like "JOIN" if auto_update.to is shared short code. Constraints: Must be one word. maxLength: 15 remove: type: object description: Keyword to be sent in MO to remove from a group. properties: first_word: type: string pattern: '^\w+$' description: |- Opt-out keyword like "LEAVE" If auto_update.to is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code. Constraints: Must be one word. maxLength: 15 minLength: 1 second_word: type: string pattern: '^\w+$' description: |- Opt-out keyword like "LEAVE" if auto_update.to is shared short code. Constraints: Must be one word. maxLength: 15 minLength: 1 msisdn: type: string format: E.164 description: |- A phone number in E.164 format. example: "+453234457784" BinaryRequest: required: - body - to - udh type: object properties: to: maxItems: 1000 minItems: 1 type: array description: "A list of phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)." format: E.164 example: - +15551231234 - +15551256344 items: $ref: '#/components/schemas/MtDestination' from: type: string description: "Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured." example: +15551231234 body: type: string description: |- The message content Base64 encoded. Max 140 bytes including `udh`. udh: type: string description: The UDH header of a binary message HEX encoded. Max 140 bytes including the `body`. type: type: string description: SMS in binary format. enum: - mt_binary delivery_report: type: string description: "Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. " default: none x-enumDescriptions: none: No delivery report callback will be sent. summary: A single delivery report callback will be sent. full: A single delivery report callback will be sent which includes a list of recipients per delivery status. per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC. per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC. send_at: type: string description: |- If set in the future the message will be delayed until `send_at` occurs. Must be before `expire_at`. If set in the past, messages will be sent immediately. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`. format: date-time example: "2024-08-07T12:34:56.789Z" expire_at: type: string description: |- If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`. format: date-time callback_url: maxLength: 2048 minLength: 0 type: string description: Override the *default* callback URL for this batch. Must be a valid URL. Learn how to set a default callback URL here. client_reference: maxLength: 2048 minLength: 0 type: string description: The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch. feedback_enabled: type: boolean description: |- If set to true then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery. default: false from_ton: maximum: 6 minimum: 0 type: integer description: The type of number for the sender number. Use to override the automatic detection. format: int32 from_npi: maximum: 18 minimum: 0 type: integer description: Number Plan Indicator for the sender number. Use to override the automatic detection. format: int32 BinaryResponse: type: object properties: id: type: string description: Unique identifier for batch. readOnly: true example: 01FC66621XXXXX119Z8PMV1QPQ to: maxItems: 1000 minItems: 1 type: array description: "A list of phone numbers and group IDs that have received the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)." format: E.164 example: - +15551231234 - +15551256344 items: $ref: '#/components/schemas/MtDestination' from: type: string description: |- The sender number provided. Required if the Automatic Default Originator is not configured. example: +15551231234 canceled: type: boolean description: Indicates whether or not the batch has been canceled. readOnly: true default: false body: type: string description: |- The message content provided. Base64 encoded. udh: type: string description: The UDH header of a binary message HEX encoded. Max 140 bytes including the `body`. type: type: string description: SMS in binary format. enum: - mt_binary created_at: type: string description: |- Timestamp for when batch was created. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`. format: date-time readOnly: true modified_at: type: string description: |- Timestamp for when batch was last updated. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`. format: date-time readOnly: true delivery_report: type: string description: The delivery report callback option selected. Will be either `none`, `summary`, `full`, `per_recipient`, or `per_recipient_final`. default: none send_at: type: string description: |- If set, the date and time the message should be delivered. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`. format: date-time expire_at: type: string description: |- If set, the date and time the message will expire. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`. format: date-time callback_url: maxLength: 2048 minLength: 0 type: string description: The callback URL provided in the request. client_reference: maxLength: 2048 minLength: 0 type: string description: The string input to identify this batch message. If set, the identifier will be added in the delivery report/callback of this batch. feedback_enabled: type: boolean description: |- If set to true, then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery. default: false from_ton: maximum: 6 minimum: 0 type: integer description: The type of number for the sender number. format: int32 from_npi: maximum: 18 minimum: 0 type: integer description: Number Plan Indicator for the sender number. format: int32 MediaRequest: description: "Only available in the US. Contact your account manager if you wish to send MMS." properties: to: type: array format: E.164 description: List of Phone numbers and group IDs that will receive the batch. More info example: - +15551231234 - +15551256344 items: $ref: '#/components/schemas/MtDestination' maxItems: 1000 minItems: 1 from: type: string description: "Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured." example: +15551231234 body: $ref: '#/components/schemas/MediaBody' parameters: $ref: '#/components/schemas/parameterObj' type: type: string description: MMS enum: - mt_media delivery_report: type: string default: none description: Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. x-enumDescriptions: none: No delivery report callback will be sent. summary: A single delivery report callback will be sent. full: A single delivery report callback will be sent which includes a list of recipients per delivery status. per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC. per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC. send_at: type: string format: date-time description: | If set in the future, the message will be delayed until `send_at` occurs. Must be before `expire_at`. If set in the past, messages will be sent immediately. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`. expire_at: type: string format: date-time description: | If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`. callback_url: type: string description: Override the default callback URL for this batch. Must be valid URL. maxLength: 2048 minLength: 0 client_reference: type: string description: The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch maxLength: 2048 minLength: 0 feedback_enabled: type: boolean default: false description: "If set to `true`, then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery." strict_validation: default: false type: boolean description: | Whether or not you want the media included in your message to be checked against [Sinch MMS channel best practices](/docs/mms/bestpractices/). If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed. required: - body - to MediaResponse: properties: id: type: string description: Unique identifier for batch example: 01FC66621XXXXX119Z8PMV1QPQ readOnly: true to: type: array format: E.164 description: "List of Phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)" example: - +15551231234 - +15551256344 items: $ref: '#/components/schemas/MtDestination' maxItems: 1000 minItems: 1 from: type: string description: "Sender number.\n \n Required if Automatic Default Originator\ \ not configured." example: +15551231234 canceled: type: boolean default: false description: Indicates if the batch has been canceled or not. readOnly: true body: $ref: '#/components/schemas/MediaBody' parameters: $ref: '#/components/schemas/parameterObj' type: type: string description: Media message enum: - mt_media readOnly: true created_at: type: string format: date-time description: "Timestamp for when batch was created. \n \n YYYY-MM-DDThh:mm:ss.SSSZ\ \ format" readOnly: true modified_at: type: string format: date-time description: "Timestamp for when batch was last updated. \n \n YYYY-MM-DDThh:mm:ss.SSSZ\ \ format" readOnly: true delivery_report: type: string default: none description: "Request delivery report callback. \n \n Note that delivery\ \ reports can be fetched from the API regardless of this setting. " x-enumDescriptions: none: No delivery report callback will be sent. summary: A single delivery report callback will be sent. full: A single delivery report callback will be sent which includes a list of recipients per delivery status. per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC. per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC. send_at: type: string format: date-time description: "If set in the future the message will be delayed until send_at\ \ occurs. \n \n Must be before `expire_at`. \n \n If set in the past messages\ \ will be sent immediately. \n \n YYYY-MM-DDThh:mm:ss.SSSZ format" example: "2024-08-07T12:34:56.789Z" expire_at: type: string format: date-time description: "If set the system will stop trying to deliver the message\ \ at this point. \n \n Must be after `send_at`. Default and max is 3 days\ \ after send_at. \n \n YYYY-MM-DDThh:mm:ss.SSSZ format" callback_url: type: string description: Override the default callback URL for this batch. Must be valid URL. maxLength: 2048 minLength: 0 client_reference: type: string description: "The client identifier of a batch message. If set, the identifier\ \ will be added in the delivery report/callback of this batch" maxLength: 2048 minLength: 0 feedback_enabled: type: boolean default: false description: "If set to true then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback)\ \ is expected after successful delivery." strict_validation: type: boolean description: | Whether or not you want the media included in your message to be checked against [Sinch MMS channel best practices](/docs/mms/bestpractices/). If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed. MediaBody: description: The message content, including a URL to the media file properties: subject: maxLength: 80 minLength: 0 type: string description: The subject text example: Media message from Sinch! message: type: string description: The message text. Text only media messages will be rejected, please use SMS instead. example: Your text message. maxLength: 2000 minLength: 0 url: type: string description: URL to the media file example: https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png maxLength: 2048 minLength: 0 required: - url MOMediaBody: type: object description: The message content, including a URL to the media filters. properties: subject: type: string description: The subject of the MMS media message. message: type: string description: The text message content of the MMS media message. media: type: array items: type: object properties: url: type: string description: URL to the media file contentType: type: string description: The type of media file included in the message status: type: string description: The status of the media upload code: type: integer securitySchemes: BearerAuth: type: http scheme: bearer description: | Your API token is sent in the `Authorization` header preceded by `Bearer`. You'll have an API token per `service_plan_id`. Both can be found in the [Sinch Customer Dashboard](https://dashboard.sinch.com/sms/api/rest). Double check that you're using the correct region in your base URL. parameters: # path parameters service_plan_id: name: service_plan_id in: path required: true description: Your service plan ID. You can find this on your [Dashboard](https://dashboard.sinch.com/sms/api/rest). schema: type: string example: jd63jf88477ll123ab4567cd89012ef3 batch_id: name: batch_id in: path required: true description: The batch ID you received from sending a message. schema: type: string example: 01FC66621XXXXX119Z8PMV1QPQ inbound_id: name: inbound_id in: path required: true description: The inbound ID found when listing inbound messages. schema: type: string example: 01FC66621XXXXX119Z8PMV1QPA group_id: name: group_id in: path required: true description: ID of a group that you are interested in getting. schema: type: string recipient_msisdn: name: recipient_msisdn in: path required: true description: Phone number for which you to want to search. schema: type: string example: "+134848393506" # query parameters page: name: page in: query description: The page number starting from 0. schema: type: integer minimum: 0 default: 0 example: 2 tags: - name: Batches description: |- Batches are sets of SMS messages. You can send a single message or many. Batches are queued and sent at the rate limit in first-in-first-out order. - name: Delivery reports description: |- The REST API uses message statuses and error codes in delivery reports, which refer to the state of the batch and can be present in either [Retrieve a delivery report](/docs/sms/api-reference/sms/tag/Delivery-reports/#tag/Delivery-reports/operation/GetDeliveryReportByBatchId) or sent as a callback. ## Delivery report statuses The status field describes which state a particular message is in. Note that statuses of type Intermediate will only be reported if you request a status `per_recipient` or `per_recipient_final` ([Retrieve a recipient delivery report](/docs/sms/api-reference/sms/tag/Delivery-reports/#tag/Delivery-reports/operation/GetDeliveryReportByPhoneNumber)). The following statuses are available when using the SMS REST API: | Status | Type | Description | | ------------ | ------------ | --------------------------------------------- | | `Queued` | Intermediate | Message is queued within REST API system and will be dispatched according to the rate of the account. | | `Dispatched` | Intermediate | Message has been dispatched and accepted for delivery by the SMSC. | | `Aborted` | Final | Message was aborted before reaching the SMSC. | | `Cancelled` | Final | Message was cancelled by user before reaching SMSC. | | `Rejected` | Final | Message was rejected by the SMSC. | | `Deleted` | Final | Message has been deleted. Message was deleted by a remote SMSC. This may happen if the destination is an invalid MSISDN or opted out subscriber. | | `Delivered` | Final | Message has been delivered. | | `Failed` | Final | Message failed to be delivered. | | `Expired` | Final | Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short. | | `Unknown` | Final | Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received. | ## Delivery report error codes The delivery report status code provides a more detailed view of what happened with a message. The REST API error codes are a combination of [SMPP error codes](/docs/sms/smpp/error-codes/#status-reports-error-codes), [MMS error codes](/docs/mms/7-service/mms-status-codes/) and custom codes. The REST API custom error codes are all within the 4xx range. These are listed below: | Status Code | Name | Status | Description | | ----------------- | ---------------------------- | ------------ | --------------------------------------------------------- | | 400 | Queued | `Queued` | Message is queued within REST API system and will be dispatched according to the rate of the account. | | 401 | Dispatched | `Dispatched` | Message has been dispatched to SMSC. | | 402 | Message unroutable | `Aborted` | SMSC rejected message. Retrying is likely to cause the same error. | | 403 | Internal error | `Aborted` | An unexpected error caused the message to fail. | | 404 | Temporary delivery failure | `Aborted` | Message failed because of temporary delivery failure. Message can be retried. | | 405 | Unmatched Parameter | `Aborted` | One or more parameters in the message body has no mapping for this recipient. See [Message Parameterization](../../../../resources/message-info/message-parameterization/) | | 406 | Internal Expiry | `Aborted` | Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short. | | 407 | Cancelled | `Cancelled` | Message was cancelled by user before reaching SMSC. | | 408 | Internal Reject | `Aborted` | SMSC rejected the message. Retrying is likely to cause the same error. | | 410 | Unmatched default originator | `Aborted` | No default originator exists/configured for this recipient when sending message without originator. | | 411 | Exceeded parts limit | `Aborted` | Message failed as the number of message parts exceeds the defined max number of message parts. | | 412 | Unprovisioned region | `Aborted` | SMSC rejected the message. The account hasn't been provisioned for this region. | | 413 | Blocked | `Aborted` | The account is blocked. Reach out to support for help. Potentially out of credits. | | 414 | Bad Media | `Aborted` | MMS only, the request failed due to a bad media URL. It is possible that the URL was unreachable, or sent a bad response. | | 415 | Delivery report Rejected | `Failed` | MMS only, message reached MMSC but was rejected by MMS gateway or mobile network. | | 416 | Delivery report Not Supported| `Failed` | MMS only, message reached MMSC but it is not supported. | | 417 | Delivery report Unreachable | `Failed` | MMS only, message reached MMSC but the destination network or the mobile subscriber cannot be reached. | | 418 | Delivery report Unrecognized | `Failed` | MMS only, message reached MMSC but the handset of the mobile subscriber does not recognize the message content. | - name: Inbounds description: |- Inbounds, or Mobile Originated (MO) messages, are incoming messages. Inbound messages can be listed and retrieved like batch messages and they can also be delivered by callback requests like delivery reports. ## MMS Media error codes The REST API handles MO media messages by uploading them to specified s3 storage location and providing the URL to download the attachment. On a successful upload, the code will be `0`. If the upload fails, the code will be a value other than `0`. | Status Code | Name | Status | Description | | --------------- | ---------------------------- | ------------ | --------------------------------------------------------- | | 0 | Uploaded | `Uploaded` | Attachment successfully uploaded to storage. | | 1 | Internal failure | `Failed` | Internal exception happened during upload. | | 2 | Bucket not found | `Failed` | Provisioned bucket doesn't exist. | - name: Groups description: A group is a set of phone numbers (or [MSISDNs](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)) that can be used as a target when sending an SMS. An phone number (MSISDN) can only occur once in a group and any attempts to add a duplicate are ignored but not rejected. - name: Webhooks description: |- ## Callbacks A callback is an HTTP POST request with a notification made by the Sinch SMS REST API to a URI of your choosing. The REST API expects the receiving server to respond with a response code within the `2xx` success range. For `5xx` the callback will be retried. For `429` the callback will be retried and the throughput will be lowered. For other status codes in the `4xx` range the callback will not be retried. The first initial retry will happen 5 seconds after the first try. The next attempt is after 10 seconds, then after 20 seconds, after 40 seconds, after 80 seconds, doubling on every attempt. The last retry will be at 81920 seconds (or 22 hours 45 minutes) after the initial failed attempt. Note that, with these callbacks, the Sinch SMS REST API will make a request to the URI of your choosing. This means that Sinch will be authenticating against **your system**. By making a request to your account manager, SMS REST API callbacks may be configured with the following options: - **Basic authentication** is the simplest form of authentication. It enables access to the SMS API via a username and password. Basic Auth can be utilised in a callback by provisioning the callback URL with the appropriate username and password. Note that, because callbacks are made by Sinch to a URI of your choosing (rather than a call made by your system to Sinch's endpoints), the username and password must be accepted by **your system**. - **OAuth 2.0** is a standard form of authentication that provides enhanced security when compared to Basic Authentication. It uses access tokens to reduce the risk of credentials being intercepted. OAuth 2.0 can be utilised in a callback by provisioning the callback URL with username, password and the URL to fetch OAuth access token. Note that, because callbacks are made by Sinch to a URI of your choosing (rather than a call made by your system to Sinch's endpoints), the username, password, and and access token URL must be accepted by **your system**. - **HMAC** Hash-based message authentication code. It is a cryptographic authentication technique that uses a hash function and a secret key. HMAC can also be configured alongside Basic Auth and OAuth. - **AWS SNS** is a managed service that provides message delivery from publishers to subscribers by routing messages through SNS topics. Users can utilise AWS SNS in a callback by provisioning the callback URL with an Access Key ID, Secret Key and Region.