Create the Bulk

POST

/bulks

Create a bulk SMS campaign by sending a POST request with message details and recipient information.

Authorizations

token

Request Body^required

The new bulks resource

application/json

Any of:

object
object

Bulk SMS creation request payload

object

delivery_at

One of:

integer
null

Timestamp de entrega programada

integer

sender_id

Sender-ID of the message. Can be a number (up to 15 digits) or a text (up to 11 character). In case of a number please use preferentially E.164 phone number format. A sender of text may contain spaces but no other special characters. Please note that some countries do not support own sender IDs or do require pre-registration. Our system automatically tries to detect whether a sender ID is a text or a phone number. Avoid special characters in a number and enter it the same way as it would be dialed on a phone.

Para mensagens de voz (text2speech, text2speech_ssml): se sender_id não estiver em conformidade com o formato E.164 (por exemplo, sem o prefixo +, contendo caracteres não numéricos), a mensagem será enviada a partir do número padrão do sistema +493075435114. Alguns provedores de telefonia downstream podem substituir ou não respeitar o número de remetente definido pelo usuário — o identificador de chamada real apresentado ao destinatário depende das capacidades do provedor.

string

/^(\+?[1-9]\d{0,14}|[a-zA-Z0-9 ]{1,11})$/

text

Max text length is 1785 character. But don’t forget that the final message text can have a length of up to 1530 characters. With a Unicode SMS, the maximum character length is reduced to 670 characters. Internal encoding is UTF-8.

string

<= 1785 characters

phones

required

List of the recipients (international) numbers:

+491701234567 (E.164)
00491701234567
491701234567
01701234567 (if the account is registered in Germany) will be convert to +491701234567

If the number is not in an E.164 format then the service will convert it based on user’s address. To avoid problems with the converting please use E.164 preferentially.

array | null

msg_groups

List of the recipients groups

array | null

is_unicode

True se a mensagem contém caracteres Unicode, False caso contrário

boolean | null

service_code

One of:

unknown
null

Código de serviço ou gateway

Allowed values: direct text2speech text2speech_ssml

source

Fonte ou origem da mensagem

integer | null

voice_lang

Idioma da mensagem de voz. Valores possíveis: null (detecção automática) ou um dos seguintes: EN (inglês), DE (alemão), FR (francês), IT (italiano), ES (espanhol), PL (polaco), NL (neerlandês), RO (romeno), PT (português), CS (checo), HU (húngaro), SV (sueco), DA (dinamarquês), FI (finlandês), SK (eslovaco), HR (croata), TR (turco), RU (russo), BG (búlgaro), UK (ucraniano).

string | null

Allowed values: EN DE FR IT ES PL NL RO PT CS HU SV DA FI SK HR TR RU BG UK

is_text_deleted

One of:

boolean
null

True se o texto da mensagem foi excluído, False caso contrário

boolean

Bulk SMS creation request payload

object

delivery_at

One of:

integer
null

Timestamp de entrega programada

integer

sender_id

string

/^(\+?[1-9]\d{0,14}|[a-zA-Z0-9 ]{1,11})$/

text

string

<= 1785 characters

phones

List of the recipients (international) numbers:

+491701234567 (E.164)
00491701234567
491701234567
01701234567 (if the account is registered in Germany) will be convert to +491701234567

If the number is not in an E.164 format then the service will convert it based on user’s address. To avoid problems with the converting please use E.164 preferentially.

array | null

msg_groups

required

List of the recipients groups

array | null

is_unicode

True se a mensagem contém caracteres Unicode, False caso contrário

boolean | null

service_code

One of:

unknown
null

Código de serviço ou gateway

Allowed values: direct text2speech text2speech_ssml

source

Fonte ou origem da mensagem

integer | null

voice_lang

string | null

Allowed values: EN DE FR IT ES PL NL RO PT CS HU SV DA FI SK HR TR RU BG UK

is_text_deleted

One of:

boolean
null

True se o texto da mensagem foi excluído, False caso contrário

boolean

Examples

example_bulks_request

Create bulk with static text and phones

Example of creating a bulk with static text to multiple phone numbers

{
  "sender_id": "testbulk",
  "text": "Hello! This is a test bulk message.",
  "phones": [
    "+49751234567",
    "+49751234568",
    "+49751234569"
  ],
  "service_code": "direct"
}

