SMS

Use this API to send SMS with numerous functions to one or more recipients at the same time.

POST/api/sms

Send SMS

Send an SMS to one or more recipients.

Name
to
Type
string
Description
Recipient number of the SMS. This can also be the name of a contact or a group. Our API accepts all common formats such as 0049171999999999, 49171999999999, +49171999999999. Multiple recipients are transferred comma-separated. Ideally, you should enter the phone number in international format after E.164.
Name
text
Type
string
Description
Text of the SMS message.

Name
from
Type
string
Optional
Optional
Description
Sender of the SMS. This may contain a maximum of 11 alphanumeric or 16 numeric characters.
Name
delay
Type
timestamp
Optional
Optional
Description
Date/time for delayed sending. Optionally Unix timestamp or a timestamp in the format YYYY-MM-DD hh:mm:ss.
Name
flash
Type
boolean
Optional
Optional
Description
Send SMS as Flash SMS. These are shown directly on the recipient's display. On most devices, no sender is displayed for Flash SMS, with the exception of some older models.
Name
udh
Type
string
Optional
Optional
Description
Individual User Data Header (UDH) of the SMS. If specified and variable text contains hex code, the message is sent as an 8-bit binary SMS. 050003CC0201 (concatenated message: reference number 204, part 1 of 2)
Name
ttl
Type
integer
Optional
Optional
Description
Specifies the validity period of the SMS in minutes. The default is 2880, i.e. 48 hours. Please note that not all networks allow a different setting. If omitted, the default validity from the account settings under Settings > Messages applies, otherwise 2880.
Name
label
Type
string
Optional
Optional
Description
Optionally set a separate label for each SMS so that you can assign it to your statistics. Max. 100 characters, permitted characters: a-z, A-Z, 0-9, .-_@.
Name
performance_tracking
Type
boolean
Optional
Optional
Description
Activate click and performance tracking for URLs found in the SMS text. This also activates the URL shortener. Requires a custom domain configured under Settings > Conversion Tracking, otherwise the request is rejected with code 603.
Name
foreign_id
Type
string
Optional
Optional
Description
Enter your own ID for this message. You will receive the foreign_id in turn for callbacks for status reports etc. Max. 64 characters, permitted characters: a-z, A-Z, 0-9, .-_@.
Name
is_binary
Type
boolean
Optional
Optional
Description
If true, the SMS is sent as an 8-bit binary SMS (DCS 0x04). Pass the payload as hex code in text (two hex characters per byte). Without udh, no User Data Header is sent. In the response, encoding is then binary.
Name
get_replies
Type
boolean
Optional
Optional
Description
Activates the reply function. Replies are assigned for 48 hours. The sender is automatically overwritten.
Name
unicode
Type
string
Deprecated
Deprecated
Description
Sending as Unicode SMS (Cyrillic, Arabic etc characters). This reduces the SMS length to 70 characters. Please note that our Gateway automatically recognizes the encoding. This parameter is therefore not necessary. However, you can use it to force a certain type of dispatch.
Name
utf8
Type
string
Deprecated
Deprecated
Description
Forces the recognition as UTF8 character set and overwrites the automatic recognition of the API.
Name
return_msg_id
Type
string
Deprecated
Deprecated
Description
If this parameter is set, the ID of the SMS is output in the second line after the status code. Has no effect if the json parameter is set to 1.
Name
details
Type
string
Deprecated
Deprecated
Description
Displays numerous details about the SMS sent. Useful for debugging. Has no effect if the json parameter is set to 1.
Name
json
Type
string
Deprecated
Deprecated
Description
The output is more detailed in JSON format. Please use Accept: application/json in the header instead.
Name
no_reload
Type
string
Deprecated
Deprecated
Description
Switch off reload lock. This block prevents the same SMS (text & recipient the same) from being sent within 180 seconds. You can also deactivate this block permanently in your login under Settings > SMS.

Request

POST

/api/sms

curl -X POST https://gateway.seven.io/api/sms \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Accept: application/json" \
    -d "to=49176123456789" \
    -d "from=AcmeInc" \
    -d "text=hello world"

Reply

{
    "success": "100",
    "total_price": 0.075,
    "balance": 593.994,
    "debug": "false",
    "sms_type": "direct",
    "messages": [
        {
            "id": "77229318510",
            "sender": "sender",
            "recipient": "49123456789",
            "text": "Hello World",
            "encoding": "gsm",
            "label": null,
            "parts": 1,
            "udh": null,
            "is_binary": false,
            "price": 0.075,
            "success": true,
            "error": null,
            "error_text": null
        },
        {
            "id": "77229318511",
            // ....
        }
    ]
}

File attachments

