Send Your First Message
Before you start
You'll need:
- A Surge account at hq.surge.app
- An API key (find it under API Keys in the left sidebar of the dashboard)
- Your account ID (shown at the top of the dashboard, format:
acct_01j...) - A phone number you can receive texts on
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="YOUR_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("YOUR_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(
"YOUR_ACCOUNT_ID",
to: "+18015551234",
body: "Hello from Surge!"
)
puts message.idclient = Surge.Client.new("YOUR_API_KEY")
{:ok, message} = Surge.Messages.create(
client,
"YOUR_ACCOUNT_ID",
%{to: "+18015551234", body: "Hello from Surge!"}
)
IO.puts(message.id)curl -X POST https://api.surge.app/accounts/YOUR_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.
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.
Demo limits
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 to get carrier approval for your brand and campaign
- Pick an SDK for pagination, error handling, and webhook signature verification out of the box
Once registered, purchase a phone number and attach it to your campaign to start sending at scale.