Responses

201

Bulks resource created

Bulk SMS details (JSON-LD)

object

@id

JSON-LD ID

string

@type

JSON-LD type

string

@context

One of:

string
object

string

uuid

Unique entity UUID

string

/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/

delivery_at

Timestamp de entrega programada

integer

sender_id

string

/^(\+?[1-9]\d{0,14}|[a-zA-Z0-9 ]{1,11})$/

text

string

<= 1785 characters

phones

List of the recipients (international) numbers:

+491701234567 (E.164)
00491701234567
491701234567
01701234567 (if the account is registered in Germany) will be convert to +491701234567

If the number is not in an E.164 format then the service will convert it based on user’s address. To avoid problems with the converting please use E.164 preferentially.

array | null

msg_groups

List of the recipients groups

array | null

status_code

Bulk’s status:

0 - new and not processed
5 - bulks in progress
10 - bulks was successfully processed
15 - bulk’s processing was canceled by the user
20 - system error
201 - error: no recipients found

integer

Allowed values: 0 5 10 15 20 201

msg_total_count

Count of the messages created by the bulk

integer

created_at

Timestamp when the entity was added to the system by the user

integer

processed_at

Timestamp of last changes

integer | null

IP address of the host which sent request

string format: ipv4

is_unicode

True se a mensagem contém caracteres Unicode, False caso contrário

boolean | null

is_dryrun

Type of the bulk ‘dryrun’ or not

boolean

service_code

Código de serviço ou gateway

Allowed values: direct text2speech text2speech_ssml

key_id

Identificador da chave API

integer

>= 1

source

Fonte ou origem da mensagem

integer | null

voice_lang

string | null

Allowed values: EN DE FR IT ES PL NL RO PT CS HU SV DA FI SK HR TR RU BG UK

is_text_deleted

True se o texto da mensagem foi excluído, False caso contrário

boolean

msg_total_cost

Cost of the messages created by the bulk

number

Examples

example_bulks_response_post

Bulk created (JSON-LD)

Example response for POST /bulks with Accept: application/ld+json

{
  "@context": "/contexts/Bulk",
  "@id": "/bulks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "@type": "Bulk",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "delivery_at": 0,
  "sender_id": "testbulk",
  "text": "Hello! This is a test bulk message.",
  "phones": [
    "+49751234567",
    "+49751234568",
    "+49751234569"
  ],
  "msg_groups": [
    7116,
    7117
  ],
  "status_code": 10,
  "msg_total_count": 1000,
  "created_at": 1755868416,
  "processed_at": 1755868500,
  "ip": "10.1.1.1",
  "is_unicode": false,
  "is_dryrun": false,
  "service_code": "direct",
  "key_id": 8291,
  "source": 0,
  "voice_lang": null,
  "is_text_deleted": false,
  "msg_total_cost": 56
}

Bulk SMS details

object

uuid

Unique entity UUID

string

/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/

delivery_at

Timestamp de entrega programada

integer

sender_id

string

/^(\+?[1-9]\d{0,14}|[a-zA-Z0-9 ]{1,11})$/

text

string

<= 1785 characters

phones

List of the recipients (international) numbers:

+491701234567 (E.164)
00491701234567
491701234567
01701234567 (if the account is registered in Germany) will be convert to +491701234567

If the number is not in an E.164 format then the service will convert it based on user’s address. To avoid problems with the converting please use E.164 preferentially.

array | null

msg_groups

List of the recipients groups

array | null

status_code

Bulk’s status:

0 - new and not processed
5 - bulks in progress
10 - bulks was successfully processed
15 - bulk’s processing was canceled by the user
20 - system error
201 - error: no recipients found

integer

Allowed values: 0 5 10 15 20 201

msg_total_count

Count of the messages created by the bulk

integer

created_at

Timestamp when the entity was added to the system by the user

integer

processed_at

Timestamp of last changes

integer | null

IP address of the host which sent request

string format: ipv4

is_unicode

True se a mensagem contém caracteres Unicode, False caso contrário

boolean | null

is_dryrun

Type of the bulk ‘dryrun’ or not

boolean

service_code

Código de serviço ou gateway

Allowed values: direct text2speech text2speech_ssml

key_id

Identificador da chave API

integer

>= 1

source

Fonte ou origem da mensagem

integer | null

voice_lang

