API-dokumentaatio

Yleiskatsaus

SMS24 REST API mahdollistaa tekstiviestien lähettämisen, saldon tarkistuksen ja kontaktien hallinnan ohjelmallisesti. API palauttaa JSON-vastauksia ja käyttää HTTP-statuskoodeja.

Base URL	https://gw.sms24.fi
Muoto	JSON (Content-Type: application/json)
Autentikointi	Bearer token (API-avain)
Enkoodaus	UTF-8

Autentikointi

Luo API-avain Oma SMS24 → API -sivulta. Käytä avainta Authorization-headerissa:

Authorization: Bearer SINUN_API_AVAIMESI

API-avain on 64 merkin heksadesimaalimerkkijono. Voit luoda useita avaimia ja poistaa niitä käytöstä yksitellen.

Lähetä viesti

Lähetä tekstiviesti yhdelle tai useammalle vastaanottajalle.

Parametrit (JSON body)

Parametri	Tyyppi	Pakollinen	Kuvaus
to	string | string[]	Kyllä	Vastaanottajan numero tai taulukko numeroista. Kansainvälinen muoto (esim. 358401234567).
message	string	Kyllä	Viestin sisältö. Max 160 merkkiä = 1 osa, yli 160 merkkiä jaetaan 153 merkin osiin.
from	string	Ei	Lähettäjänimi (3–11 merkkiä, aakkosnumeerinen). Täytyy olla hyväksytty asetuksissa. Oletus: tilisi oletuslähettäjänimi.

Esimerkki: yksi vastaanottaja

curl -X POST https://gw.sms24.fi/send \
  -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "358401234567",
    "message": "Hei! Tämä on testiviesti."
  }'

Esimerkki: useita vastaanottajia

curl -X POST https://gw.sms24.fi/send \
  -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["358401234567", "358409876543"],
    "message": "Ryhmäviesti kaikille.",
    "from": "MiniYritys"
  }'

Onnistunut vastaus 200

{
  "results": [
    {"number": "358401234567", "status": "ok", "batch_id": 123456},
    {"number": "358409876543", "status": "ok", "batch_id": 123457}
  ]
}

Virhevastaus

// 401 Unauthorized
{"error": "Invalid API key"}

// 400 Bad Request
{"error": "No recipients"}

// 200 (osittainen virhe)
{
  "results": [
    {"number": "358401234567", "status": "ok", "batch_id": 123456},
    {"number": "abc", "status": "error", "error": "Numero virheellinen"}
  ]
}

Query-parametrit (vaihtoehtoinen)

Voit myös lähettää GET/POST-pyyntöjä query-parametreilla:

curl -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  "https://gw.sms24.fi/send?n=358401234567&m=Testiviesti&from=MiniYritys"

Saldon tarkistus

Tarkista jäljellä olevien viestien määrä.

Esimerkki

curl -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  https://gw.sms24.fi/credits

Vastaus 200

{"messages": 150}

Viestihistoria

Hae lähetettyjen viestien historia suodatuksella ja sivutuksella.

Query-parametrit

Parametri	Tyyppi	Oletus	Kuvaus
start	string	—	Alkupäivä (YYYY-MM-DD)
end	string	—	Loppupäivä (YYYY-MM-DD)
number	string	—	Suodata vastaanottajan numerolla
status	string	—	Suodata: scheduled, sent, delivered, failed
limit	integer	100	Tulosten enimmäismäärä (max 500)
offset	integer	0	Sivutuksen offset

Esimerkki

curl -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  "https://gw.sms24.fi/api/history.php?start=2025-01-01&end=2025-01-31&limit=10"

Vastaus 200

{
  "messages": [
    {
      "id": 0,
      "sendtime": "2025-01-15 10:30:00",
      "sender_id": "MiniYritys",
      "number": "358401234567",
      "msg": "Muistathan palaverin klo 14.",
      "parts": 1,
      "status_code": 1,
      "status": "delivered"
    }
  ],
  "count": 1,
  "offset": 0,
  "limit": 10
}

Status-arvot

status	status_code	Kuvaus
delivered	1	Viesti toimitettu vastaanottajalle
sent	0	Lähetetty, odottaa toimitusta
scheduled	-10	Ajastettu lähetettäväksi
failed	< 0	Lähetys epäonnistui

Kontaktien hallinta

Listaa osoitekirjat ja kontaktit

curl -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  https://gw.sms24.fi/api/contacts.php

