API Integration Guide

The Síminn magnSMS API allows organizations to send SMS messages globally (up to 1040 characters) and integrate messaging directly into third-party systems via HTTP/HTTPS.

Prerequisites

Before you begin, you must have an active account.

Credentials: Username (L) and Password (P).
Request Access: If you do not have credentials, contact radgjof@siminn.is.

Connection Settings

Base URL: https://vasp.siminn.is/smap/
Protocol: HTTPS (Recommended) or HTTP.
Authentication: Credentials must be passed as parameters in every request.

1. Sending Messages (`/push`)

Use this endpoint to send a message to a single number, multiple numbers, or a pre-defined group.

Endpoint: POST https://vasp.siminn.is/smap/push

Alternative: GET https://vasp.siminn.is/smap/push

Request Parameters

Parameter	Required	Description
`L`	Yes	Your account username.
`P`	Yes	Your account password.
`msisdn`	Yes*	Recipient number(s). Separate multiple numbers with `,` or `;`. Normal 7 digits Icelandic phone numbers or International phone numbers then format starts with `+` or `00`.
`T`	Yes *	The message text.
`group`	Cond.*	Name of a pre-defined recipient group.
`T`	Cond.	The message text.
`text_template`	Cond.	Pre-defined message template name.
`A`	No	Sender ID (Originator). Maximum 11 characters. From GSM Basic Character Set
`unicode`	No	Use `y` to support Icelandic characters (ð, þ, etc.). This limits one SMS to 70 chars.
`dr`	No	Use `y` to request a Delivery Report (Callback).
`flash`	No	If set, the SMS appears immediately on the screen (Class 0).
`vp`	No	Validity Period in minutes (1–4320). Default is 3 days.
`reference`	No	Custom ID for your tracking purposes.
`scheduled`	No	Send at a future date (Format: ISO-8601).

* Either msisdn or group must be provided. Either T or text_template must be provided.

[!NOTE]
Character Limits & Billing: Standard GSM 7-bit messages allow 160 characters. If you use unicode=y, the limit drops to 70 characters. Messages exceeding these limits are sent as multiple concatenated SMS segments and billed accordingly.

2. Character Encoding

To ensure that Icelandic characters and special symbols are delivered correctly, you must handle character encoding based on the HTTP method used.

GET Requests

When using HTTP GET, the API assumes that all text strings in the URL parameters are encoded in ISO-8859-1.

Warning: If you send UTF-8 encoded strings via GET without conversion, special characters (like þ, æ, ö) will likely appear garbled.

POST Requests

When using HTTP POST, you have more flexibility. You can specify your preferred character set in the Content-Type header of your request.

Recommended Header: Content-Type: application/x-www-form-urlencoded; charset=utf-8
The system will read the charset defined in the header and decode the message body accordingly.

3. Status Queries (`/query`)

Check the delivery status of a specific message manually.

Endpoint: GET /smap/query

Required Parameters:

L: Username
P: Password
messageid: The ID returned by the initial PUSH request.

Response Format:

The service returns three lines of plain text:

Status String (e.g., DELIVERED, EXPIRED, REJECTED)
Error Code
Timestamp of the current status.

Status String	Description
`ACCEPTED`	Received by the SMS system.
`DELIVERED`	Successfully delivered to the handset.
`EXPIRED`	Delivery failed after several attempts (timed out).
`UNDELIVERABLE`	Could not be delivered (e.g., disconnected number).
`REJECTED`	Message rejected by system.

4. Delivery Reports (Callbacks)

If the dr flag was set in your PUSH request, the system will POST to your pre-registered* callback URL once the message reaches a final state.

Parameter	Description
`id`	The original message ID.
`msisdn`	The recipient's phone number.
`results`	`DELIVERED`, `EXPIRED`, or `UNDELIVERABLE`.
`text`	The content of the message.

* Contact radgjof@siminn.is to register your callback URL

5. Troubleshooting (Error Codes)

Common API Errors

Code	Type	Meaning	Action
314	Client	Message too long	Keep messages under 540 characters.
401	Auth	Unauthorized	Verify your `L` and `P` parameters.
403	Limit	Throttled	Reduce the frequency of your API calls.
500	Server	System Error	Wait a few seconds and retry.
600	Billing	Insufficient Credit	Top up your account balance.

Encoding Issues (Stafabrenglu)

Symptom	Cause	Solution
`ð` becomes `d`	No Unicode flag	Set `unicode=y` in the request.
`þ` becomes `Ã¾`	UTF-8 sent to GET	Use POST with `charset=utf-8` or convert to ISO-8859-1.
`ö` becomes `?`	Incorrect charset header	Ensure `Content-Type` header matches your payload encoding.

6. Implementation Examples

Python (POST with UTF-8)

Python
import requests

url = 'https://vasp.siminn.is/smap/push'
headers = {'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8'}

payload = {
    'L': 'your_username',
    'P': 'your_password',
    'msisdn': '354XXXXXXX',
    'T': 'Hyldýpi þjóðfélagsins vex úr kærkomnu böli í ást',
    'unicode': 'y', 
    'dr': 'y',
    'A': 'Siminn'
}

response = requests.post(url, data=payload, headers=headers)
print(response.text)

CURL

Bash
curl -X POST -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
--data-ascii "L=USER&P=PASS&msisdn=354XXXXXXX&T=TestMessage&unicode=y" \
https://vasp.siminn.is/smap/push

Need further help? Would you like me to generate a template for the callback listener URL so you know how to process incoming delivery reports?

SMS Magnsendingar API