string | null

Allowed values: EN DE FR IT ES PL NL RO PT CS HU SV DA FI SK HR TR RU BG UK

is_text_deleted

True se o texto da mensagem foi excluído, False caso contrário

boolean

msg_total_cost

Cost of the messages created by the bulk

number

Examples

example_bulks_response_post

Bulk created

Example response for POST /bulks with Accept: application/json

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "delivery_at": 0,
  "sender_id": "testbulk",
  "text": "Hello! This is a test bulk message.",
  "phones": [
    "+49751234567",
    "+49751234568",
    "+49751234569"
  ],
  "msg_groups": [
    7116,
    7117
  ],
  "status_code": 10,
  "msg_total_count": 1000,
  "created_at": 1755868416,
  "processed_at": 1755868500,
  "ip": "10.1.1.1",
  "is_unicode": false,
  "is_dryrun": false,
  "service_code": "direct",
  "key_id": 8291,
  "source": 0,
  "voice_lang": null,
  "is_text_deleted": false,
  "msg_total_cost": 56
}

400

Invalid input

401

Client ID or API key isn’t active or invalid!

403

Account isn’t activated. Please wait or contact to support!

422

The request was well-formed but was unable to be followed due to semantic errors

429

O endereço IP foi bloqueado temporariamente, pois durante um curto período de tempo foram enviadas várias solicitações com credenciais inválidas. Aguarde e tente mais tarde.

Code Samples

#!/usr/bin/env bash
curl -X POST https://api.lox24.eu/bulks \
  -H 'Content-Type: application/json' \
  -H 'X-LOX24-AUTH-TOKEN: 1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx' \
   -d '{
  "sender_id": "testbulk",
    "text": "test bulk text",
    "service_code": "direct",
    "phones": ["+49751234567"],
    "msg_groups": [7117],
    "delivery_at": 1573724611,
    "is_unicode": true,
    "source": 1234,
    "voice_lang": "DE"
    }'

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System;
using System.IO;
using System.Net;
using System.Text;

namespace Lox24.Api
{
    class client
    {
        static void Main()
        {
            string key = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx";
            string url = "https://api.lox24.eu/bulks";

            var data = new {
                sender_id = "My Sender",
                text = "Test message!",
                service_code = "direct",
                phones = new string[]{"+49751234567", "+49751234568"},
                msg_groups = new int[]{14514},
                delivery_at = 1573724611,
                is_unicode = true,
                voice_lang = "DE"
            };

            string postdata = JsonConvert.SerializeObject(data);

            Console.WriteLine("Post data: {0}", postdata);

            var httpWebRequest = (HttpWebRequest)WebRequest.Create(url);
            httpWebRequest.ReadWriteTimeout = 100000;
            httpWebRequest.ContentType = "application/json; charset=utf-8";
            httpWebRequest.Accept = "application/json"; // or application/ld+json
            httpWebRequest.Method = "POST";
            httpWebRequest.KeepAlive = true;
            httpWebRequest.Headers.Add("X-LOX24-AUTH-TOKEN", key);
            httpWebRequest.Credentials = CredentialCache.DefaultNetworkCredentials;

            using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
            {
                streamWriter.Write(postdata);
                streamWriter.Flush();
                streamWriter.Close();
            }
            try
            {
                using (HttpWebResponse resp = (HttpWebResponse)httpWebRequest.GetResponse())
                {

                    if(resp.StatusCode == HttpStatusCode.Created) {
                        Console.WriteLine("Success:{0} {1}", (int)resp.StatusCode, "bulks resource created");
                    } else {
                        Console.WriteLine("Error: wrong response code {0} on create bulk", (int)resp.StatusCode);
                    }

                    Stream respStream = resp.GetResponseStream();
                    using (StreamReader sr = new StreamReader(respStream, Encoding.UTF8))
                    {
                        string responseText = sr.ReadToEnd();
                        Console.WriteLine("responseText : {0}", responseText);
                    }
                }

            }
            catch (System.Net.WebException ex)
            {
                var webResponse = ex.Response as System.Net.HttpWebResponse;
                Console.WriteLine("Error:{0}", webResponse.StatusCode);

                switch (webResponse.StatusCode)
                {
                    case HttpStatusCode.BadRequest: // 400
                        Console.WriteLine("Error:400 Invalid input");
                        break;
                    case HttpStatusCode.Unauthorized: // 401
                        Console.WriteLine("Error:401 Client ID or API key isn't active or invalid!");
                        break;
                    case HttpStatusCode.Forbidden: // 403
                        Console.WriteLine("Error:403 Account isn't activated. Please wait or contact to support!");
                        break;
                    case HttpStatusCode.NotFound: // 404
                        Console.WriteLine("Error:404 Resource not found");
                        break;
                    case HttpStatusCode.InternalServerError: // 500
                    case HttpStatusCode.BadGateway: //502
                    case HttpStatusCode.ServiceUnavailable: // 503
                    case HttpStatusCode.GatewayTimeout: // 504
                        Console.WriteLine("System error! Please contact to LOX24 support!");
                        break;
                }
            }
        }
    }

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "log"
  "net/http"
)

