# Using Alias To Send SMS

Alias based messaging allows you to send an SMS to a recipient by referencing an **alias** instead of providing a phone number (MSISDN).

For an alias to be deliverable, a contact with the same alias **must already exist** in your address book. If no matching contact is found, the message will not be sent.

### <mark style="color:green;">`POST`</mark> `/send/alias`

#### Required Permission

```
create:AliasSMS
```

Your API key must have this permission enabled to use this endpoint.

### Example Request

```bash
curl --location 'https://<hostname>/send/alias' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "recipients": ["john"],
    "text": "Hello {{name}} sent at {{time}}",
    "originator": "test",
    "excludeDuplicates": true,
    "excludeOptouts": true,
    "shortenUrls": true,
    "name": "Alias Campaign",
    "spreadHours": 0
  }'
```

Replace `YOUR_API_KEY` with your API key.

{% hint style="info" %}
All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request.
{% endhint %}

#### Request Parameters

| Field             | Type                       | Required | Description                                                                                                                                                                                                   |
| ----------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| recipients        | array                      | Yes      | List of aliases to send messages to.                                                                                                                                                                          |
| text              | string                     | Yes      | Message content. Supports template placeholders.                                                                                                                                                              |
| originator        | string                     | Yes      | Sender ID displayed on the recipient’s handset.                                                                                                                                                               |
| name              | string                     | No       | Optional campaign name for reporting.                                                                                                                                                                         |
| shortenUrls       | boolean                    | No       | Automatically shorten URLs in the message text.                                                                                                                                                               |
| excludeDuplicates | boolean                    | No       | Prevent duplicate aliases within the request.                                                                                                                                                                 |
| excludeOptouts    | boolean                    | No       | Exclude contacts who have opted out.                                                                                                                                                                          |
| spreadHours       | number                     | No       | Spread message delivery evenly over the specified number of hours.                                                                                                                                            |
| scheduleDateTime  | string (ISO 8601 datetime) | No       | Schedules the message or campaign to be sent at a future date and time. The value must be provided in ISO 8601 format (e.g. `2025-03-01T14:30:00Z`). If omitted, the message or campaign is sent immediately. |

### Template Placeholders

Alias-based messages support template placeholders in the message text, such as:

```json
Hello {{name}} sent at {{time}}
```

Placeholder values are resolved using the contact data stored in your address book.

#### Success (HTTP 200)

```json
{
  "success": true,
  "record": {
    "id": "8af60d9-de7f-45ce-97f1-35a91b45277",
    "type": "AliasSMS",
    "scheduled": "2025-11-10T21:12:32.786Z",
    "recipientCount": 1
  }
}
```

A successful response confirms that the message has been queued for delivery. Message delivery and delivery receipts are handled asynchronously.