> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wavix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send SMS messages

> Send, manage, and track SMS and MMS messages using the Wavix Messaging API, including Sender ID registration and message delivery.

## Prerequisites

* Before you can use the Wavix Messaging API, you need to [create a Wavix account](/getting-started/create-account).
* You also need to [create or get your API key](/api-reference/authentication).

## Sender ID registration

A Sender ID is what recipients see as the message sender on their devices. It can be a numeric (phone numbers) or alphanumeric (brand names) Sender IDs. Before you send an SMS message, register your Sender ID on the Wavix platform.

**Alphanumeric Sender ID:**

* Must be between 3 and 11 characters long.
* Can contain uppercase and lowercase ASCII letters, digits, hyphen (-), plus (+), underscore (\_), ampersand (&), and space.
* Should not contain only digits.

**Numeric Sender ID:**

* Must be an SMS-enabled DID on your account.
* Third-party numbers and DIDs that do not support inbound SMS cannot be used as a Sender ID.

You can register Sender IDs in the Wavix portal or by using the API.

## Register a Sender ID using the app

<Steps>
  <Step title="Access Sender ID registration">
    1. Sign in to your [Wavix account](https://app.wavix.com).
    2. In the top menu, select **SMS** → **Sender IDs**.
    3. Select **Create new**.
  </Step>

  <Step title="Select Sender ID type">
    * Select **Alphanumeric** to use a brand or service name as your Sender ID.
    * Select **Numeric** to use a phone number as your Sender ID.
      Then select **Next**.
          <img src="https://mintcdn.com/wavix/kBvJ34HqZKc5EMhB/messaging/images/sms/sms-create-senderid-type.png?fit=max&auto=format&n=kBvJ34HqZKc5EMhB&q=85&s=f3ae8d7212845f0e524dc60d6588054e" alt="Sender ID registration (type) screenshot" title="Sender ID registration (type)" style={{ width:"70%" }} className="mx-auto" width="1396" height="678" data-path="messaging/images/sms/sms-create-senderid-type.png" />
  </Step>

  <Step title="Select destination countries">
    Select your destination countries. Sender ID regulation varies by country and Sender ID type; some destinations may be unavailable. Then select **Next**.

    <img src="https://mintcdn.com/wavix/kBvJ34HqZKc5EMhB/messaging/images/sms/sms-create-senderid-destination.png?fit=max&auto=format&n=kBvJ34HqZKc5EMhB&q=85&s=aed2a9714ee001c00766ae2e0d71f7f0" alt="Sender ID registration (destinations) screenshot" title="Sender ID registration (destinations)" style={{ width:"70%" }} className="mx-auto" width="1420" height="1832" data-path="messaging/images/sms/sms-create-senderid-destination.png" />
  </Step>

  <Step title="Select use case">
    Select your use case for messaging. Options include Promotional, Transactional, or Authentication. Enter your Sender ID name, estimate your monthly message volume, and provide sample messages you plan to send.
    Then select **Next**.

    <img src="https://mintcdn.com/wavix/kBvJ34HqZKc5EMhB/messaging/images/sms/sms-create-senderid-usecase.png?fit=max&auto=format&n=kBvJ34HqZKc5EMhB&q=85&s=d68451526edea33091549761fbd7b7ea" alt="Sender ID registration (use case) screenshot" title="Sender ID registration (use case)" style={{ width:"70%" }} className="mx-auto" width="1120" height="2284" data-path="messaging/images/sms/sms-create-senderid-usecase.png" />
  </Step>

  <Step title="Summary and confirmation">
    Review the Sender ID, type, and destination countries. Your Sender ID will be automatically allow-listed for countries where no additional paperwork is required. Countries that require manual registration will be highlighted.
    Select **Confirm**.
    You can immediately start sending messages to countries that do not require manual sender ID registration.
  </Step>
</Steps>

## Register a Sender ID using the API

Sender ID regulations vary by country. You can register a Sender ID using the API only in countries where it can be provisioned in self-service mode. To check if a numeric or alphanumeric Sender ID can be registered in self-service mode for a particular country, use:

```http theme={null}
GET https://api.wavix.com/v3/messages/sender_ids/restrictions?country=country_code&type=sender_type
Authorization: Bearer your_api_key
```

* `country_code`: 2-letter ISO code of the country
* `sender_type`: Sender ID type, can be either `numeric` or `alphanumeric`

All parameters are required.

If successful, the method returns the `HTTP 200 OK` status code. The response body indicates if a numeric or an alphanumeric Sender ID can be registered in self-service mode in the country.

```json theme={null}
{
    "self_service": true
}
```

If the `self_service` attribute value is `true`, the Sender ID can be registered using the API. Otherwise, create the Sender ID in the Wavix portal and go through the review or registration procedure.

To [register a new Sender ID](/api-reference/sms-and-mms/create-a-sender-id), use the following method:

```http theme={null}
POST https://api.wavix.com/v3/messages/sender_ids
Authorization: Bearer your_api_key
Content-Type: application/json
```

Paste the following JSON in the request body:

```json theme={null}
{
    "sender_id": "1313xxxxxxx",
    "countries": [
        "US"
    ],
    "type": "numeric"
}
```

* `sender_id`: the name of the Sender ID
* `countries`: an array of countries the Sender ID needs to be registered in
* `type`: Sender ID type

If successful, the method returns the `HTTP 200 OK` status code. The response body contains the Sender ID details.

```json theme={null}
{
   "id": "94b319e0-8277-4efa-b7ec-d6e0e255ddaf",
   "allowlisted_in": [
       "US"
   ],
   "sender_id": "1313xxxxxxx",
   "type": "numeric"
}
```

* `id`: system-generated unique ID of the Sender ID
* `allowlisted_in`: an array of countries the Sender ID is automatically provisioned in
* `sender_id`: name of the Sender ID
* `type`: sender ID type

## Get a list of Sender IDs on the account

To [get a list of Sender IDs](/api-reference/sms-and-mms/list-sender-ids), use the following method. This method does not require any parameters.

```http theme={null}
GET https://api.wavix.com/v3/messages/sender_ids
Authorization: Bearer your_api_key
```

If successful, the method returns the `HTTP 200 OK` status code. The response body contains an array of Sender IDs provisioned on the account and their details.

```json theme={null}
{
   "items": [
       {
           "id": "5108c63f-af4d-4852-88e0-ce06e82db5d3",
           "allowlisted_in": [
               "GB",
               "FR"
           ],
           "sender_id": "Wavix",
           "type": "alphanumeric"
       },
       {
           "id": "94b319e0-8277-4efa-b7ec-d6e0e255ddaf",
           "allowlisted_in": [
               "US",
               "CA" 
           ],
           "sender_id": "1313xxxxxxx",
           "type": "numeric"
       }
   ]
}
```

* `id`: unique ID of the Sender ID
* `allowlisted_in`: an array of countries the Sender ID is automatically provisioned in
* `sender_id`: the name of the Sender ID
* `type`: Sender ID type

## Delete a Sender ID

To [delete a Sender ID](/api-reference/sms-and-mms/delete-a-sender-id), use the following method:

```http theme={null}
DELETE https://api.wavix.com/v3/messages/sender_ids/id
Authorization: Bearer your_api_key
Content-Type: application/json
```

* `id`: unique ID of the Sender ID

If successful, the method returns the `HTTP 204 No Content` status code without the response body.

## Send a message

*Using a sandbox account? A few rules apply to this request—see [Sandbox](/getting-started/sandbox).*

To [send an SMS or MMS message](/api-reference/sms-and-mms/send-a-message), use the following method:

```http theme={null}
POST https://api.wavix.com/v3/messages
Authorization: Bearer your_api_key
Content-Type: application/json
```

Paste the following JSON in the request body:

```json theme={null}
{
   "from": "SenderID",
   "to": "1686xxxxxxx",
   "message_body": {
       "text": "Message text.",
       "media": ["https://publicly-available-resource.com/media"]
   }
}
```

* `from`: the Sender ID to be used to send an SMS, must be a registered Sender ID on your account.
* `to`: the recipient phone number, must be in E.164 format (international format with + and country code, e.g., +12015551234).
* `message_body.text`: the text of the SMS message to be sent.
* `message_body.media`: an array of URLs to media files to be included in the message attachments. In case the parameter is specified and its value is different from `null`, the message will be sent as MMS. The URLs must point to publicly available resources.

All parameters are required.

If successful, the service returns the `HTTP 201 Created` status code. The response body contains the sent message details.

Response example:

```json theme={null}
{
  "message_id": "871b4eeb-f798-4105-be23-32df9e991456",
  "message_type": "mms",
  "from": "13137890021",
  "to": "13137890021",
  "mcc": "301",
  "mnc": "204",
  "message_body": {
    "text": "This is an MT message",
    "media": ["https://publicly-available-resource.com"]
  },
  "tag": null,
  "status": "accepted",
  "segments": 1,
  "charge": "0.02",
  "submitted_at": "2022-04-14T13:51:16.096Z",
  "sent_at": null,
  "delivered_at": null,
  "error_message": null
}
```

## Get message details

To get the message details, including delivery status, use the following method:

```http theme={null}
GET https://api.wavix.com/v3/messages/{{message_id}}
Authorization: Bearer your_api_key
```

* `message_id`: the unique identifier of the message on the Wavix platform for which the details are requested.

If successful, the service returns the `HTTP 200 OK` status code. The response body contains the message details.

Response example:

```json theme={null}
{
  "message": {
    "direction": "outbound",
    "message_id": "871b4eeb-f798-4105-be23-32df9e991456",
    "message_type": "mms",
    "from": "13137890021",
    "to": "13137890021",
    "mcc": "301",
    "mnc": "204",
    "message_body": {
      "text": "This is an MT message",
      "media": ["https://publicly-available-resource.com"]
    },
    "tag": "1234",
    "status": "delivered",
    "segments": 1,
    "charge": "0.02",
    "submitted_at": "2022-04-14T13:51:16.096Z",
    "sent_at": "2022-04-14T13:51:16.096Z",
    "delivered_at": "2022-04-14T13:51:16.096Z",
    "error_message": null
  }
}
```

For outbound messages, the `status` field shows the delivery status:

* **accepted**: Message queued for delivery
* **sent**: Message delivered to carrier
* **delivered**: Delivery confirmed by recipient's network
* **failed**: Delivery failed; check `error_message` for details

## Unsubscribe a recipient

If you need to [unsubscribe a recipient](/api-reference/sms-and-mms/create-an-opt-out) from receiving SMS or MMS messages, use the following method:

```http theme={null}
POST https://api.wavix.com/v3/messages/opt_outs
Authorization: Bearer your_api_key
Content-Type: application/json
```

Paste the following JSON in the request body:

```json theme={null}
{
   "sender_id": "1716xxxxxxx",
   "phone_number": "1686xxxxxxx"
}
```

* `sender_id`: Sender ID of which the phone number will be opted out. If not specified, the phone number will be opted out of all SMS messages.
* `phone_number`: the phone number to be opted out

If successful, the service returns the `HTTP 204 No Content` status code.