# PulseSMS — Full Context for LLMs

> PulseSMS is a free SMS gateway platform that turns any Android device into a personal SMS gateway. Send campaigns from your own phone number using your carrier plan — no per-message gateway fees, no shared short codes, no Twilio required.

This file contains inline content for LLM context windows. See [llms.txt](https://pulse-sms.com/llms.txt) for the curated link index.

---

## What Is PulseSMS?

PulseSMS is a multi-tenant SaaS platform that lets individuals and businesses send SMS campaigns from their own phone numbers. Unlike traditional SMS APIs (Twilio, Vonage, etc.), PulseSMS does not provision phone numbers or operate carrier infrastructure. Instead, it routes messages through an Android app installed on a device the user owns. The device uses the SIM card's carrier plan, so messages appear to recipients as coming from a real mobile number.

The platform is organized around **Organizations** (workspaces). Each user can belong to multiple organizations. All resources — campaigns, contacts, devices, API keys, webhooks — are scoped to the active organization.

**Who uses PulseSMS:**
- Small businesses sending appointment reminders or promotions from their business number.
- Developers who need a low-cost programmatic SMS channel without per-message API fees.
- Marketers running outreach campaigns who want replies to come to their actual phone.

---

## How It Works

1. A user signs up at pulse-sms.com and gets a free account with a default Organization and API key.
2. They download the PulseSMS Gateway Android app from pulse-sms.com/download.
3. In the dashboard, they go to Devices → Connect device, which generates a QR code.
4. In the Android app, they scan the QR code. The app registers itself as a gateway for that organization.
5. The app detects the phone's SIM card(s) and phone number(s). On multi-SIM devices, users pick which SIM to use.
6. From the dashboard (or API), users create campaigns, select contacts, and send. Messages are routed to the connected device, which dispatches them via the Android SMS API.
7. Delivery status updates flow back to the dashboard via the gateway app's heartbeat. Webhook events are dispatched to any configured endpoint URLs.

---

## Features

### Send From Your Own Number
Messages are sent from the phone number on the gateway device's SIM card. Recipients see a real mobile number, not a short code or shared sender ID. This increases open rates and enables two-way conversations directly on the phone.

### Batch Campaigns
Create campaigns targeting hundreds or thousands of recipients. The gateway device processes the queue in the background. Campaigns support scheduling (send now or at a future time) and personalization variables (`{{name}}`, etc. substituted per-contact at send time).

### Real-Time Analytics
The campaign detail view shows live delivery statistics: queued, sent, delivered, and failed counts. Status updates as the device processes messages. Overall campaign status transitions from In Progress to Completed when all messages have been handled.

### Zero Gateway Fees
There are no per-message fees charged by PulseSMS. Costs are limited to the chosen plan subscription and normal carrier charges on the device's SIM plan.

### Smart Contact Management
Contacts are organized into lists. Each list can contain thousands of entries with phone (required, E.164 format), name, and email fields. Lists support CSV import with validation. Contacts can be reused across multiple campaigns.

### Device Fleet Management
Multiple Android devices can be registered to an organization. Each device appears on the Devices page with status (Connected / Disconnected), phone number, carrier name, and last-seen timestamp. Devices send a heartbeat every 30 seconds.

### Webhooks & REST API
- Webhooks: Configure endpoint URLs to receive HTTP POST events for message and device lifecycle events. Payloads are HMAC-SHA256 signed with the webhook secret.
- REST API: Full programmatic access to campaigns, contacts, devices, organizations, and messages. Authenticated via session cookie (browser) or JWT Bearer token (API key exchange at `POST /api/auth/token`).
- API documentation: Interactive Scalar reference at pulse-sms.com/reference.

### Multi-Organization Support
Users can create and switch between organizations within a single account. All resources are isolated per organization. The active org is tracked via a cookie or `X-Organization-Id` header for API calls.

---

## Pricing Plans

| Plan       | Monthly Price | SMS / Month | Organizations | API Keys |
|------------|--------------|-------------|---------------|----------|
| Free       | $0           | 100         | 1             | 1        |
| Pro        | $10          | Unlimited   | 5             | Unlimited|
| Enterprise | $99          | Unlimited   | Unlimited     | Unlimited|

- Free plan requires no credit card.
- Pro and Enterprise are billed monthly via Stripe.
- Enterprise includes priority support; contact sales@pulse-sms.com.

---

## API Overview

### Authentication

**Session-based (browser dashboard):** Standard session cookies set after login via Better Auth.

**API key → JWT (programmatic):**
```
POST /api/auth/token
Content-Type: application/json

{ "apiKey": "pk_your_api_key_here" }

Response: { "token": "<jwt>", "expiresIn": 86400 }
```
Use the JWT as a Bearer token: `Authorization: Bearer <jwt>`

### Organization Scoping

Pass `X-Organization-Id: <org_id>` on all API requests, or rely on the active-org cookie (browser sessions).

### Key Endpoints

- `GET /api/campaigns` — List campaigns for the active org.
- `POST /api/campaigns` — Create a new campaign.
- `GET /api/contacts` — List contact lists.
- `POST /api/contacts` — Create a contact list.
- `GET /api/devices` — List connected gateway devices.
- `GET /api/messages` — List messages for the org.
- `POST /api/webhooks` — Register a webhook endpoint.

Full schema, request/response examples, and code snippets: [https://pulse-sms.com/reference](https://pulse-sms.com/reference)

### Webhook Events

All webhook payloads include the event type, timestamp, and relevant resource data. Signatures use HMAC-SHA256 over the raw request body with the webhook secret.

| Event                  | Triggered When                                  |
|------------------------|-------------------------------------------------|
| message.sent           | Gateway device accepts and sends the message    |
| message.delivered      | Carrier confirms delivery                       |
| message.failed         | Message could not be sent                      |
| campaign.started       | Campaign begins processing                      |
| campaign.completed     | All campaign messages have been processed       |
| device.connected       | Gateway device comes online                    |
| device.disconnected    | Gateway device goes offline                    |

---

## Getting Started (Summary)

1. **Create account** — Sign up at pulse-sms.com (free, no credit card).
2. **Download Android app** — From pulse-sms.com/download. Install the APK on an Android 6.0+ phone with a SIM.
3. **Connect device** — Dashboard → Devices → Connect device → scan QR code in the Android app.
4. **Add contacts** — Contacts → New list → Import CSV or add manually.
5. **Create campaign** — Campaigns → New campaign → select contact list → write message → send.
6. **Monitor delivery** — Open the campaign to see real-time delivery stats.

Full step-by-step guides:
- [Getting Started with PulseSMS](https://pulse-sms.com/blog/getting-started-with-pulsesms)
- [How to Send Your First SMS Campaign](https://pulse-sms.com/blog/how-to-send-your-first-sms-campaign)

---

## Frequently Asked Questions

**Do I need an SMS gateway or Twilio account?**
No. PulseSMS sends through your Android device using your carrier plan. You avoid per-message gateway fees; normal carrier rates and fair-use policies still apply.

**What phone can act as the gateway?**
Any Android device running Android 6.0 or later with an active SIM card that has SMS capability. The phone should stay powered and connected to the internet while processing campaigns.

**Can I use my existing business number?**
Yes — the point of PulseSMS is that recipients see SMS from the number on the gateway device. Use a dedicated line or any number you are authorized to use for outreach.

**How do upgrades and billing work?**
The Free tier includes core sending limits. Pro and Enterprise unlock higher limits and features. Pro is billed monthly via Stripe. Plans can be changed as volume grows.

**Is my contact data secure?**
Data is stored per-workspace (organization). Users should use strong passwords, restrict team access appropriately, and comply with local regulations such as consent requirements and opt-out handling for SMS campaigns.

**Can I send to multiple countries?**
Delivery depends on your carrier's international SMS roaming and the destination country's regulations. PulseSMS itself does not restrict by country, but carrier costs and deliverability vary.

**Is inbound SMS (replies) supported?**
Not in the current release. Replies arrive on the physical device's SIM. The dashboard does not currently display incoming messages.

---

## What PulseSMS Does Not Do

- Does not provide phone numbers — you supply the Android device and SIM.
- Does not support iOS gateway devices — Android only (6.0+).
- Does not replace carrier-grade APIs like Twilio for high-volume, latency-sensitive sends at scale.
- Does not work without an online Android gateway device.
- Does not offer inbound SMS or two-way messaging through the dashboard.
- Does not store payment card data — billing is delegated to Stripe.
- Does not guarantee delivery — delivery depends on device connectivity and carrier.

---

## Contact

- Support: support@pulse-sms.com
- Enterprise sales: sales@pulse-sms.com
- Website: https://pulse-sms.com
- API docs: https://pulse-sms.com/reference