func main() {

  const Method = "POST"
  const URL = "https://api.lox24.eu/bulks"
  const Token = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx"

  payload := map[string]interface{}{
    "sender_id":    "testbulk",
    "text":         "test bulk text",
    "service_code": "direct",
    "phones":       []string{"+49751234567"},
    "msg_groups":   []int{7117},
    "delivery_at":  1593724611,
    "is_unicode":   true,
    "source":       1234,
    "voice_lang":   "DE",
  }

  jsonPayload, _ := json.Marshal(payload)

  client := &http.Client{}

  req, err := http.NewRequest(Method, URL, bytes.NewBuffer(jsonPayload))
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Add("X-LOX24-AUTH-TOKEN", Token)
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Accept", "application/json")

  res, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }

  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    log.Fatal(err)
  }

  switch res.StatusCode {
  case 201:
    fmt.Println((string(body)))
  case 400:
    fmt.Println("Error: code = 400 - Invalid input")
  case 401:
    fmt.Println("Error: code = 401 - Client ID or API key isn't active or invalid!")
  case 403:
    fmt.Println("Error: code = 403 - Account isn't activated. Please wait or contact to support!")
  default:
    fmt.Printf("Error: code = %d\n", res.StatusCode)
  }
}

package eu.lox24.doc.bulks;

import org.json.JSONObject;

import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class PostBulksCollection {

    public static void main(String[] args) {

        var key = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx";
        var url = "https://api.lox24.eu/bulks";

        var json = new JSONObject();
        json.put("sender_id", "My Sender");
        json.put("text", "Test message!");
        json.put("service_code", "direct");
        json.put("phones", new String[]{"+49751234567", "+49751234568", "+49751234569"});
        json.put("msg_groups", new int[]{7116, 7117});
        json.put("delivery_at", 1573724611);
        json.put("is_unicode", true);
        json.put("voice_lang", "DE");

        var postData = json.toString();

        System.out.println("Post data: " + postData);

        var httpRequest = HttpRequest.newBuilder(URI.create(url))
                .timeout(Duration.ofMillis(100000))
                .setHeader("Content-Type", "application/json; charset=utf-8")
                .setHeader("Accept", "application/json") // or application/ld+json
                .setHeader("X-LOX24-AUTH-TOKEN", key)
                .POST(HttpRequest.BodyPublishers.ofString(postData))
                .build();

        var client = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_1_1) // Http 1.1 clients are kept alive be default
                .build();

        try {
            var httpResponse = client.send(httpRequest, HttpResponse.BodyHandlers.ofString());

            if (httpResponse.statusCode() == HttpURLConnection.HTTP_CREATED) {
                System.out.println("Success:" + httpResponse.statusCode() + " " + "bulks resource created");
                System.out.println("Response text : \n" + httpResponse.body());

            } else {

                System.out.println("Error: wrong response code " + httpResponse.statusCode() + " on create bulk");
                System.out.println("Response text : \n" + httpResponse.body());

                switch (httpResponse.statusCode()) {

                    case HttpURLConnection.HTTP_BAD_REQUEST: // 400
                        System.out.println("Error:400 Invalid input");
                        break;
                    case HttpURLConnection.HTTP_UNAUTHORIZED: // 401
                        System.out.println("Error:401 Client ID or API key isn't active or invalid!");
                        break;
                    case HttpURLConnection.HTTP_FORBIDDEN: // 403
                        System.out.println("Error:403 Account isn't activated. Please wait or contact to support!");
                        break;
                    case HttpURLConnection.HTTP_INTERNAL_ERROR: // 500
                    case HttpURLConnection.HTTP_BAD_GATEWAY: //502
                    case HttpURLConnection.HTTP_UNAVAILABLE: // 503
                    case HttpURLConnection.HTTP_GATEWAY_TIMEOUT: // 504
                        System.out.println("System error! Please contact to LOX24 support!");
                        break;
                }

            }

        } catch (IOException | InterruptedException e) {
            e.printStackTrace();
        }
    }
}

