How it fits together

Three pieces work together. You drive everything from this web console.

  CSV + message template            paired Android phones
        │                                   ▲   │
        ▼                                   │   ▼  send over SIM
  ┌─────────────┐   queue / claim / report  ┌──────────────┐
  │  This server│◀──────────────────────────▶│  Phone app   │
  │  + database │   QR pairing (one-time)     │ (background) │
  └─────────────┘                             └──────────────┘
        ▲
        └── your browser (Dashboard, Lists, Campaigns, Reports)

• This server stores lists, campaigns, and stats, and meters out messages at your chosen rate.
• Phone app pairs once via QR, then sends queued messages in the background and reports status.
• Your browser is where you upload contacts, write messages, and watch results.

Quick start (5 steps)

1. 1
   Set your server URL in Settings so phones can reach this server (a LAN IP or public HTTPS address, not localhost).
2. 2
   Pair a phone in Devices by showing the QR and scanning it with the app.
3. 3
   Upload a CSV of contacts in Lists and confirm the phone-number column.
4. 4
   Write a campaign in Campaigns using {{column}} placeholders, then Test-send to yourself.
5. 5
   Press Start and watch live stats on the Dashboard.

1 · Settings (one-time)

Open Settings and set:

• Public server URL — the address phones connect to. It is baked into pairing QR codes, so it must be reachable from the phone (your LAN IP like http://192.168.1.50:3000, or a public HTTPS hostname). Not localhost.
• Default rate (msgs/min) — the send rate a new campaign starts at. Lower is gentler on carrier limits.
• Default country code — the dialing prefix (e.g. 1 for US/Canada) used to normalize bare numbers that have no country code.

2 · Pair a phone

1. 1
   Install the SMSBlaster app on the phone and grant the SMS + notification permissions. On Windows, the easiest way is the one-click installer under Devices → Set up a new phone (plug the phone in via USB with USB debugging on). Or get the APK directly from /api/app/apk.
2. 2
   Go to Devices → Pair a phone. A QR code and a tappable smsblaster:// link appear. The token is single-use and expires in 10 minutes.
3. 3
   In the app, tap Scan and scan the QR (or tap the link on the phone itself). The phone gets a random name like azure-otter-24 and an auth key.
4. 4
   The device appears under Devices as Online, with its IP, hostname, and carrier info.

Pair as many phones as you like. Campaigns fan out across every online phone, which adds resilience. To send faster, raise the campaign rate (see the FAQ).

3 · Upload a contact list

1. 1
   Go to Lists → Upload CSV. The first row must be column headers.
2. 2
   Confirm the auto-detected phone column (or pick it). Every number is normalized to E.164 using your default country.
3. 3
   The list shows its columns, row count, and a preview. Those column names become the merge variables you can drop into a message.

Example CSV:

first_name,last_name,phone,city
Ada,Lovelace,555-123-0000,Reno
Alan,Turing,(555) 987 6543,Sparks

Numbers that fail validation are skipped at campaign time (counted as skipped), so a messy column won't stop the rest of the list.

4 · Build a campaign

1. 1
   Go to Campaigns → New, pick the list, and name the campaign.
2. 2
   Write the message with {{column_name}} placeholders. Click a chip in the variable palette to insert one. The live preview renders against a real row and flags any {{variables}} that don't match a column.
3. 3
   Choose a mode: Standard blast sends your message to everyone; Anchor question sends a short question first and only pitches people who reply (see below).
4. 4
   (Optional) attach an image to send a picture (MMS) message; every recipient gets the image plus your text as a caption. Leave it empty for plain SMS.
5. 5
   Set the rate per minute (defaults to your setting), then Test-send to your own number to see the real message before committing.
6. 6
   Press Create. The server pre-renders and queues one message per valid contact and reports queued vs skipped.

A message like Hi {{first_name}}, still looking in {{city}}? becomes Hi Ada, still looking in Reno? for each contact.

Anchor-question campaigns

Anchor mode is the recommended flow for colder lists: it self-filters before pitching, so you send far less sales copy to silent numbers.

• Step 1 is your short question (the main message), e.g. "Hi {{first_name}}, are you still the homeowner at {{address}}?"
• Step 2 is sent only after the contact replies. The server reads the reply and picks the matching follow-up:

• YES / positive follow-up — required
• NO / negative follow-up — optional
• "Who is this / what is this about?" follow-up — optional
• Other replies — optional, defaults to the YES follow-up

A STOP reply suppresses that number from future campaigns automatically.

5 · Run & monitor

• Press Start. The server releases messages to online phones at the campaign's rate; phones send via their SIM and report back.
• The campaign card shows live stats: pending / dispatched / sent / failed and a percent complete.
• Pause holds new sends (in-flight ones still report); Resume continues.
• A campaign flips to Done when nothing is pending or in flight.

Lifecycle:

draft  ──Start──▶  running  ──Pause──▶  paused
                     │   ▲                  │
                     │   └──────Resume──────┘
                     └──(all messages done)──▶  done

Replies & inbound calls

• Replies from contacts drive anchor follow-ups and show up on the Dashboard. A reply is also tagged with a rough sentiment (positive / negative).
• Inbound calls to your numbers are captured by the phone's caller-ID, with answered/missed outcome and talk time, in Calls.
• Dispositions let you tag a call outcome (Sale / No sale / Call back / DNC) from the phone's lead popup or here in Dispositions. A DNC tag also suppresses the number.

Do-Not-Contact & compliance

• Add numbers to your DNC list manually, by CSV/text upload, or automatically via STOP replies and DNC dispositions. Suppressed numbers are skipped when a campaign is created.
• National DNC scrubbing (hosted edition) can check a file against the National DNC Registry and add hits to your DNC list before you send.
• Carrier line-type targeting (hosted edition): classify a list by line type via a live carrier dip in Lists (Wireless / VOIP / Landline / Reseller). When creating a campaign you can target only the line types you want; invalid numbers are always scrubbed. New lists default to Wireless + VOIP.
• Your responsibility: get consent before texting, identify yourself, and honor opt-outs ("Reply STOP"). SMSBlaster records STOP suppression, but list hygiene and legal compliance are up to you.

Reports

The Reports tab summarizes activity over a date range: totals, a daily activity chart, and breakdowns by campaign and by device. Dispositions and calls can be exported to CSV from their own tabs for outside analysis.

FAQ & gotchas

How do I send faster?

Throughput is the campaign's rate_per_min, shared across all phones. More phones add resilience, not speed, unless you raise the rate. Push the rate up gradually and watch for carrier failures.

What happens if a phone goes offline?

Offline phones are skipped automatically. If every phone is offline the queue simply waits until one comes back.

Are failed messages retried?

A dropped claim (a phone that took messages but never reported) is re-queued automatically. A reported failed is final; check its error to diagnose (no service, invalid number, etc.).

SMS vs MMS?

Leave the image empty for plain SMS. Attach an image to send MMS (picture) messages. MMS needs mobile data and may cost more or be rate-limited harder by carriers. RCS is not supported.

Why must the server URL be reachable from the phone?

The phone connects back to this server to claim and report messages, so localhost won't work. Use a LAN IP or a public HTTPS URL.

More detail lives in the full docs shipped with the server (architecture, API reference, agent protocol, MMS, deployment).