Get started

Quickstart

Send your first SMS with Pulsr in TypeScript or Python. You need an account, an API key and a phone you can read messages on.

1. Get your credentials

In the Pulsr dashboard, open API keys and create a key. The same page shows your base URL, the address every request goes to. Store both as environment variables:

Terminal

export PULSR_API_URL="https://<your-base-url>"export PULSR_API_KEY="<your-api-key>"

2. Add the client helper

The API is plain HTTPS and JSON, so a small helper is all you need. It adds the Authorization header, encodes the body and turns error responses into exceptions. The rest of the docs use it.

Terminal

# TypeScript: nothing to install, fetch is built into Node.js 18+# Pythonpip install requests

client.ts

const BASE_URL = process.env.PULSR_API_URL!;const API_KEY = process.env.PULSR_API_KEY!;export class PulsrError extends Error {  constructor(public status: number, public body: any) {    // SMS and RCS errors carry a description, voice and verify a requestError    const legacy = body?.requestError?.serviceException?.text;    super(body?.description ?? legacy ?? `HTTP ${status}`);  }}export async function pulsr<T = any>(  method: string,  path: string,  body?: unknown,): Promise<T> {  const res = await fetch(`${BASE_URL}${path}`, {    method,    headers: {      "Authorization": `App ${API_KEY}`,      "Content-Type": "application/json",      "Accept": "application/json",    },    body: body === undefined ? undefined : JSON.stringify(body),  });  const data = await res.json().catch(() => null);  if (!res.ok) throw new PulsrError(res.status, data);  return data as T;}

3. Send a message

Replace the destination with your own mobile number, in international format without the +.

send.ts

import { pulsr } from "./client";const res = await pulsr("POST", "/sms/3/messages", {  messages: [    {      sender: "Pulsr",      destinations: [{ to: "33639981234" }],      content: { text: "Hello from Pulsr! It works." },    },  ],});const { messageId, status } = res.messages[0];console.log(messageId, status.name); // ... PENDING_ACCEPTED

The API answers as soon as the message is accepted. Keep the messageId: it is how you will match the delivery report.

Response · 200 OK

{  "bulkId": "2034072219640523072",  "messages": [    {      "messageId": "2250be2d4219-3af1-78856-aabe-1362af1edfd2",      "status": {        "groupId": 1,        "groupName": "PENDING",        "id": 26,        "name": "PENDING_ACCEPTED",        "description": "Message sent to next instance"      },      "destination": "33639981234",      "details": { "messageCount": 1 }    }  ]}

4. Check that it arrived

Your phone should buzz within seconds. To follow delivery from your code, fetch the delivery report for the message. In production, have reports pushed to a webhook instead of polling.

report.ts

const { results } = await pulsr("GET", `/sms/3/reports?messageId=${messageId}`);if (results.length === 0) {  console.log("No report yet, try again in a few seconds");} else {  console.log(results[0].status.groupName); // DELIVERED}

A status.groupName of DELIVERED means the handset received the message. Anything else is explained in Errors and statuses.

Next steps

1. Get your credentials

In the Pulsr dashboard, open API keys and create a key. The same page shows your base URL, the address every request goes to. Store both as environment variables:

Terminal

export PULSR_API_URL="https://<your-base-url>"export PULSR_API_KEY="<your-api-key>"

2. Add the client helper

The API is plain HTTPS and JSON, so a small helper is all you need. It adds the Authorization header, encodes the body and turns error responses into exceptions. The rest of the docs use it.

Terminal

# TypeScript: nothing to install, fetch is built into Node.js 18+# Pythonpip install requests

client.ts

const BASE_URL = process.env.PULSR_API_URL!;const API_KEY = process.env.PULSR_API_KEY!;export class PulsrError extends Error {  constructor(public status: number, public body: any) {    // SMS and RCS errors carry a description, voice and verify a requestError    const legacy = body?.requestError?.serviceException?.text;    super(body?.description ?? legacy ?? `HTTP ${status}`);  }}export async function pulsr<T = any>(  method: string,  path: string,  body?: unknown,): Promise<T> {  const res = await fetch(`${BASE_URL}${path}`, {    method,    headers: {      "Authorization": `App ${API_KEY}`,      "Content-Type": "application/json",      "Accept": "application/json",    },    body: body === undefined ? undefined : JSON.stringify(body),  });  const data = await res.json().catch(() => null);  if (!res.ok) throw new PulsrError(res.status, data);  return data as T;}

3. Send a message

Replace the destination with your own mobile number, in international format without the +.

send.ts

import { pulsr } from "./client";const res = await pulsr("POST", "/sms/3/messages", {  messages: [    {      sender: "Pulsr",      destinations: [{ to: "33639981234" }],      content: { text: "Hello from Pulsr! It works." },    },  ],});const { messageId, status } = res.messages[0];console.log(messageId, status.name); // ... PENDING_ACCEPTED

The API answers as soon as the message is accepted. Keep the messageId: it is how you will match the delivery report.

Response · 200 OK

{  "bulkId": "2034072219640523072",  "messages": [    {      "messageId": "2250be2d4219-3af1-78856-aabe-1362af1edfd2",      "status": {        "groupId": 1,        "groupName": "PENDING",        "id": 26,        "name": "PENDING_ACCEPTED",        "description": "Message sent to next instance"      },      "destination": "33639981234",      "details": { "messageCount": 1 }    }  ]}

4. Check that it arrived

Your phone should buzz within seconds. To follow delivery from your code, fetch the delivery report for the message. In production, have reports pushed to a webhook instead of polling.

report.ts

const { results } = await pulsr("GET", `/sms/3/reports?messageId=${messageId}`);if (results.length === 0) {  console.log("No report yet, try again in a few seconds");} else {  console.log(results[0].status.groupName); // DELIVERED}

A status.groupName of DELIVERED means the handset received the message. Anything else is explained in Errors and statuses.