const host = 'api.lox24.eu';
const token = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx";

var postObj = {
    sender_id: 'My Sender',
    text: 'Test message',
    service_code: 'direct',
    phones: ['+49751234567', '+344354634'],
    msg_groups: [7117],
    delivery_at: 1573724611,
    is_unicode: true,
    voice_lang: 'DE',
};

var postdata = JSON.stringify(postObj);

const https = require('https');
const options = {
    hostname: host,
    path: '/bulks',
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Content-Length': postdata.length,
        'X-LOX24-AUTH-TOKEN': token
    }
}

const req = https.request(options, res => {
    if (res.statusCode == 201) {
        console.log("Success: code = 201 - bulks resource created");
        res.on('data', d => { process.stdout.write(d) })
    } else if (res.statusCode == 400) {
        console.log("Error: code = 400 - Invalid input");
    } else if (res.statusCode == 401) {
        console.log("Error: code = 401 - Client ID or API key isn't active or invalid!");
    } else if (res.statusCode == 403) {
        console.log("Error: code = 403 - Account isn't activated. Please wait or contact to support!");
    } else {
        console.log("Error: code = " + res.statusCode );
    }
});

req.on('error', error => {
    console.error(error)
});

req.write(postdata);
req.end();

<?php

$uri = 'https://api.lox24.eu/bulks';

$token = '1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx';

$body = [
    'sender_id' => 'testbulk',
    'text' => 'test bulk text',
    'service_code' => 'direct',
    'phones' => ['+49751234567'],
    'msg_groups' => [7117],
    'delivery_at' => 1573724611,
    'is_unicode' => true,
    'source' => 1234,
    'voice_lang' => 'DE',
];

if(!$body = json_encode($body)) {
    die('JSON encoding error!');
}

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_URL => $uri,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        "X-LOX24-AUTH-TOKEN: {$token}",
        'Accept: application/json', // or application/ld+json
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
]);

$response = curl_exec($curl);
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$data = json_decode($response, JSON_OBJECT_AS_ARRAY);

if(201 === $code) {
    echo 'Success: response data = ' . var_export($data, true);
} else {
    echo "Error: code = {$code}, data = " . var_export($data, true);
}

import json
import requests


token = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx"

url = "https://api.lox24.eu/bulks"

data = {
    'sender_id': "My Sender",
    'text' : "Test message",
    'service_code' : "direct",
    'phones': ["+49751234567", "+49751234568"],
    'msg_groups': [14514],
    'delivery_at': 1573724611,
    'is_unicode': True,
    'voice_lang' : "DE"
}

headers = {
    'Accept': 'application/json', # or application/ld+json
    'Content-Type': 'application/json',
    'X-LOX24-AUTH-TOKEN': token,
}

print("Post data: ", json.dumps(data, indent=4))

try:
    # timeout is 100 seconds
    res = requests.post(url, headers=headers, json=data, timeout=100)
    if res.status_code != 201: # Created
        res.raise_for_status()
    else:
        print(f'Success: code = {res.status_code} - bulks resource created')
        print("Response: ", json.dumps(res.json(), indent=4))

except requests.HTTPError:
    if res.status_code == 400:
        print("Error:400 Invalid input")
    elif res.status_code == 401:
        print("Error: code = 401 - Client ID or API key isn't active or invalid!")
    elif res.status_code == 403:
        print("Error: code = 403 - Account isn't activated. Please wait or contact to support!")
    elif res.status_code in (500, 502, 503, 504):
        print("System error! Please contact to LOX24 support!")
    else:
        print(f"Error: code {res.status_code}")
    print("Response: ", json.dumps(res.json(), indent=4))

Create the Bulk

Authorizations

Request Body required

Examples

Responses

201

Examples

Examples

400

401

403

422

429

Code Samples

Request Body^required