Vastaus 200

{
  "addressbooks": [
    {
      "id": 1,
      "name": "Myyntitiimi",
      "contact_count": 3,
      "contacts": [
        {"id": 10, "name": "Matti Meikäläinen", "number": "358401234567"},
        {"id": 11, "name": "Liisa Virtanen", "number": "358409876543"}
      ]
    }
  ]
}

Tietyn osoitekirjan kontaktit

Luo osoitekirja

curl -X POST https://gw.sms24.fi/api/contacts.php \
  -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  -H "Content-Type: application/json" \
  -d '{"action": "create_list", "name": "Uusi ryhmä"}'

// Vastaus:
{"success": true, "id": 5, "name": "Uusi ryhmä"}

Lisää kontakti

curl -X POST https://gw.sms24.fi/api/contacts.php \
  -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  -H "Content-Type: application/json" \
  -d '{"action": "add_contact", "ab_id": 5, "name": "Matti", "number": "358401234567"}'

// Vastaus:
{"success": true}

Poista kontakti

curl -X POST https://gw.sms24.fi/api/contacts.php \
  -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  -H "Content-Type: application/json" \
  -d '{"action": "delete_contact", "c_id": 10}'

Poista osoitekirja

curl -X POST https://gw.sms24.fi/api/contacts.php \
  -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  -H "Content-Type: application/json" \
  -d '{"action": "delete_list", "ab_id": 5}'

Käyttäjätiedot

Hae tilisi tiedot, lähettäjänimi ja asetukset.

curl -H "Authorization: Bearer SINUN_API_AVAIMESI" \
  https://gw.sms24.fi/api/status.php

Vastaus 200

{
  "id": 123,
  "name": "Matti Meikäläinen",
  "email": "matti@yritys.fi",
  "senderid": "MiniYritys",
  "price": 0.10,
  "messages_balance": 150,
  "advance_only": "f",
  "message_alert": 20,
  "max_parts_per_msg": 3
}

HTTP-statuskoodit

Koodi	Merkitys	Kuvaus
200	OK	Pyyntö onnistui
400	Bad Request	Puuttuva tai virheellinen parametri
401	Unauthorized	API-avain puuttuu tai on virheellinen
405	Method Not Allowed	Väärä HTTP-metodi
429	Too Many Requests	Liian monta pyyntöä (rate limit)

Kaikki virhevasaukset noudattavat samaa muotoa:

{"error": "Virheen kuvaus"}

Esimerkit eri kielillä

PHP

$ch = curl_init('https://gw.sms24.fi/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('SMS24_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to'      => '358401234567',
        'message' => 'Hei! Tämä on testiviesti.',
    ]),
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);

Python

import os, requests

response = requests.post(
    "https://gw.sms24.fi/send",
    headers={"Authorization": f"Bearer {os.environ['SMS24_API_KEY']}"},
    json={
        "to": "358401234567",
        "message": "Hei! Tämä on testiviesti.",
    },
)
print(response.json())

JavaScript (Node.js)

const response = await fetch("https://gw.sms24.fi/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SMS24_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "358401234567",
    message: "Hei! Tämä on testiviesti.",
  }),
});
const data = await response.json();
console.log(data);

C# (.NET)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add(
    "Authorization",
    $"Bearer {Environment.GetEnvironmentVariable("SMS24_API_KEY")}");

var response = await client.PostAsJsonAsync(
    "https://gw.sms24.fi/send",
    new { to = "358401234567", message = "Hei! Tämä on testiviesti." });

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

MCP-integraatio (AI-assistentit)

SMS24 tarjoaa MCP-palvelimen (Model Context Protocol), jonka avulla AI-assistentit voivat lähettää viestejä ja hallita kontakteja puolestasi.

Tuetut työkalut

Työkalu	Kuvaus
send_sms	Lähetä tekstiviesti yhdelle tai useammalle vastaanottajalle
check_balance	Tarkista jäljellä olevien viestien saldo
list_contacts	Listaa osoitekirjat ja kontaktit

Konfiguraatio

Lisää seuraava JSON Claude Desktopiin, Cursoriin tai muuhun MCP-yhteensopivaan sovellukseen:

{
  "mcpServers": {
    "sms24": {
      "url": "https://gw.sms24.fi/mcp",
      "headers": {
        "Authorization": "Bearer SINUN_API_AVAIMESI"
      }
    }
  }
}

Lisätietoja: MCP-integraation esittelysivu