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.

  • Name
    label
    Type
    integer
    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.

  • 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 will be sent as binary data.

  • 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 Gatway 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.

  • 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
    500
    Description

    Account has too little credit to send this SMS.

  • Name
    600
    Description

    An error has occurred during sending.

  • 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"
  ]
}

Legacy

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=meine%20erste%20nachricht&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
Last updated: 2 minutes ago