Tracking message status

Every message moves through a small, predictable state machine. You can poll for status, list recent messages, or subscribe to webhooks for push-based updates.

Lifecycle

Status	Meaning
`pending`	Accepted by LynSMS and queued for the provider.
`sent`	Accepted by the upstream provider. Emits `message.sent`.
`delivered`	The carrier returned a successful delivery receipt. Emits `message.delivered`.
`failed`	The provider rejected the send, or delivery failed permanently. Emits `message.failed`.
`undelivered`	The carrier could not deliver (handset off, blacklisted, expired, etc.).

Retrieve one message

GET/v1/messages/{id}

curl https://lynsms.com/api/v1/messages/msg_VyB2pNkX0wnA9aTrLqDh1Z3Fc \
  -H "Authorization: Bearer ds_live_..."

const res = await fetch(
  `https://lynsms.com/api/v1/messages/${messageId}`,
  { headers: { Authorization: `Bearer ${process.env.LYNSMS_API_KEY}` } }
);
const { data: message } = await res.json();
console.log(message.status, message.delivered_at);

import os, requests

resp = requests.get(
    f"https://lynsms.com/api/v1/messages/{message_id}",
    headers={"Authorization": f"Bearer {os.environ['LYNSMS_API_KEY']}"},
)
message = resp.json()["data"]
print(message["status"], message["delivered_at"])

List recent messages

GET/v1/messages

curl "https://lynsms.com/api/v1/messages?status=delivered&limit=20" \
  -H "Authorization: Bearer ds_live_..."

Query parameters

Param	Description
`status`	Filter by `pending`, `sent`, `delivered`, `failed`, `undelivered`.
`to`	Substring match against the recipient number.
`created_after`	ISO 8601 timestamp.
`created_before`	ISO 8601 timestamp.
`page`	Page number, defaults to `1`.
`limit`	Results per page (max 100, defaults to 50).

Push, don't poll. For production traffic, subscribe to webhooks instead of polling. You'll save rate-limit budget and react to delivery events in milliseconds rather than seconds.

Error information

Failed messages include an error object with the upstream error code and a short, human-readable description. Use this in your retry logic and customer support flows.

{
  "id": "msg_VyB2pNkX0wnA9aTrLqDh1Z3Fc",
  "status": "failed",
  "provider": "twilio",
  "attempts": 2,
  "error": {
    "code": "21610",
    "message": "Attempt to send to unsubscribed recipient"
  }
}