Kom igång med SMS API – från API-nyckel till leveransstatus

Den här guiden visar ett komplett första flöde: skapa en API-nyckel, bygg en giltig payload, skicka ett testmeddelande och kontrollera om det nådde mottagarens telefon. Du får också en checklista för att ta integrationen från test till produktion.

Guiden är en praktisk startpunkt. Den fullständiga och aktuella specifikationen finns alltid i SMS API-dokumentationen.

När ska du välja SMS API?

Välj SMS API när ett system ska skicka meddelanden automatiskt efter en händelse, exempelvis:

en bokning skapas eller ändras,
en order får ny leveransstatus,
ett HR-system behöver nå personal vid en schemaändring,
ett övervakningssystem upptäcker ett larm,
en användare begär en engångskod.

Om en person i stället ska skriva och skicka meddelanden manuellt är Web SMS ofta en enklare start. API:et är rätt val när utskicket ska bli en del av ett befintligt system eller arbetsflöde.

Så hänger SMS API och SMS Gateway ihop

Integrationen följer normalt detta flöde:

Er applikation skickar ett HTTPS-anrop med JSON till SMS API:et.
API:et validerar nyckel, avsändare, mottagare och innehåll.
SMS Gateway förmedlar meddelandet till mobiloperatören.
API:et returnerar ett batch-ID; varje mottagares meddelande-ID blir tillgängligt i batchens meddelandelista.
Leveransstatus hämtas via API eller skickas till er webhook.

Accepterad betyder att meddelandet har tagits emot för behandling. Endast statusen 201 DeliveredToHandset bekräftar leverans till mottagarens telefon.

Förbered testet

Du behöver:

ett iP.1-konto med SMS-saldo eller aktiv fakturering,
en API-nyckel med rätt behörighet,
en registrerad avsändare,
ett mobilnummer som du själv kan kontrollera,
en servermiljö eller terminal där nyckeln kan lagras säkert.

Skapa nyckeln i användarportalen och lägg den i en skyddad miljövariabel:

read -rsp "API-nyckel: " IP1_TOKEN && export IP1_TOKEN

Skriv aldrig nyckeln i JavaScript som körs i webbläsaren, mobilappen, versionshanteringen eller en delad logg. Skapa separata nycklar per integration så att en nyckel kan spärras utan att påverka andra system.

1. Bygg och kontrollera payloaden

Ett minimalt utskick kräver avsändare, minst en mottagare och meddelandetext:

{
  "sender": "DittForetag",
  "recipients": ["46700000000"],
  "body": "Test från iP.1 SMS API",
  "reference": "guide-test-001"
}

Telefonnummer anges som MSISDN: landskod och nummer utan +, mellanslag eller inledande 00. En svensk mottagare skrivs exempelvis 46700000000.

Använd gärna API-playground för att validera mottagare, räkna SMS-delar och generera kod. Verktyget körs lokalt i webbläsaren, gör inga API-anrop och frågar aldrig efter din API-nyckel.

2. Skicka testmeddelandet

Skapa en batch med POST /v2/batches:

curl --fail-with-body -X POST "https://api.ip1sms.com/v2/batches" \
  -H "Authorization: Bearer $IP1_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "DittForetag",
    "recipients": ["46700000000"],
    "body": "Test från iP.1 SMS API",
    "reference": "guide-test-001"
  }'

Byt avsändare och mottagare innan du kör anropet. Börja med ett eget testnummer och kontrollera alltid teckenlängd, avsändare och kostnad innan du skickar till en större lista.

3. Spara batchsvaret

Ett lyckat anrop returnerar ett batchdokument. Spara framför allt:

id – batchens ID för fortsatt uppföljning,
status – batchens sammanvägda status,
messageSummary – antal meddelanden och segment per status,
priceSummary – batchens beräknade kostnad,
reference – er egen referens som kopplar utskicket till rätt händelse.

Logga inte Bearer-token, fullständiga telefonnummer eller meddelandetext om de inte behövs. En intern referens, batch-ID och tidpunkt räcker ofta för felsökning.

4. Kontrollera leveransstatus

Lista meddelandena i batchen:

curl "https://api.ip1sms.com/v2/batches/{batchId}/messages" \
  -H "Authorization: Bearer $IP1_TOKEN" \
  -H "Accept: application/json"

Ersätt {batchId} med id från batchsvaret. Varje mottagare får ett eget meddelandedokument med den senaste statusen.

Statusgrupperna betyder i korthet:

1xx – meddelandet behandlas eller förmedlas,
201 – levererat till mottagarens telefon,
202–203 – avslutat utan leverans, exempelvis utgånget eller avbrutet,
4xx – avvisat på grund av konto, avsändare, innehåll eller mottagare,
5xx – tekniskt eller nätverksrelaterat leveransfel.

Läs alltid den specifika koden i statuskodsguiden. Ett 2xx-värde är inte automatiskt samma sak som leverans.

5. Ta emot status med webhook

För löpande produktion är en webhook effektivare än att fråga API:et upprepade gånger. Lägg till en publik HTTPS-adress när batchen skapas:

{
  "deliveryReportUrl": "https://example.com/webhooks/ip1sms"
}

iP.1 skickar leveransrapporter med POST. Mottagaren bör:

validera Content-Type och obligatoriska JSON-fält,
lägga rapporten i en intern kö,
svara snabbt med 200 OK,
behandla dubbletter idempotent,
använda id, code och created för att identifiera en statushändelse.

Byt exempeladressen mot en endpoint ni kontrollerar. Se leveransrapporter för payload, omförsök och säker hantering.

Vanliga problem

`400 Bad Request`

Kontrollera JSON, obligatoriska fält, avsändarformat och att mottagaren är ett giltigt MSISDN.

`401 Unauthorized`

Bearer-token saknas, är felaktig eller har spärrats. Kontrollera miljövariabeln utan att skriva ut nyckeln i loggen.

`403 Forbidden`

Nyckeln saknar behörighet eller avsändaren är inte tillåten för kontot eller destinationen.

För många anrop

Den publicerade gränsen är 30 anrop per sekund och konto. Använd kö, begränsad parallellitet och exponentiell backoff.

API-anropet lyckas men SMS:et kommer inte fram

Kontrollera meddelandets statuskod. Vanliga orsaker är felaktigt nummer, avvisad avsändare, otillåtet innehåll eller att mottagaren är tillfälligt offline.

Checklista före produktion

Lagra API-nyckeln i en hemlighetshanterare och rotera den regelbundet.
Begränsa nyckeln till de rättigheter och IP-adresser som integrationen behöver.
Använd kö och kontrollerad backoff i stället för obegränsade omförsök.
Spara batch- och meddelande-ID:n samt en egen reference.
Hantera webhook-händelser idempotent och acceptera att samma rapport kan komma flera gånger.
Kontrollera SMS-delar och Unicode innan större utskick.
Logga bara den persondata som behövs och definiera en gallringstid.
Övervaka avvisningar, tekniska fel och uteblivna leveransrapporter.
Säkerställ giltig rättslig grund och en tydlig avsändare för varje utskick.

Nästa steg

Bygg payloaden i API-playground.
Följ den kompletta guiden för att skicka SMS.
Konfigurera leveransrapporter.
Implementera hantering av statuskoder.
Utforska hela SMS API- och SMS Gateway-tjänsten.