Sending SMS API

Queues one outbound message. Returns as soon as it's queued — not when it's actually sent.

POST/api/v1/sms/send/

Authentication

Authorization: Bearer YOUR_API_KEY — see Authentication.

Parameters

Parameter	Type	Required	Description
`to`	string	Required	Recipient in E.164 format, e.g. `+212612345678`.
`from`	string	Required	Sender number in E.164 format. Must belong to a SIM your account can send from.
`message`	string	Required	Body text, up to 1,600 characters (~10 concatenated SMS segments).
`request_id`	string	Optional	Your own idempotency key. Reusing it within 24h returns the original message instead of creating a duplicate.
`send_at`	ISO 8601 (UTC)	Optional	Hold the message until this time instead of sending immediately. Must be in the future.

The field is from in JSON; some client libraries reserve that word, so the API also accepts from_number as an equivalent alias.

Example request

bash

curl -X POST https://www.connecfy.com/api/v1/sms/send/ \
  -H "Authorization: Bearer $CONNECFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+212612345678",
    "from": "+212600000000",
    "message": "Your verification code is 482910",
    "request_id": "order-12345"
  }'

python

import os, requests

resp = requests.post(
    "https://www.connecfy.com/api/v1/sms/send/",
    headers={"Authorization": f"Bearer {os.environ['CONNECFY_API_KEY']}"},
    json={
        "to": "+212612345678",
        "from": "+212600000000",
        "message": "Your verification code is 482910",
        "request_id": "order-12345",
    },
)
data = resp.json()
message_id = data["message_id"]

javascript

const res = await fetch("https://www.connecfy.com/api/v1/sms/send/", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CONNECFY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+212612345678",
    from: "+212600000000",
    message: "Your verification code is 482910",
    request_id: "order-12345",
  }),
});
const { message_id } = await res.json();

php

$ch = curl_init("https://www.connecfy.com/api/v1/sms/send/");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("CONNECFY_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "to" => "+212612345678",
        "from" => "+212600000000",
        "message" => "Your verification code is 482910",
        "request_id" => "order-12345",
    ]),
]);
$data = json_decode(curl_exec($ch), true);
$messageId = $data["message_id"];

Response

202 Accepted — queued, not yet sent:

JSON

{
  "status": "queued",
  "message_id": "f3a1b2c4-d5e6-7890-abcd-ef1234567890",
  "request_id": "order-12345",
  "device_id": "a8b9c0d1-2e3f-4a5b-6c7d-8e9f0a1b2c3d",
  "from_number": "+212600000000",
  "to": "+212612345678",
  "created_at": "2026-08-26T14:30:00.123Z"
}

Replaying the same request_id within 24 hours returns this identical body again with 200 OK instead of creating a second message.

Checking status afterward

GET/api/v1/sms/<message_id>/

bash

curl https://www.connecfy.com/api/v1/sms/f3a1b2c4-d5e6-7890-abcd-ef1234567890/ \
  -H "Authorization: Bearer $CONNECFY_API_KEY"

JSON

// 200 OK
{
  "status": "delivered",
  "message_id": "f3a1b2c4-...",
  "request_id": "order-12345",
  "device_id": "a8b9c0d1-...",
  "from_number": "+212600000000",
  "to": "+212612345678",
  "created_at": "2026-08-26T14:30:00.123Z"
}

Only returns messages your own account queued — an unrecognized or someone-else's message_id is a 404, not a permissions error, so it can't be used to probe whether an id exists on another account.

Errors

Full list with causes and fixes: Errors. The ones specific to sending:

HTTP	code	Cause
400	(field name)	A field failed validation — see the body for which one
401	`auth_invalid_key`	Missing, wrong, or revoked API key
402	`quota_exceeded`	Monthly SMS limit reached for your plan
403	`from_number_not_found`	`from` isn't a number registered to any SIM on your account
403	`from_number_access_denied`	The number exists, but your account isn't allowed to send from it
503	`device_inactive`	The SIM behind `from` has been deactivated
429	—	More than 120 requests/min — see Rate Limits

Message lifecycle

What happens after queued, and what delivered actually confirms: Message Lifecycle.