#Send an SMS

A single POST /messages sends an SMS from one of your numbers to any recipient. The call returns a message object you can store and reconcile against later delivery events. Every message you send also lands in the softphone inbox so your team sees the same conversation in real time.

The messaging API is write- and event-oriented: you send with POST /messages, then react to inbound texts and delivery updates over Webhooks. To look up a single message after the fact, use GET /messages/{id}.

#Send a message

Provide a from (an E.164 number you own), a to recipient, and a body. The API responds 201 with the created message in queued status.

curl https://api.netexem.com/v1/messages \
-H "Authorization: Bearer $NETEXEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "from": "+15551234567",
  "to": "+15557654321",
  "body": "Your appointment is confirmed for 2pm — reply STOP to opt out.",
  "senderName": "Appointment Reminder Bot"
}'

Numbers use E.164 format — a leading + and country code, e.g. +15551234567. Opt-out is handled automatically: recipients who have texted STOP are suppressed before delivery. See Opt-out.

#Request fields

Field	Type	Required	Description
`from`	`string`	yes	An E.164 number you own.
`to`	`string`	yes	Recipient in E.164 format.
`body`	`string`	yes	Message text.
`senderName`	`string`	no	Name identifying the message source in the softphone inbox — a team member's name or an automation/script name. See Sender identification.
`mediaUrls`	`string[]`	no	Media URLs to attach — sends as MMS.

#The message object

A successful send returns the created message. The same shape is returned by GET /messages/{id}.

{
  "id": "msg_01h…",
  "from": "+15551234567",
  "to": "+15557654321",
  "body": "Your appointment is confirmed for 2pm — reply STOP to opt out.",
  "direction": "outbound",
  "status": "queued",
  "createdAt": "2026-05-31T14:02:09Z"
}

Field	Type	Description
`id`	`string`	Unique message identifier, e.g. `msg_01h…`. Use it to look the message up later.
`from`	`string`	The sending E.164 number.
`to`	`string`	The recipient E.164 number.
`body`	`string`	The message text.
`direction`	`string`	`outbound` for messages you send, `inbound` for messages you receive.
`status`	`string`	Lifecycle state — one of `queued`, `sent`, `delivered`, `failed`.
`createdAt`	`string`	ISO 8601 timestamp of when the message was created.

#MMS

To send an MMS, include a mediaUrls array alongside body. Each entry is a publicly reachable URL to the media you want to attach; body is optional when media is present.

curl https://api.netexem.com/v1/messages \
-H "Authorization: Bearer $NETEXEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "from": "+15551234567",
  "to": "+15557654321",
  "body": "Here is your receipt.",
  "mediaUrls": ["https://files.example.com/receipts/inv-1042.pdf"]
}'

#Sender identification

The optional senderName field identifies who or what sent the message, displayed in the softphone inbox. It supports two primary use cases:

#For manual sends — team member names

When a team member sends a message, populate senderName with their name:

{
  "from": "+15551234567",
  "to": "+15557654321",
  "body": "Hi! Just checking in on your order.",
  "senderName": "Sarah Chen"
}

The message appears in the softphone inbox labeled with Sarah's name, so your team can trace it back to a specific person.

#For automated sends — script and workflow names

When an automation, script, or workflow sends a message, use a descriptive name that identifies the automation:

{
  "from": "+15551234567",
  "to": "+15557654321",
  "body": "Your appointment reminder: Tomorrow at 2:00 PM",
  "senderName": "Appointment Reminder Bot"
}

Other examples of automation names:

"Lead Follow-Up Sequence" — for CRM drip campaigns
"Post-Sale Survey" — for automated customer feedback
"Re-Engagement Campaign" — for win-back workflows
"Notification System" — for alert automations

#Why this matters

When multiple automations are running in parallel (appointment reminders, follow-up sequences, drip campaigns), the senderName becomes the primary way your team identifies which workflow or script triggered each message. Without clear sender identification, it's difficult to:

Audit which automation sent a given message to a customer
Troubleshoot unexpected messaging behavior
Report on engagement by automation or workflow

If senderName is omitted, the message is attributed to the from number alone.

#Delivery status

The status on the returned object is its state at the moment of the request — almost always queued. Delivery is asynchronous, so the status advances after the response: queued → sent → delivered, or failed if the carrier rejects it.

Track those transitions with delivery-receipt webhooks. Subscribe an endpoint and you'll receive a signed event each time a message advances, so you can reconcile state without polling. Every event is HMAC-SHA256 signed in the X-Netexem-Signature header — verify it before trusting the payload. See Webhooks for the event shape and signature verification.

Every message you send also appears in the softphone inbox in real time — your team sees the same conversation thread your code does, with no extra setup.

If you need to read a single message's current state directly, fetch it:

curl https://api.netexem.com/v1/messages/msg_01h… \
  -H "Authorization: Bearer $NETEXEM_API_KEY"

#Compliance

Opt-out is automatic. Recipients who reply STOP are suppressed for the relevant number, and further sends to them are blocked before they reach the carrier. Honor and surface these states rather than working around them. See Opt-out.
Use E.164 everywhere. Both from and to must be E.164; malformed numbers return 422.
Send from numbers you own. from must be a provisioned number on your account.

#Next steps

Webhooks — delivery receipts and inbound message.received events
Opt-out — how STOP/START is handled for you
API reference — try POST /messages live