Message Records and Status

Message records and status

The message records API provides the stored details and current processing status of SMS messages. Records include both messages sent through the SMS API and incoming messages received by your Swift numbers.

Message submission uses https://sms.swift-api.com/v1. Message records are retrieved through the Mercury Public API at https://api.swift-api.com/api/v1.

Note: The API key provided in the Authorization header must have the apik_ prefix.

SMS record schema

Name	Type	Description
id	ULID	Unique identifier assigned to the SMS record. Use the ID returned when an outgoing message is queued to retrieve that message later.
inserted_at	String(format:datetime)	Timestamp when the record was created.
updated_at	String(format:datetime)	Timestamp when the record was last updated.
processed_at	String(format:date-time)	Timestamp when processing completed, if available.
delivered_at	String(format:date-time)	Timestamp when delivery was confirmed, if available.
expired_at	String(format:date-time)	Timestamp when the message expired, if applicable.
scheduled_at	String(format:date-time)	Timestamp when the message was scheduled for processing.
host_number	String(format:e164)	The Swift number associated with the message. This is the sender for outbound messages and the recipient for inbound messages.
remote_number	String(format:e164)	The other party’s number. This is the recipient for outbound messages and the sender for inbound messages.
direction	Enum:String	Message direction. Possible values are INBOUND and OUTBOUND.
status	Enum:String	Current processing or delivery status of the message.
error_code	Enum:String	The associated error code, if the message encountered an error.
display_body	String	Human-readable message body.
multipart_id	ULID	Identifier shared by the parts of a multipart SMS, if applicable.
multipart_method	String	Method used to handle the multipart message, if applicable.
priority	Integer	Processing priority of the message.
encoding	Integer	The encoding used for the message body.
remote_need_delivery_receipt	Boolean	Whether a delivery receipt was requested.
udh_count	Integer	Total number of UDH parts in a multipart SMS.
udh_seq_num	Integer	Sequence number of this UDH part.
udh_ref_num	Integer	Reference number of the multipart SMS.

Fields that do not apply to a message may be null.

List SMS records

Lists the SMS records visible to the authenticated user, including records from immediate and sub-accounts. Results use cursor pagination and are returned newest first.

The list endpoint supports the standard cursor pagination parameters first, after, last, and before.

Request:

GET https://api.swift-api.com/api/v1/smses?first=50 HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json

{
  "data": {
    "items": [
      {
        "associations": {
          "account": {
            "data": {
              "id": "01J0CRVTXX9KBD9NWS02R5R8RT"
            },
            "type": "account"
          },
          "host_did": {
            "data": {
              "id": "01J0CS4Y2N7RZQAS68T6VBP6ZP"
            },
            "type": "did"
          }
        },
        "data": {
          "delivered_at": "2024-06-14T00:00:02.000000Z",
          "direction": "OUTBOUND",
          "display_body": "Hello, World",
          "encoding": 0,
          "error_code": "OK",
          "expired_at": null,
          "host_number": "12003004000",
          "id": "01JDQ02MQ543RTQBT08WY88589",
          "inserted_at": "2024-06-14T00:00:00.000000Z",
          "multipart_id": null,
          "multipart_method": null,
          "priority": 0,
          "processed_at": "2024-06-14T00:00:01.000000Z",
          "remote_need_delivery_receipt": true,
          "remote_number": "12003004001",
          "scheduled_at": "2024-06-14T00:00:00.000000Z",
          "status": "DELIVERED",
          "udh_count": null,
          "udh_ref_num": null,
          "udh_seq_num": null,
          "updated_at": "2024-06-14T00:00:02.000000Z"
        },
        "type": "sms_request"
      }
    ],
    "page_info": {
      "after": "string",
      "before": null,
      "limit": 50,
      "total": 1
    }
  },
  "type": "list"
}

Use the after or before value returned in page_info to request the next page in the corresponding direction.

Get an SMS record

Retrieves one SMS record by its Swift-assigned ID. This endpoint can be used to check the latest status of an outgoing message or retrieve the stored details of an incoming message.

Request:

GET https://api.swift-api.com/api/v1/smses/01JDQ02MQ543RTQBT08WY88589 HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json

{
  "associations": {
    "account": {
      "data": {
        "id": "01J0CRVTXX9KBD9NWS02R5R8RT"
      },
      "type": "account"
    },
    "host_did": {
      "data": {
        "id": "01J0CS4Y2N7RZQAS68T6VBP6ZP"
      },
      "type": "did"
    }
  },
  "data": {
    "delivered_at": "2024-06-14T00:00:02.000000Z",
    "direction": "OUTBOUND",
    "display_body": "Hello, World",
    "encoding": 0,
    "error_code": "OK",
    "expired_at": null,
    "host_number": "12003004000",
    "id": "01JDQ02MQ543RTQBT08WY88589",
    "inserted_at": "2024-06-14T00:00:00.000000Z",
    "multipart_id": null,
    "multipart_method": null,
    "priority": 0,
    "processed_at": "2024-06-14T00:00:01.000000Z",
    "remote_need_delivery_receipt": true,
    "remote_number": "12003004001",
    "scheduled_at": "2024-06-14T00:00:00.000000Z",
    "status": "DELIVERED",
    "udh_count": null,
    "udh_ref_num": null,
    "udh_seq_num": null,
    "updated_at": "2024-06-14T00:00:02.000000Z"
  },
  "type": "sms_request"
}

The record reflects the latest status known to Swift. When a delivery report is requested, status changes are also delivered through the DLR webhook.