/deliveryLogs

Overview

Fetch communication delivery logs (SMS, email, push, etc.) across all members of the business. Results are scoped to the authenticated business (x-api-key) and default to the last 90 days when no date filter is supplied.

When to Use This Endpoint

Use this endpoint to:

• Monitor delivery status of communications (SMS, email, push notifications)
• Audit member engagement metrics (clicks, opens, bounces)
• Troubleshoot failed deliveries or identify delivery issues
• Generate delivery reports for compliance and analytics

Key Considerations

• Results are always sorted by createdAt descending (newest first)
• When neither fromDate nor toDate is provided, the endpoint automatically uses a 90-day window ending at the current time
• The database stores status values capitalized but the API returns them in lowercase for consistency
• Use limit and offset together for cursor-free pagination
• Results are scoped to the authenticated business; only logs for members of the calling business are returned

Request Details

Method & URL

POST /deliveryLogs

See API Servers for the base URL to use in place of {{server}}.

Headers

Header	Type	Required	Description
x-api-key	string	Yes	Business API key used to identify and authorize the caller
x-source-type	string	Yes	Type of the calling system (e.g., pos, kiosk)
x-source-name	string	Yes	Name of the calling application
x-pos-id	string	Yes	Unique identifier of the POS terminal
x-branch-id	string	Yes	Identifier of the branch making the request

Request Body

Field	Type	Required	Default	Description
type	string	No	—	Filter by message type (e.g., sms, email, push)
status	string	No	—	Filter by delivery status: sent, failed, bounce complaint, delivered, open, or clicked
fromDate	ISO 8601 date	No	90 days ago	Start of the date range (createdAt >= fromDate)
toDate	ISO 8601 date	No	now	End of the date range (createdAt <= toDate)
limit	integer (1–100)	No	40	Maximum number of records to return
offset	integer (≥ 0)	No	0	Number of records to skip (for pagination)

Request Example

curl --location --request POST 'https://{{server}}/v1/deliveryLogs' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{api-key}}' \
--header 'x-source-type: POS' \
--header 'x-source-name: pos-terminal-01' \
--header 'x-pos-id: POS001' \
--header 'x-branch-id: BR001' \
--data-raw '{
  "type": "sms",
  "status": "delivered",
  "fromDate": "2026-04-01T00:00:00.000Z",
  "toDate": "2026-04-30T23:59:59.999Z",
  "limit": 20,
  "offset": 0
}'

Success Response

200 OK

{
  "status": "success",
  "deliveryLogs": [
    {
      "messageId": "msgabc123",
      "type": "sms",
      "status": "delivered",
      "destination": "905551234567",
      "membershipKey": "0fe31b8b-5ad5-48af-81e9-4adc7d596042",
      "templateId": "tmplxyz",
      "campaignId": "camp456",
      "provider": "verimor",
      "source": "SENDERNAME",
      "createdAt": "2026-04-15T10:23:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
messageId	string	Unique identifier of the message
type	string	Communication channel (sms, email, push, etc.)
status	string	Delivery status in lowercase: sent, failed, bounce complaint, delivered, open, or clicked
destination	string | null	Recipient address (phone number or email)
membershipKey	string	Loyalty membership key of the recipient
templateId	string | null	Identifier of the message template used
campaignId	string | null	Identifier of the campaign that triggered the message
provider	string	Delivery provider (e.g., verimor, ses, notification)
source	string | null	Source identifier (e.g., SMS sender name or email "from" field)
createdAt	ISO 8601 date	Timestamp when the log entry was created

Error Response Examples

Invalid API Key

{
  "statusCode": 400,
  "status": "error",
  "errors": [
    {
      "code": "101",
      "message": "x-api-key header is required"
    }
  ]
}

Invalid Status Value

{
  "statusCode": 400,
  "status": "error",
  "errors": [
    {
      "code": "1005",
      "message": "Invalid status value"
    }
  ]
}

Invalid Date Format

{
  "statusCode": 400,
  "status": "error",
  "errors": [
    {
      "code": "1002",
      "message": "Invalid fromDate format (must be ISO 8601)"
    }
  ]
}

Internal Server Error

{
  "statusCode": 500,
  "status": "error",
  "errors": [
    {
      "code": "1030",
      "message": "Internal server error while fetching delivery logs"
    }
  ]
}

Error Codes

HTTP Status	Code	Description
400	101	Missing or invalid x-api-key header
400	102	Missing x-source-type header
400	103	Missing x-source-name header
400	104	Missing x-pos-id header
400	105	Missing x-branch-id header
400	1004	Invalid type value
400	1005	Invalid status value
400	1002	Invalid fromDate format (must be ISO 8601)
400	1003	Invalid toDate format (must be ISO 8601)
500	1030	Internal server error while fetching delivery logs

Field Reference

Field	Type	Description
type	string	Communication channel type (e.g., sms, email, push)
status	string	Delivery status (sent, failed, bounce complaint, delivered, open, or clicked)
fromDate	ISO 8601 date	Start date for filtering log entries
toDate	ISO 8601 date	End date for filtering log entries
limit	integer	Maximum records to return (1–100)
offset	integer	Number of records to skip for pagination

Related Use Cases

• Monitoring compliance with communication delivery SLAs
• Investigating member engagement patterns (open rates, click rates)
• Debugging delivery failures for troubleshooting
• Building delivery analytics dashboards
• Auditing communication history for regulatory compliance