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!"
  }'

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.