You can also send file attachments directly via API in your SMS. To do this, the respective files must be transferred to the files parameter as an associative array.

Properties

Name
name
Type
string
Description
File name. This must be inserted exactly as a placeholder in the SMS text. Here it would be [[document.pdf]]
Name
contents
Type
string
Description
Content of the file encoded as base64.

Optional properties

Name
validity
Type
integer
Description
Validity in days. The file is automatically deleted after the validity period. Default: 3
Name
password
Type
string
Description
Desired access password for the file. Without a password, the file can be viewed by anyone with the link.

Request

POST

/api/sms

curl -X POST https://gateway.seven.io/api/sms \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Accept: application/json" \
    -d "to=49176123456789" \
    -d "from=AcmeInc" \
    -d "text=Hello, here is the document: [[document.pdf]]" \
    -d "files[0][name]=document.pdf" \
    -d "files[0][contents]=iVBORw0KGgoAAAANSUhEUgAAAdoAAACWCAYAAAB5CUk..."

Return codes

For each SMS you will receive a return code in the reply, which provides detailed information about the sending or the error when sending the SMS.

Name
100
Description
SMS has been accepted by the gateway and is being sent.
Name
101
Description
Sending to at least one recipient failed.
Name
201
Description
Sender invalid. A maximum of 11 alphanumeric or 16 numeric characters are permitted.
Name
202
Description
The recipient number is invalid.
Name
301
Description
Parameter to not set.
Name
305
Description
Parameter text is invalid. Also returned if the SMS has more parts than the maximum set in the account under Settings > Messages.
Name
308
Description
An unknown or no longer supported parameter was sent in the request.
Name
401
Description
Parameter text is too long.
Name
402
Description
This SMS has already been sent within the last 180 seconds. You can deactivate this block in your account settings.
Name
403
Description
Maximum limit per day reached for this recipient number.
Name
407001
Description
The message was declined.
Name
407002
Description
Declined due to a geo restriction: the destination country is blocked in the account's country restrictions under Settings > Messages.
Name
407003
Description
Declined: the recipient number is blocked.
Name
407004
Description
Declined: the recipient has unsubscribed.
Name
407005
Description
Declined: the price per SMS part is higher than the maximum price set in the account under Settings > Messages.
Name
500
Description
Account has too little credit to send this SMS.
Name
501
Description
Spending limit reached: the request would exceed the account's daily or monthly spending limit set under Billing > Spending limits. Sending is possible again once the limit resets (daily at midnight, monthly on the 1st, CET/CEST).
Name
600
Description
An error has occurred during sending.
Name
603
Description
Performance tracking requires a custom domain. Configure one under Settings > Conversion Tracking.
Name
802
Description
Provided label is invalid.
Name
900
Description
Authentication has failed. Please check the API key used in Authentication.
Name
901
Description
Verification of the signing hash failed.
Name
902
Description
The API key does not have access rights to this endpoint.
Name
903
Description
The IP from which the request was executed is not included in the List of permitted IP addresses.

DELETE/api/sms

Delete SMS

Delete one or more SMS messages before they have been sent to prevent them from being sent.

Name
ids
Type
array
Description
A list of the SMS to be deleted. Enter the respective 'id's of the SMS to be deleted here.

Request

DELETE

/api/sms

curl -X DELETE "https://gateway.seven.io/api/sms" \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-type: application/json" \
    -d "{ \"ids\": [ 77150850625, 77150850626 ] }"

Answer

    {
        "success": true,
        "deleted": [
            "77150850625",
            "77150850626"
        ]
    }

For compatibility reasons, older and more basic access methods are still supported. Please note that new features are mainly released for the current API. In addition, the following usage may lead to problems with larger requests and security issues.

Examples

The following request from the following URL sends an SMS with the content my first message as an SMS with the sender seven.io to the phone number 49160999999999:

Request

GET

/api/sms

curl "https://gateway.seven.io/api/sms?p=YOUR_API_KEY&to=49160999999999&text=my%first%message&from=seven.io&return_msg_id=1"

Response

100
123456789

This request shows numerous details about the message, each separated by a line break:

Request

GET

/api/sms

curl "http://gateway.seven.io/api/sms?p=YOUR_API_KEY&to=Gruppe1&text=Test+SMS&from=SMS&flash=0&details=1"

Reply

100
Posted: 0.075
Price: 0.075
Credit: 27.38
Text: Test SMS
SMS type: direct
Flash SMS: off
Encoding: ASCII
GSM0338: true
Debug: false

SMS

Send SMS

Request

Reply

File attachments

Properties

Optional properties

Request

Return codes

Delete SMS

Request

Answer

Legacy

Examples

Request

Response

Request

Reply