Create an SMS message

POST

/v1/sms/messages

const msg = await bird.sms.send({
  from: "+15557654321",
  to: "+14155550100",
  text: "Your verification code is 123456.",
  category: "authentication",
});
console.log(msg.id, msg.status);

msg = client.sms.send(
    from_="+15557654321",
    to="+15551234567",
    text="Your verification code is 123456.",
    category="authentication",
)
print(msg.id, msg.status)

msg, err := client.Sms.Send(context.Background(), bird.SmsSendParams{
	From:     "+15557654321",
	To:       "+15551234567",
	Text:     "Your verification code is 123456.",
	Category: bird.SMSCategoryAuthentication,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->sms->send(
    from: '+15557654321',
    to: '+15551234567',
    text: 'Your verification code is 123456.',
    category: 'authentication',
);
echo $message->getId(), ' ', $message->getStatus();

bird sms send --body-file - <<'JSON'
{
  "to": "+14155550100",
  "from": "+15557654321",
  "text": "Your verification code is 123456.",
  "category": "authentication",
  "options": {
    "smart_encoding": true
  },
  "tags": [
    {
      "name": "campaign",
      "value": "signup"
    }
  ],
  "metadata": {
    "user_id": "usr_12345"
  }
}
JSON

curl -X POST "https://us1.platform.bird.com/v1/sms/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "from": "+15557654321",
    "text": "Your verification code is 123456.",
    "category": "authentication",
    "options": {
      "smart_encoding": true
    },
    "tags": [
      {
        "name": "campaign",
        "value": "signup"
      }
    ],
    "metadata": {
      "user_id": "usr_12345"
    }
  }'

Response202

{
  "id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "outbound",
  "status": "scheduled",
  "to": "+15551234567",
  "from": "+15557654321",
  "text": "Your order has shipped and is on its way.",
  "category": "transactional",
  "segments": {
    "encoding": "GSM_7BIT"
  },
  "cost": {
    "amount": "0.00990",
    "currency_code": "USD",
    "transaction_amount": "0.00790",
    "passthrough_amount": "0.00200"
  },
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ],
  "options": {
    "smart_encoding": true
  },
  "carrier": "Verizon",
  "mcc_mnc": "311480",
  "last_error": {
    "code": "invalid_destination",
    "description": "Carrier filtered as spam"
  }
}

Sends one SMS to one recipient with exactly one content form: text, which requires category and from, or a stored template, which selects both for you. To submit up to 100 independent messages in one request, use Send a batch of SMS messages instead.

The 202 Accepted response means the API durably accepted the message for asynchronous delivery. Delivery remains pending; follow it with Get an SMS message or by subscribing to sms.* webhook events.

An invalid field, more than 12 segments, a disabled destination country, or a sender not permitted for the destination returns 422. Insufficient wallet balance returns 402.

Request Payload

string

आवश्यक

Recipient phone number in E.164 format (for example +14155550100). One recipient per message. The number is stored and returned in canonical E.164; a recipient that cannot be routed returns a 422 SMSInvalidRecipient.

from

string

Sender to send from. It must be a sender the workspace holds: a number it owns in E.164, such as +15557654321, a short code it holds, such as 24680, or an alphanumeric sender ID it has claimed, such as MyBrand. A sender the workspace does not hold returns a 422 SMSSenderNotConfigured, and an alphanumeric sender must also be permitted, and where required registered, for the destination country. Required on a free-text send: omitting it returns a 422 SMSNoEligibleSender. Not accepted alongside template, which selects its sender automatically.

text

string

आवश्यक

Free-text message body. Required unless template is supplied (the two are mutually exclusive). At least 1 character, up to a 12-segment cap (roughly 1836 GSM-7 or 804 UCS-2 characters). Bird does not truncate; a body exceeding 12 segments is rejected with a 422. The cap applies to segments because GSM-7 and UCS-2 encodings differ in characters per segment.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideSending your first SMS Understand the conceptWhat does SMS mean?Explore the capabilitySMS Follow the learning pathBuild your first integration

Try the practice and get an implementation brief

const msg = await bird.sms.send({
  from: "+15557654321",
  to: "+14155550100",
  text: "Your verification code is 123456.",
  category: "authentication",
});
console.log(msg.id, msg.status);

msg = client.sms.send(
    from_="+15557654321",
    to="+15551234567",
    text="Your verification code is 123456.",
    category="authentication",
)
print(msg.id, msg.status)

msg, err := client.Sms.Send(context.Background(), bird.SmsSendParams{
	From:     "+15557654321",
	To:       "+15551234567",
	Text:     "Your verification code is 123456.",
	Category: bird.SMSCategoryAuthentication,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->sms->send(
    from: '+15557654321',
    to: '+15551234567',
    text: 'Your verification code is 123456.',
    category: 'authentication',
);
echo $message->getId(), ' ', $message->getStatus();

bird sms send --body-file - <<'JSON'
{
  "to": "+14155550100",
  "from": "+15557654321",
  "text": "Your verification code is 123456.",
  "category": "authentication",
  "options": {
    "smart_encoding": true
  },
  "tags": [
    {
      "name": "campaign",
      "value": "signup"
    }
  ],
  "metadata": {
    "user_id": "usr_12345"
  }
}
JSON

curl -X POST "https://us1.platform.bird.com/v1/sms/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "from": "+15557654321",
    "text": "Your verification code is 123456.",
    "category": "authentication",
    "options": {
      "smart_encoding": true
    },
    "tags": [
      {
        "name": "campaign",
        "value": "signup"
      }
    ],
    "metadata": {
      "user_id": "usr_12345"
    }
  }'

Response202

{
  "id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "outbound",
  "status": "scheduled",
  "to": "+15551234567",
  "from": "+15557654321",
  "text": "Your order has shipped and is on its way.",
  "category": "transactional",
  "segments": {
    "encoding": "GSM_7BIT"
  },
  "cost": {
    "amount": "0.00990",
    "currency_code": "USD",
    "transaction_amount": "0.00790",
    "passthrough_amount": "0.00200"
  },
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ],
  "options": {
    "smart_encoding": true
  },
  "carrier": "Verizon",
  "mcc_mnc": "311480",
  "last_error": {
    "code": "invalid_destination",
    "description": "Carrier filtered as spam"
  }
}