---
title: "Create an SMS"
method: POST
path: "/v1/design_studio/sms"
tags: ["SMS"]
---

# Create an SMS

`POST /v1/design_studio/sms`

## Request

- Base URL: `https://api.customer.io`
- URL: `https://api.customer.io/v1/design_studio/sms`
- Auth: none declared

This endpoint creates an SMS message in Design Studio. After you create an SMS, [link it](/integrations/api/design-studio/tag/sms-link-and-publish/linkSms/) to a workflow. If you make updates after linking the message, make sure you [publish changes](/integrations/api/design-studio/tag/sms-link-and-publish/publishSms/) to send the latest content to your audience.

Not all accounts are set up to create SMS through Design Studio. [Learn more about your options](/integrations/api/design-studio/tag/sms/).

## Request body

- object
  - `name` string, required: A friendly name for the SMS. Your team sees this name in Design Studio, so pick one that helps them find the message.
  - `parent_folder_id` string, uuid, nullable: UUID of the folder to create the SMS in. Omit or pass `null` to create the SMS at the root level. You can [list folders](/integrations/api/design-studio/tag/folders/listFolders/) to find the UUID of the folder you want.
  - `content` string, required: The message, written as SMS markup. Put your message text in an `<x-sms-body>` element inside an `<x-sms>` element; the text can include liquid. To send an image as an MMS, add an `<x-sms-media>` element inside `<x-sms>` with `type="image"` and an `href` set to the image URL or to liquid that resolves to one. Each message can have one image. See [SMS building blocks](/messaging/channels/sms/send-messages/#sms-building-blocks) for line breaks, special characters, and the HTML you can't use.
  - `recipient` string: Liquid that resolves to the phone number of the person you're messaging, like `{{customer.phone}}`. Customer.io evaluates it against that person's profile when it sends the message. If you leave it empty, Customer.io uses `{{customer.phone}}`. Don't set a static phone number here; if you do, every send of this message goes to that one number instead of to each person.
  - `sender_id` integer, nullable: The ID of the sender identity to send the SMS from. You can [list sender identities](/integrations/api/app/tag/sender-identities/listSenders/) to find the ID you want. You can create an SMS without a sender, but you need to set one before you can publish it.

## Response `200`

SMS created

- object
  - `sms` Sms
    - `id` string, uuid, required: The UUID of the SMS.
    - `name` string, required: The friendly name your team sees for the SMS in Design Studio.
    - `is_linked` boolean, required: Whether you've linked the SMS to a workflow, like a transactional message, a one-time send, or an automation action.
    - `parent_folder_id` string, uuid, nullable, required: UUID of the folder that contains the SMS, or `null` if the SMS is at the root level.
    - `content` string, required: The message, written as SMS markup.
    - `recipient` string, required: Liquid that resolves to the phone number of the person you're messaging. An empty string means Customer.io sends to `{{customer.phone}}`.
    - `sender_id` integer, nullable, required: The ID of the sender identity the SMS sends from, or `null` if you haven't set a sender.
    - `created` integer, required: When you created the SMS, as a Unix timestamp in seconds.
    - `updated` integer, required: When the SMS last changed, as a Unix timestamp in seconds.

## Other responses

- `400`: The request is invalid due to malformed parameters, missing required fields, or constraint violations.
- `401`: Authentication failed due to a missing or invalid API key.
- `404`: The requested resource was not found.
- `422`: The `content` isn't valid SMS markup, or the liquid in `content` or `recipient` isn't valid. Markup fails when it doesn't parse, when `<x-sms-body>` is empty, or when text sits inside an unsupported tag like `<b>`. Each error's `source.pointer` names the field that failed, as `/data/attributes/content` or `/data/attributes/recipient`. Customer.io checks liquid syntax only, so a variable your profiles don't have yet renders as empty rather than failing.

## Changes

- **2026-10-08** `6378ded43e43`: 2 info
  - api tag `SMS` added
  - api tag `Design Studio SMS` removed
- **2026-10-06** `b0a0db5fbc21`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/changes/v1/design_studio/sms/post.md)

---

[API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) - [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/revisions/ac0b282053fe?raw)