Send Your First Message

Send an SMS in under five minutes using Surge’s demo number. No carrier registration, no phone number purchase required.

Prerequisites

Surge account: Sign up at hq.surge.app.
API key: Find it under API Keys in the left sidebar of the dashboard.
Account ID: Shown at the top of the dashboard, format acct_01j....
A phone number you can receive texts on: Used as the to value in your first send.

1. Send a message

Every outbound message goes through the same endpoint. Replace the account ID, API key, and to number with your own values.

from surge import Surge

surge = Surge()  # uses SURGE_API_KEY env var

message = surge.messages.create(
    account_id="{account_id}",
    to="+18015551234",
    body="Hello from Surge!",
)

print(message.id)

import Surge from "@surgeapi/node";

const surge = new Surge(); // uses SURGE_API_KEY env var

const message = await surge.messages.create("{account_id}", {
  to: "+18015551234",
  body: "Hello from Surge!",
});

console.log(message.id);

require "surge_api"

surge = SurgeAPI::Client.new # uses SURGE_API_KEY env var

message = surge.messages.create(
  "{account_id}",
  to: "+18015551234",
  body: "Hello from Surge!"
)

puts message.id

client = Surge.Client.new("YOUR_API_KEY")

{:ok, message} = Surge.Messages.create(
  client,
  "{account_id}",
  %{to: "+18015551234", body: "Hello from Surge!"}
)

IO.puts(message.id)

curl -X POST https://api.surge.app/accounts/{account_id}/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+18015551234",
    "body": "Hello from Surge!"
  }'

You don’t need a from number. New accounts send from a demo number automatically.

2. Check the response

A successful request returns the message object:

{
  "id": "msg_01kqbhwra9egg8sdcsp9veg391",
  "body": "Hello from Surge!",
  "blast_id": null,
  "attachments": [],
  "metadata": {},
  "conversation": {
    "id": "cnv_01kpc9b1jgepxazwjya3scxse4",
    "contact": {
      "id": "ctc_01kpc9b1jefg28pfpvf96t9ce6",
      "phone_number": "+18015551234",
      "first_name": null,
      "last_name": null,
      "email": null,
      "metadata": {}
    },
    "phone_number": {
      "id": "pn_01kpc9b1jaeaht0an56f6r4p7v",
      "name": "Demo phone number",
      "type": "demo",
      "number": "+13854252553"
    }
  }
}

Within a few seconds, the phone number you specified in to receives a text. If nothing arrives after 60 seconds, check that the number is in E.164 format: starting with + and country code, like +18015551234.

3. Watch for the demo limit

The demo number has a cap of 25 outbound messages per account. When you hit the limit, the API returns a 403 with:

{
  "error": {
    "type": "demo_message_limit",
    "message": "Demo messaging limit has been reached."
  }
}

Next steps

Two things unlock production sending: register your business and purchase a phone number. Pick an SDK while you wait for review to clear.

Register your business

Get carrier approval for your brand and campaign.

Pick an SDK

Pagination, error handling, and webhook signature verification out of the box.

Purchase a phone number

Buy a local or toll-free number and let Surge attach it to your campaign.

Receive webhooks

Verify signatures and handle inbound messages, deliveries, and opt-outs.

Get started

Register your business

Sending messages

Receiving messages & webhooks

Phone numbers

Verifications

Channels roadmap

Embeddable UI components

Concepts

Send Your First Message

Prerequisites

1. Send a message

2. Check the response

3. Watch for the demo limit

Next steps

Register your business

Pick an SDK

Purchase a phone number

Receive webhooks

​Prerequisites

​1. Send a message

​2. Check the response

​3. Watch for the demo limit

​Next steps

Register your business

Pick an SDK

Purchase a phone number

Receive webhooks

Prerequisites

1. Send a message

2. Check the response

3. Watch for the demo limit

Next steps