Messaging

Delivery reports and logs

Every SMS ends with a final status: delivered, undeliverable, expired or rejected. Get it pushed to a webhook as it happens, fetch it, or search your logs.

Receive reports on a webhook

Set webhooks.delivery.url on each message. When the final status is known, Pulsr sends it to that URL. Add intermediateReport: true to also receive pending states.

send.ts

await pulsr("POST", "/sms/3/messages", {  messages: [    {      sender: "YourBrand",      destinations: [{ to: "33639981234", messageId: "order-4821" }],      content: { text: "Your order #4821 has shipped." },      webhooks: {        delivery: { url: "https://yourapp.com/webhooks/pulsr?token=…" },        contentType: "application/json",        // Returned untouched in the report, up to you what goes in it        callbackData: "order=4821",      },    },  ],});

POST to your webhook

{  "results": [    {      "bulkId": "2034072219640523072",      "messageId": "order-4821",      "to": "33639981234",      "sender": "YourBrand",      "sentAt": "2026-10-19T09:30:00.000+0000",      "doneAt": "2026-10-19T09:30:03.000+0000",      "messageCount": 1,      "price": { "pricePerMessage": 0.045, "currency": "EUR" },      "status": {        "groupId": 3,        "groupName": "DELIVERED",        "id": 5,        "name": "DELIVERED_TO_HANDSET",        "description": "Message delivered to handset"      },      "error": {        "groupId": 0,        "groupName": "OK",        "id": 0,        "name": "NO_ERROR",        "description": "No Error",        "permanent": false      },      "callbackData": "order=4821"    }  ]}

Handle the report

Update your records from status.groupName and keep error.name when something went wrong. The Webhooks guide covers securing the endpoint and handling retries.

app/webhooks/pulsr/route.ts

export async function POST(req: Request) {  // Check the token first, see the Webhooks guide  const { results } = await req.json();  for (const report of results) {    await db.message.update({      where: { id: report.messageId },      data: {        status: report.status.groupName, // DELIVERED, UNDELIVERABLE, ...        error: report.error.id === 0 ? null : report.error.name,        deliveredAt: report.doneAt,      },    });  }  return new Response(null, { status: 200 });}

Field	Description
`messageId`	Your ID if you set one on the destination, otherwise ours.
`status`	Final status. See Message statuses.
`error`	Why it failed, with `permanent` telling you whether retrying can help.
`sentAt`, `doneAt`	When the message left Pulsr and when the final status was reached.
`messageCount`	Number of SMS parts billed.
`price`	`pricePerMessage` and `currency`.
`callbackData`	The value you sent, untouched.

Fetch reports

GET/sms/3/reports

No public server yet? Fetch reports instead. Filter by bulkId or messageId, and set limit (50 by default, up to 1,000).

reports.ts

const query = "bulkId=reminders-2026-10-20&limit=100";const { results } = await pulsr("GET", `/sms/3/reports?${query}`);for (const report of results) {  console.log(report.messageId, report.status.name);}

Logs list sent messages with their current status, and can be queried as often as you need. Filter by destination, sender, bulkId, messageId, generalStatus (e.g. DELIVERED, UNDELIVERABLE) and a sentSince / sentUntil range. Use useCursor=true and the returned cursor to page through large results.

logs.ts

const params = new URLSearchParams({  destination: "33639981234",  sentSince: "2026-10-19T00:00:00.000+0000",  generalStatus: "UNDELIVERABLE",  limit: "50",});const { results } = await pulsr("GET", `/sms/3/logs?${params}`);