Send SMS

Sends an SMS text message to a user's configured mobile phone number.

Endpoint

POST /v2/users/send-sms

note

The target user must have a cell phone number and cell carrier configured in their account. If either is missing or the carrier is unsupported, the message will not be delivered.

Request Body

Field	Type	Required	Constraints	Description
userId	integer	Yes	Must be an existing user	ID of the user to receive the SMS
message	string	Yes	—	The text message content to send

{
  "userId": 1042,
  "message": "Your ECGrid parcel download is ready."
}

Response

Returns a boolean indicating whether the SMS was successfully submitted for delivery.

{
  "success": true,
  "data": true
}

ENUMs

The user's cell carrier configuration uses the CellCarrier ENUM. This is set on the user's account, not passed in this request. See Appendix: ENUMs for the full list of supported carriers.

• CellCarrier — the mobile carrier associated with the user's phone number (e.g., ATTCingular, Verizon, TMobile, SprintPCS)

Code Examples

cURL

curl -X POST "https://rest.ecgrid.io/v2/users/send-sms" \
  -H "X-API-Key: $ECGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 1042, "message": "Your ECGrid parcel download is ready." }'

C#

// .NET 10 — Send an SMS notification to a user using IHttpClientFactory
// User must have a cell number and carrier configured on their account
public async Task<bool> SendSmsAsync(
    IHttpClientFactory httpClientFactory,
    int userId,
    string message)
{
    var http = httpClientFactory.CreateClient("ECGridRest");

    var requestBody = new
    {
        userId,
        message
    };

    var response = await http.PostAsJsonAsync(
        "https://rest.ecgrid.io/v2/users/send-sms",
        requestBody);
    response.EnsureSuccessStatusCode();

    var result = await response.Content.ReadFromJsonAsync<ApiResponse<bool>>();
    return result?.Data ?? false;
}

Java

import java.net.URI;
import java.net.http.*;

String apiKey = System.getenv("ECGRID_API_KEY");

String body = "{ \"userId\": 1042, \"message\": \"Your ECGrid parcel download is ready.\" }";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://rest.ecgrid.io/v2/users/send-sms"))
    .header("X-API-Key", apiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Node.js

const apiKey = process.env.ECGRID_API_KEY;
const url = 'https://rest.ecgrid.io/v2/users/send-sms';

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ "userId": 1042, "message": "Your ECGrid parcel download is ready." }),
});

const data = await response.json();
console.log(data);

Python

import os, requests

api_key = os.environ["ECGRID_API_KEY"]
headers = {"X-API-Key": api_key}
url = "https://rest.ecgrid.io/v2/users/send-sms"

response = requests.post(
    url,
    json={ "userId": 1042, "message": "Your ECGrid parcel download is ready." },
    headers=headers,
)

response.raise_for_status()
print(response.json())

See Also

• Get User — verify the user's contact details before sending
• Update Config — configure a user's cell phone number and carrier