# Send your first SMS with the API

In this tutorial, you send a single SMS with the Outbound SMS API by using
cURL. You collect the credentials of an HTTP OUT trunk, submit a message, and
check the result in the API response, the status callback, and the Outbound
SMS logs.

## Before you begin

- An [HTTP OUT trunk](../sms-trunks/http-out/http-out-trunk.html). If you
  do not have one, [create an HTTP OUT trunk](../sms-trunks/http-out/how-to-guides/create-http-out-trunk.html).
- A sender for the message:

  - For P2P messaging, a DID number that supports **Outbound P2P SMS** and
    is allowed in the trunk's [Source Address Settings](../sms-trunks/http-out/http-out-trunk-settings-reference.html#user-panel-sms-http-out-trunk-source-address-settings).
  - For A2P messaging, an active [Sender ID Verification](../sender-id-verifications/index.html) associated with the trunk.
- If the trunk has **Allowed IP addresses**, a computer that sends requests
  from one of these addresses.
- A **Callback URL** on the trunk, if you want to receive the status
  callback in step 4.
- [cURL](https://curl.se/) installed on your computer.

## Step 1: Get your trunk credentials

1. In the DIDWW User Panel, go to **SMS > SMS Trunks**.
2. Locate your HTTP OUT trunk and click the key icon in the **Credentials**
   column.
3. Copy the **Username** and **Password**.
4. Choose an endpoint. Use the global endpoint `https://sms-out.didww.com`,
   or a regional endpoint for lower latency, such as the ones listed in
   **Host(s)**. For all endpoints, see [Endpoints](outbound-sms-api-reference.html#sms-out-spec-endpoints-headers).

For details, see [View HTTP OUT trunk
credentials](../sms-trunks/http-out/how-to-guides/view-http-out-trunk-credentials.html).

[![HTTP OUT trunk credentials window showing the Username, a hidden Password, Host(s), Allowed IPs, and Allowed Source Addresses](../../_images/fig_credentials2.webp)](../../_images/fig_credentials2.webp)


**Fig. 1.** Get the trunk credentials

## Step 2: Prepare your request

A single-message request has the following parts:

- **Method and URL:** `POST` to the endpoint from step 1. The path for a
  single message is `/outbound_messages`.
- **Headers:** `Content-Type: application/vnd.api+json` and an
  `Authorization` header with your credentials. The cURL `-u` option
  creates the `Authorization` header for you.
- **Body:** a JSON:API document with the `outbound_messages` type and the
  message attributes.

Choose the body that matches your messaging type:

*P2P (DID number as sender)*

Set `source` to a DID number that the trunk allows as a sender.

```
 1{
 2  "data": {
 3    "type": "outbound_messages",
 4    "attributes": {
 5      "destination": "15551234567",
 6      "source": "12125551234",
 7      "content": "Hello World!"
 8    }
 9  }
10}
```


*A2P (Sender ID Verification)*

Set `campaign_id` to the **Campaign ID** of your active Sender ID
Verification and omit `source`. DIDWW randomly selects one of the
Sender IDs registered under that verification. To use a specific
Sender ID, set it in `source` instead.

```
 1{
 2  "data": {
 3    "type": "outbound_messages",
 4    "attributes": {
 5      "destination": "15551234567",
 6      "content": "Hello World!",
 7      "campaign_id": "1111aaaa-1a1a-41a1-aaaa-11aaaaa11111"
 8    }
 9  }
10}
```

Replace the example values with your own:

- `destination`: the recipient's number in E.164 format, digits only,
  without the leading `+`.
- `source`: your sender, in E.164 format for DID numbers.
- `campaign_id`: the Campaign ID shown on the verification details page.

For all attributes, see [Request attributes](outbound-sms-api-reference.html#outbound-attributes).

## Step 3: Send the SMS

Run the following command. Replace `USERNAME`, `PASSWORD`, and the
endpoint with the values from step 1, and the body with the one you prepared
in step 2.

```
 1curl -u USERNAME:PASSWORD \
 2  -X POST \
 3  -H "Content-Type: application/vnd.api+json" \
 4  https://sms-out.didww.com/outbound_messages \
 5  -d '{
 6    "data": {
 7      "type": "outbound_messages",
 8      "attributes": {
 9        "destination": "15551234567",
10        "source": "12125551234",
11        "content": "Hello World!"
12      }
13    }
14  }'
```

## Step 4: Inspect the result

1. Check the API response. A `201 Created` response contains the ID of the
   message:

   ```
   1{
   2  "data": {
   3    "type": "outbound_messages",
   4    "id": "550e8400-e29b-41d4-a716-446655440000"
   5  }
   6}
   ```

   Save the `id`. The response confirms that DIDWW accepted the message
   for processing. It does not confirm delivery to the recipient.
2. Check the status callback. After processing the message, DIDWW sends an
   `outbound_message_callbacks` request to the trunk's **Callback URL**
   with the same `id`. The `status` attribute shows the processing
   result, and `code_id` explains a failure. See [Status callbacks
   and delivery receipts](status-callbacks-and-delivery-receipts.html).
3. In the DIDWW User Panel, go to **Logs & Analytics > SMS Logs** and choose
   **Outbound** to find the message. See [Outbound SMS
logs](../../logs-analytics/sms-logs/outbound-logs.html#outbound-logs).

If the request fails, the API returns an error instead of `201 Created`:

- `400 Bad Request`: check that the body follows the JSON:API format shown
  in step 2 and that every required attribute has a valid value.
- `401 Unauthorized`: check the credentials and the trunk's **Allowed IP
  addresses**.
- `415 Unsupported Media Type`: check that the `Content-Type` header is
  `application/vnd.api+json`.
- `429 Too Many Requests`: reduce the request rate.

For all errors, see [Outbound SMS errors and status codes](outbound-sms-errors-and-status-codes.html).

## Next steps

- [Send bulk SMS with the API](send-bulk-sms-with-api.html) - Send the same message to many destination
  numbers in one request.
- [Status callbacks and delivery receipts](status-callbacks-and-delivery-receipts.html) - Process status callbacks
  and delivery receipts in your application.
- [Outbound SMS API reference](outbound-sms-api-reference.html) - Review endpoints, attributes, and
  limits.