SMS

Message Logs

Retrieve a paginated list of SMS message records for your account. Filter by delivery status, operator, campaign, individual message, or a date range to narrow results.

GET

/v1/sms/logs

Authorization

Header

X-Emisri-Api-Key: your_secret_key

Required

Yes

Query parameters

Field	Type	Required	Description
page	number	no	Page number to retrieve. Defaults to 1.
size	number	no	Number of records per page. Defaults to 100.
status	string	no	Filter by delivery status. See Status Values table below for accepted values.
operator	string	no	Filter by mobile network operator. See Operator Values table below.
campaignId	string	no	Filter logs belonging to a specific campaign. Use the campaignId returned from a send request.
messageId	string	no	Retrieve the log for a single message by its unique ID.
dateFrom	string	no	Start of the date range filter in ISO 8601 format (e.g. 2026-05-01T00:00:00Z).
dateTo	string	no	End of the date range filter in ISO 8601 format (e.g. 2026-05-31T23:59:59Z).

Response · 200 OK

application/json

Field	Type	Required	Description
success	boolean	—	true when the request completed successfully.
data	object	—	The response payload.
meta	object	—	Request metadata.

Message object

Field	Type	Required	Description
messageId	string	—	Unique ID assigned to the individual message.
campaignId	string	—	ID of the campaign this message belongs to.
campaignName	string	—	Label used when the campaign was submitted.
recipient	string	—	Destination phone number in international format.
senderId	string	—	The Sender ID used to dispatch the message.
messageType	string	—	Message classification — MARKETING or TRANSACTIONAL.
status	string	—	Current delivery status. See Status Values table below.
dlrStatus	string	—	Raw delivery report status received from the operator.
sentAt	string	—	ISO 8601 timestamp of when the message was dispatched.
completedAt	string	—	ISO 8601 timestamp of when the final status was recorded.
errorCode	string	—	Operator error code. 0000 indicates successful delivery. NO_REPORT means no DLR was received.
errorReason	string	—	Human-readable description of the error code.
pageCount	number	—	Number of SMS parts this message was split into.
charCount	number	—	Total character count of the message body.
cost	number	—	Amount charged for this message in the billing currency.
currency	string	—	Currency of the cost field (e.g. NGN).
urlClicked	boolean	—	Whether the shortened URL in the message was clicked. Only present when URL shortening with click tracking was enabled.
urlClickedAt	string \| null	—	ISO 8601 timestamp of the first URL click, or null if not clicked.

Status values

Use any of these values with the status query parameter to filter logs.

Value	Description
DELIVERED	Message successfully delivered to the handset.
PENDING	Awaiting delivery confirmation from the operator.
SENT	Accepted by the operator; DLR not yet received.
ENROUTE	In transit within the operator network.
QUEUED	Queued on the Emisri platform for dispatch.
UNDELIVERABLE	Operator confirmed the message could not be delivered.
FAILED	Delivery failed due to a platform or network error.
EXPIRED	Message expired before delivery could be confirmed.
REJECTED	Rejected by the operator or platform before dispatch.
DND	Recipient is on the Do Not Disturb registry.
BLOCKED	Blocked by a platform-level rule or content filter.
HOLDOUT	Held from delivery as part of a holdout group.
UNKNOWN	Status could not be determined.

Operator values

Use any of these values with the operator query parameter to filter logs by network.

Value	Operator
MTN	MTN Nigeria
GLOBACOM	Globacom Nigeria
AIRTEL	Airtel Nigeria
T2_9MOBILE	9mobile (formerly Etisalat) Nigeria
OTHERS	Any other or unrecognised operator.

Request Samples

Request · basic

const response = await fetch(
  'https://BASE_URL/v1/sms/logs?page=1&size=100',
  {
    headers: {
      'X-Emisri-Api-Key': 'your_secret_key',
    },
  }
)
const data = await response.json()

Response Samples

Response · 200 OK

{
  "success": true,
  "data": {
    "messages": [
      {
        "messageId": "004527b9-2d47-4feb-92ff-ef5fae30af11",
        "campaignId": "5f10dcb7-2f0b-430a-b55d-cd6e00b90b1b",
        "campaignName": "api-send-2026-05-23T08:41:59.240Z",
        "recipient": "234812345689",
        "senderId": "EMISNOTIFY",
        "messageType": "MARKETING",
        "status": "DELIVERED",
        "dlrStatus": "DELIVERED",
        "sentAt": "2026-05-23T08:42:00.085Z",
        "completedAt": "2026-05-23T08:42:02.754Z",
        "errorCode": "0000",
        "errorReason": "Message delivered successfully",
        "pageCount": 1,
        "charCount": 45,
        "cost": 5.2,
        "currency": "NGN",
        "urlClicked": true,
        "urlClickedAt": "2026-05-23T08:45:05.889Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 100,
      "total": 18,
      "totalPages": 1
    }
  },
  "meta": {
    "requestId": "req_GQfXPfNYP683wdE8"
  }
}