SMSBOX logo
API docs by Redocly

SMSBOX - SMS API Documentation (1.1.0)

URL: https://www.smsbox.net

Changelog

Version Date Changes
1.1.0 01/15/2026 📲 Initial OpenAPI documentation for the SMS API v1.1 (migrated from PDF documentation).

Send

Send SMS messages to one or multiple recipients, or to predefined contact groups.

Useful tool: Use our SMS character counter to check your message length and the number of SMS required based on encoding (GSM 7-bit or Unicode).

SMS Character Counter

Testing: Use Sandbox numbers to test your integration with simulated delivery reports.

Send message

Send one or multiple SMS messages to one or multiple recipients.

Character limits:

  • GSM alphabet: 160 characters per SMS (153 when concatenated)
  • Unicode: 70 characters per SMS (67 when concatenated)
  • Maximum 8 concatenated SMS parts allowed

Important: By default, without a specified strategy, your message will be considered commercial and must comply with authorized days/hours and include a valid unsubscribe mention (STOP SMS).

Authorizations:
ApiKey
Request Body schema: application/x-www-form-urlencoded
required
dest
required
string

Recipient phone number(s) in international format.

  • No need to prefix with "+" or "00"
  • National format (starting with "0") will use your account's default country prefix
  • For bulk sends, separate numbers with commas (max 5000 recommended)
  • For personalized sends, use format: number;var1;var2,number;var1;var2

ℹ️ Immediate sends with more than 500 grouped recipients or 100 personalized recipients will be processed asynchronously.

personnalise
integer
Default: 0
Enum: 0 1

Enable personalized messages per recipient.

When set to 1, use variables in your message (msg parameter) that will be replaced for each recipient.

Variable substitution:

  • %0% = recipient number (international format, e.g. 33600123456)
  • %1% to %9% = custom variables (up to 10 variables total)

Format for dest parameter:

number;var1;var2,number;var1;var2

Example request:

dest=33600000000;Jean;vehicule,33600123456;Paul;scooter
msg=Bonjour %1%, votre %2% est pret.
personnalise=1

Result:

  • To +33600000000: "Bonjour Jean, votre vehicule est pret."
  • To +33600123456: "Bonjour Paul, votre scooter est pret."

Special characters in variables:

  • , (comma) → %d44%
  • ; (semicolon) → %d59%

ℹ️ Maximum 500 recipients per request recommended.

msg
required
string

The message content to send.

  • Encoding must match the charset parameter
  • Character limits depend on coding parameter
  • Messages exceeding limits will be split into multiple SMS (up to 8 parts)

Important: Commercial messages must include a valid unsubscribe mention (STOP SMS).

mode
required
string
Enum: "Standard" "Expert" "Reponse"

Sending mode:

Value Description
Standard Displays a numeric shortcode (3-5 digits) as sender
Expert Allows custom sender name, e.g. a brand name (requires origine parameter)
Reponse Enables recipient replies (valid for 48h, charged to recipient). Replies are routed to the inbox available in the customer portal, or can be redirected to a callback URL.
strategy
integer
Enum: 1 2 3 4

Message type indicator for proper routing:

Value Type Description
1 Private Person-to-person communication. No commercial or automated messages. Max 50 recipients. Blacklist not checked.
2 Alert/Notification Alerts, proactive notifications, service/content delivery. No commercial messages. Max 50 recipients. Blacklist not checked.
3 Group (non-commercial) Non-commercial group communications. Global blacklist not checked, but private blacklist is checked.
4 Commercial Marketing/promotional messages. Blacklist checked. Must include unsubscribe option. Restricted hours (8h-20h, no Sundays/holidays).
origine
string <= 11 characters

Custom sender name or number (Expert mode only).

  • Maximum 15 digits or 11 alphanumeric characters
  • Must be pre-registered in your account's "Sender Management" section
  • If empty, uses your account's default sender
coding
string
Default: "default"
Enum: "default" "unicode" "auto"

Character encoding:

Value Description Characters per SMS Concatenated
default GSM 7-bit alphabet 160 153 (UDH 6) or 152 (UDH 7)
unicode Unicode 16-bit 70 67 (UDH 6) or 66 (UDH 7)
auto Automatic detection Depends on content -

ℹ️ Some GSM characters count as double: [ \ ] ^ { | } ~ €

charset
string
Default: "iso-8859-1"
Enum: "iso-8859-1" "iso-8859-15" "utf-8"

Input encoding of your request parameters.

Required if your data is not encoded in ISO-8859-1 (Latin1).

max_parts
integer [ 1 .. 8 ]
Default: 8

Maximum SMS parts for long messages.

If the message requires more parts, it will be truncated.

Recommended: Maximum 3 parts for best delivery rates.

date
string^\d{2}/\d{2}/\d{4}$

Scheduled send date in DD/MM/YYYY format.

  • Uses Paris timezone (Europe/Paris)
  • Must be used with heure parameter
  • Maximum 2 years in advance
  • Past dates result in immediate send
heure
string^\d{2}:\d{2}$

Scheduled send time in HH:MM format (24h).

  • Uses Paris timezone (Europe/Paris)
  • If date is empty, uses current date
  • Past times result in immediate send
id
integer
Default: 0
Enum: 0 1

Request message reference in response.

When set to 1, the API returns "OK" followed by the numeric reference(s).

Example response: OK 123456789012

callback
integer
Default: 0
Enum: 0 1

Enable delivery report callbacks.

When set to 1, delivery receipts are sent to your configured callback URL.

cvar
string

Custom variables to include in delivery report callbacks.

Used in conjunction with callback=1. These custom parameters are appended to your callback URL as GET parameters when delivery receipts are sent.

Example value (before encoding): mon_client=1+2=3&ma_campagne=456

ℹ️ The value 1+2=3 must be URL-encoded to 1%2B2%3D3.

Important: URL-encode the entire cvar value before sending to the API.

Final encoded parameter: cvar=mon_client%3D1%252B2%253D3%26ma_campagne%3D456

udh
integer
Default: 1
Enum: 0 1 2

User Data Header for message concatenation:

Value Description
0 Disabled. Each part received separately.
1 6-byte UDH (255 references). Default.
2 7-byte UDH (255² references).

ℹ️ Concatenation reduces available characters per SMS.

allow_vocal
integer
Default: 0
Enum: 0 1

Enable voice synthesis for landline numbers.

When set to 1, messages to French landlines (+33) are vocalized.

ℹ️ Only available in Standard and Expert modes.

validity
integer [ 5 .. 1440 ]

Message validity period in minutes.

After this period, if the message hasn't been delivered, the operator stops trying.

Default varies by operator (48-72 hours).

⚠️ Some operators may ignore this value.

uniq_period
integer [ 1 .. 24 ]

Duplicate prevention period in hours.

Prevents sending identical messages (same content + recipient) within the specified period.

⚠️ API returns "ERROR" for duplicate content.

day_min
integer [ 1 .. 7 ]

First allowed day of week for sending (1=Monday to 7=Sunday).

Must be used with day_max.

ℹ️ Ignored for scheduled sends.

day_max
integer [ 1 .. 7 ]

Last allowed day of week for sending (1=Monday to 7=Sunday).

Must be used with day_min.

hour_min
integer [ 0 .. 23 ]

First allowed hour for sending (0-23, Paris timezone).

Must be used with hour_max.

ℹ️ Ignored for scheduled sends.

hour_max
integer [ 0 .. 23 ]

Last allowed hour for sending (0-23, Paris timezone).

Must be used with hour_min.

Responses

Request samples 

curl --request POST \
	--url https://api.smsbox.pro/1.1/api.php \
	--header 'Authorization: App <APIKEY>' \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data 'dest=33600123456' \
	--data 'msg=Hello, this is a test message.' \
	--data 'mode=Standard' \
	--data 'strategy=4' \
	--data 'id=1'

Response samples

Content type
text/plain
Example
OK

Send to group

Send an SMS message to a predefined group of recipients.

The group must be created beforehand in your account's contact management section.

Usage: Add action=envoigroupe as a query parameter to the endpoint URL.

POST /1.1/api.php?action=envoigroupe
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "envoigroupe"

Action identifier. Must be set to envoigroupe to send to a group.

Request Body schema: application/x-www-form-urlencoded
required
groupe
required
integer

Group ID to send the message to.

Find the group ID in your account's contact group list.

msg
required
string

The message content to send.

  • Encoding must match the charset parameter
  • Character limits depend on coding parameter
  • Messages exceeding limits will be split into multiple SMS (up to 8 parts)

Important: Commercial messages must include a valid unsubscribe mention (STOP SMS).

mode
required
string
Enum: "Standard" "Expert" "Reponse"

Sending mode:

Value Description
Standard Displays a numeric shortcode (3-5 digits) as sender
Expert Allows custom sender name, e.g. a brand name (requires origine parameter)
Reponse Enables recipient replies (valid for 48h, charged to recipient). Replies are routed to the inbox available in the customer portal, or can be redirected to a callback URL.
strategy
integer
Enum: 1 2 3 4

Message type indicator for proper routing:

Value Type Description
1 Private Person-to-person communication. No commercial or automated messages. Max 50 recipients. Blacklist not checked.
2 Alert/Notification Alerts, proactive notifications, service/content delivery. No commercial messages. Max 50 recipients. Blacklist not checked.
3 Group (non-commercial) Non-commercial group communications. Global blacklist not checked, but private blacklist is checked.
4 Commercial Marketing/promotional messages. Blacklist checked. Must include unsubscribe option. Restricted hours (8h-20h, no Sundays/holidays).
origine
string <= 11 characters

Custom sender name or number (Expert mode only).

  • Maximum 15 digits or 11 alphanumeric characters
  • Must be pre-registered in your account's "Sender Management" section
  • If empty, uses your account's default sender
coding
string
Default: "default"
Enum: "default" "unicode" "auto"

Character encoding:

Value Description Characters per SMS Concatenated
default GSM 7-bit alphabet 160 153 (UDH 6) or 152 (UDH 7)
unicode Unicode 16-bit 70 67 (UDH 6) or 66 (UDH 7)
auto Automatic detection Depends on content -

ℹ️ Some GSM characters count as double: [ \ ] ^ { | } ~ €

charset
string
Default: "iso-8859-1"
Enum: "iso-8859-1" "iso-8859-15" "utf-8"

Input encoding of your request parameters.

Required if your data is not encoded in ISO-8859-1 (Latin1).

max_parts
integer [ 1 .. 8 ]
Default: 8

Maximum SMS parts for long messages.

If the message requires more parts, it will be truncated.

Recommended: Maximum 3 parts for best delivery rates.

date
string^\d{2}/\d{2}/\d{4}$

Scheduled send date in DD/MM/YYYY format.

  • Uses Paris timezone (Europe/Paris)
  • Must be used with heure parameter
  • Maximum 2 years in advance
  • Past dates result in immediate send
heure
string^\d{2}:\d{2}$

Scheduled send time in HH:MM format (24h).

  • Uses Paris timezone (Europe/Paris)
  • If date is empty, uses current date
  • Past times result in immediate send
id
integer
Default: 0
Enum: 0 1

Request message reference in response.

When set to 1, the API returns "OK" followed by the numeric reference(s).

Example response: OK 123456789012

callback
integer
Default: 0
Enum: 0 1

Enable delivery report callbacks.

When set to 1, delivery receipts are sent to your configured callback URL.

cvar
string

Custom variables to include in delivery report callbacks.

Used in conjunction with callback=1. These custom parameters are appended to your callback URL as GET parameters when delivery receipts are sent.

Example value (before encoding): mon_client=1+2=3&ma_campagne=456

ℹ️ The value 1+2=3 must be URL-encoded to 1%2B2%3D3.

Important: URL-encode the entire cvar value before sending to the API.

Final encoded parameter: cvar=mon_client%3D1%252B2%253D3%26ma_campagne%3D456

udh
integer
Default: 1
Enum: 0 1 2

User Data Header for message concatenation:

Value Description
0 Disabled. Each part received separately.
1 6-byte UDH (255 references). Default.
2 7-byte UDH (255² references).

ℹ️ Concatenation reduces available characters per SMS.

allow_vocal
integer
Default: 0
Enum: 0 1

Enable voice synthesis for landline numbers.

When set to 1, messages to French landlines (+33) are vocalized.

ℹ️ Only available in Standard and Expert modes.

validity
integer [ 5 .. 1440 ]

Message validity period in minutes.

After this period, if the message hasn't been delivered, the operator stops trying.

Default varies by operator (48-72 hours).

⚠️ Some operators may ignore this value.

uniq_period
integer [ 1 .. 24 ]

Duplicate prevention period in hours.

Prevents sending identical messages (same content + recipient) within the specified period.

⚠️ API returns "ERROR" for duplicate content.

day_min
integer [ 1 .. 7 ]

First allowed day of week for sending (1=Monday to 7=Sunday).

Must be used with day_max.

ℹ️ Ignored for scheduled sends.

day_max
integer [ 1 .. 7 ]

Last allowed day of week for sending (1=Monday to 7=Sunday).

Must be used with day_min.

hour_min
integer [ 0 .. 23 ]

First allowed hour for sending (0-23, Paris timezone).

Must be used with hour_max.

ℹ️ Ignored for scheduled sends.

hour_max
integer [ 0 .. 23 ]

Last allowed hour for sending (0-23, Paris timezone).

Must be used with hour_min.

Responses

Request samples 

curl --request POST \
	--url 'https://api.smsbox.pro/1.1/api.php?action=envoigroupe' \
	--header 'Authorization: App <APIKEY>' \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data 'groupe=12345' \
	--data 'msg=Hello group members, this is a test message.' \
	--data 'mode=Standard' \
	--data 'strategy=4'

Response samples

Content type
text/plain
Example
OK

Sandbox

Use sandbox phone numbers starting with +999 to test your integration with simulated delivery reports at reduced cost (0.05 credit per SMS).

Rules:

  • Destination number must start with +999
  • Total length: 7 to 16 digits (including the "999" prefix)

Simulated delivery statuses based on prefix:

Prefix Status Flow Final Status
+9990XXXXXX 9 → 0 Received
+9991XXXXXX 9 → 1 Transmission failure
+9992XXXXXX 9 → 2 Rejected
+9993XXXXXX 9 → 3 Inactive mobile
+9994XXXXXX 9 → 4 Mobile not responding
+9995XXXXXX 9 → 5 Reception error
+9996XXXXXX 9 → 6 Saturated mobile
+9997XXXXXX 9 → 7 Unknown number
+9998XXXXXX 9 → 8 Non-routable
+9999XXXXXX → -3 Refunded

Sandbox numbers require callback=1 to receive simulated delivery reports.

Senders

Manage your sender IDs (names displayed to recipients).

Senders must be registered in your account's "Sender Management" section before use.

Get default sender

Retrieve your default sender ID.

Usage: Add action=emetteur as a query parameter to the endpoint URL.

POST /1.1/api.php?action=emetteur
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "emetteur"

Action identifier. Must be set to emetteur.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=emetteur" \
  -H "Authorization: App YOUR_API_KEY"

Response samples

Content type
text/plain
MyCompany

List senders

Retrieve all registered sender IDs.

Usage: Add action=emetteur&do=list as query parameters to the endpoint URL.

POST /1.1/api.php?action=emetteur&do=list
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "emetteur"

Action identifier. Must be set to emetteur.

do
required
string
Value: "list"

Operation type. Must be set to list.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=emetteur&do=list" \
  -H "Authorization: App YOUR_API_KEY"

Response samples

Content type
text/plain
MyCompany
MyBrand
Alerts

Set default sender

Set your default sender ID.

Usage: Add action=emetteur&do=set as query parameters to the endpoint URL.

POST /1.1/api.php?action=emetteur&do=set
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "emetteur"

Action identifier. Must be set to emetteur.

do
required
string
Value: "set"

Operation type. Must be set to set.

Request Body schema: application/x-www-form-urlencoded
required
emetteur
required
string <= 11 characters

Sender ID to set as default.

Must be pre-registered in your account's "Sender Management" section.

Maximum 15 digits or 11 alphanumeric characters.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=emetteur&do=set" \
  -H "Authorization: App YOUR_API_KEY" \
  -d "emetteur=MyCompany"

Response samples

Content type
text/plain
Example
MyCompany

Groups

Manage contact groups for bulk messaging.

List groups

Retrieve all contact groups.

Usage: Add action=groupes as a query parameter to the endpoint URL.

POST /1.1/api.php?action=groupes

Add hide_numbers=1 to get only the contact count instead of phone numbers.

Authorizations:
ApiKey
query Parameters
action
required
string
Value: "groupes"

Action identifier. Must be set to groupes.

hide_numbers
integer
Enum: 0 1

Set to 1 to return contact count instead of phone numbers.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=groupes" \
  -H "Authorization: App YOUR_API_KEY"

Response samples

Content type
text/plain
Example
1;VIP Clients;33600123456,33600789012
2;Staff;33600111111

Add group

Create a new contact group.

Usage: Add action=groupes&do=add as query parameters to the endpoint URL.

POST /1.1/api.php?action=groupes&do=add
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "groupes"

Action identifier. Must be set to groupes.

do
required
string
Value: "add"

Operation type. Must be set to add.

Request Body schema: application/x-www-form-urlencoded
required
nom
required
string

Group name.

num
required
string

Phone numbers to add to the group, separated by commas.

Numbers must be in international format (without + or 00 prefix).

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=groupes&do=add" \
  -H "Authorization: App YOUR_API_KEY" \
  -d "nom=VIP%20Clients&num=33600123456,33600789012"

Response samples

Content type
text/plain
Example
OK

Edit group

Edit an existing contact group.

Usage: Add action=groupes&do=edit as query parameters to the endpoint URL.

POST /1.1/api.php?action=groupes&do=edit
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "groupes"

Action identifier. Must be set to groupes.

do
required
string
Value: "edit"

Operation type. Must be set to edit.

Request Body schema: application/x-www-form-urlencoded
required
id
required
integer

Group ID to edit.

nom
required
string

New group name.

num
required
string

New phone numbers for the group (replaces existing numbers).

Numbers separated by commas in international format.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=groupes&do=edit" \
  -H "Authorization: App YOUR_API_KEY" \
  -d "id=123&nom=Premium%20Clients&num=33600123456,33600789012"

Response samples

Content type
text/plain
Example
OK

Add numbers to group

Add phone numbers to an existing group.

Usage: Add action=groupes&do=add_numbers as query parameters to the endpoint URL.

POST /1.1/api.php?action=groupes&do=add_numbers
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "groupes"

Action identifier. Must be set to groupes.

do
required
string
Value: "add_numbers"

Operation type. Must be set to add_numbers.

Request Body schema: application/x-www-form-urlencoded
required
id
required
integer

Group ID to add numbers to.

num
required
string

Phone numbers to add to the group, separated by commas.

Numbers must be in international format (without + or 00 prefix).

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=groupes&do=add_numbers" \
  -H "Authorization: App YOUR_API_KEY" \
  -d "id=123&num=33600222222,33600333333"

Response samples

Content type
text/plain
Example
OK

Delete group

Delete a contact group.

Usage: Add action=groupes&do=del as query parameters to the endpoint URL.

POST /1.1/api.php?action=groupes&do=del
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "groupes"

Action identifier. Must be set to groupes.

do
required
string
Value: "del"

Operation type. Must be set to del.

Request Body schema: application/x-www-form-urlencoded
required
id
required
integer

Group ID to delete.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=groupes&do=del" \
  -H "Authorization: App YOUR_API_KEY" \
  -d "id=123"

Response samples

Content type
text/plain
Example
OK

History

Retrieve your sent message history.

Get history count

Get the total number of records in your message history.

Usage: Add action=historique as a query parameter to the endpoint URL.

POST /1.1/api.php?action=historique
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "historique"

Action identifier. Must be set to historique.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=historique" \
  -H "Authorization: App YOUR_API_KEY"

Response samples

Content type
text/plain
HISTORIQUE 123

List history

Retrieve sent message history.

Usage: Add action=historique as a query parameter to the endpoint URL.

POST /1.1/api.php?action=historique

Response format (CSV):

  • Date and time (Paris timezone, format: dd/MM/yyyy HH:mm:ss)
  • Reference (only if showref=1)
  • Recipient number (international format)
  • Sender
  • Send type (0=Classic, 1=Flash, 2=Other)
  • Always "1"
  • Delivery status code

Maximum records: 5000 per request (50000 with date filters).

Authorizations:
ApiKey
query Parameters
action
required
string
Value: "historique"

Action identifier. Must be set to historique.

Request Body schema: application/x-www-form-urlencoded
optional
from
integer >= 0

Starting record index for extraction.

Default: 0 (most recent record).

nb
integer [ 1 .. 5000 ]

Number of records to retrieve.

Default: 10, Maximum: 5000.

date_from
string^\d{4}-\d{2}-\d{2}$

Start date for extraction (inclusive).

Format: YYYY-MM-DD.

Maximum 50000 records will be returned when using date filters.

date_to
string^\d{4}-\d{2}-\d{2}$

End date for extraction (inclusive).

Format: YYYY-MM-DD.

Defaults to current date if date_from is specified.

id
string

Message reference to retrieve.

Use this to get history for a specific message.

msisdn
string

Recipient phone number to filter by.

International format (without + or 00 prefix).

showref
integer
Enum: 0 1

Include message reference in response.

Set to 1 to add the reference column to the output.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=historique" \
  -H "Authorization: App YOUR_API_KEY" \
  -d "from=0&nb=20&showref=1"

Response samples

Content type
text/plain
Example
20/10/2024 18:15:00;33600123456;MyCompany;0;1;0

Scheduled

Manage scheduled (deferred) messages.

Get scheduled count

Get the total number of scheduled (deferred) messages.

Usage: Add action=differes as a query parameter to the endpoint URL.

GET /1.1/api.php?action=differes
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "differes"

Action identifier. Must be set to differes.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=differes" \
  -H "Authorization: App YOUR_API_KEY"

Response samples

Content type
text/plain
DIFFERES 50

List scheduled

Retrieve scheduled (deferred) messages.

Usage: Add action=differes as a query parameter to the endpoint URL.

POST /1.1/api.php?action=differes

Response format (CSV):

  • Record ID
  • Reference (only if showref=1)
  • Recipient number (international format)
  • Empty value
  • Always "0"
  • Scheduled date and time (Paris timezone, format: dd/MM/yyyy HH:mm:ss)
  • Message content

Maximum records: 5000 per request.

Authorizations:
ApiKey
query Parameters
action
required
string
Value: "differes"

Action identifier. Must be set to differes.

Request Body schema: application/x-www-form-urlencoded
optional
from
integer >= 0

Starting record index for extraction.

Default: 0 (most recent record).

nb
integer [ 1 .. 5000 ]

Number of records to retrieve.

Default: 10, Maximum: 5000.

showref
integer
Enum: 0 1

Include message reference in response.

Set to 1 to add the reference column to the output.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=differes" \
  -H "Authorization: App YOUR_API_KEY" \
  -d "from=0&nb=20&showref=1"

Response samples

Content type
text/plain
6408047;123456789012;33612345678;;0;12/11/2024 16:30:00;Your appointment is confirmed...

Delete scheduled

Delete a scheduled (deferred) message.

Usage: Add action=differes&do=del as query parameters to the endpoint URL.

POST /1.1/api.php?action=differes&do=del
Authorizations:
ApiKey
query Parameters
action
required
string
Value: "differes"

Action identifier. Must be set to differes.

do
required
string
Value: "del"

Operation type. Must be set to del.

Request Body schema: application/x-www-form-urlencoded
required
ref
required
string

Message reference of the scheduled message to delete.

You can retrieve this reference by adding id=1 parameter when sending the original SMS.

Responses

Request samples 

curl -X POST "https://api.smsbox.pro/1.1/api.php?action=differes&do=del" \
  -H "Authorization: App YOUR_API_KEY" \
  -d "ref=123456789012"

Response samples

Content type
text/plain
Example
OK

Webhooks

Delivery Reports (Callbacks)

To receive delivery reports, add the callback=1 parameter to your requests and configure your callback URL in your Customer Area under My settings > My preferences > Callback URLs.

If you are using a firewall, make sure to allow these IPv4 addresses:

  • 37.59.198.135
  • 178.33.185.51
  • 54.36.93.79
  • 54.36.93.80
  • 62.4.31.47
  • 62.4.31.48

Delivery Report Webhook

Delivery reports are sent to your callback URL when using callback=1 in your send request.

Prerequisites: Configure your callback URL in your Customer Area under My settings > My preferences > Callback URLs (field "Delivery reports (API)").

Method: GET

Example request to your server:

GET https://your-server.com/callback?numero=33600123456&reference=123456789&accuse=0&ts=1705326600

How to respond: Return HTTP 200 with body OK to confirm successful processing. If processing fails, return ERROR with any non-200 status code.

Automatic retries: Failed callbacks are retried every 15 minutes for up to 12 hours.

⚠️ Warning: HTTP codes 401, 403, and 404 are considered permanent failures and are not retried.

Performance requirement: Respond within 3 seconds. We recommend storing the data immediately and processing it asynchronously. If your script is slow, our system waits before sending the next callback.

Request Body schema: application/x-www-form-urlencoded
numero
string

Recipient's phone number in international format.

reference
string

Internal reference of the sent message.

accuse
integer

Delivery receipt status code.

SMS status codes:

Code Status Description
-3 Reimbursed Delivery failed, credit refunded
-1 Unknown Unable to determine delivery status
0 Received Message delivered to recipient
1 Failure Delivery failed, reason unknown
2 Rejected Content blocked, spam filtered, or parental lock
3 Inactive Recipient phone is off or has no signal
4 Not responding Operator network issues
5 Reception error Recipient could not receive the message
6 Saturated Recipient phone memory full
7 Unknown number Invalid or blocked phone number
8 Non-routable Unknown prefix or routing error
9 Transmitted Accepted by operator, delivery in progress
10 Sent Delivery status not available for this mode

Vocalized SMS status codes:

Code Status Description
30 Call in progress Calling recipient
31 Picked up Line has been picked up and then hung up
32 Listening accepted Message listening has been accepted by pressing a key
33 Message listened The message has been entirely listened
34 Listening confirmed Message listening has been confirmed by pressing a key
35 Listening refused Message listening has been refused by pressing a key
36 Not picked up Line has not been picked up
37 No response Maximum call time to press a key after picking up has been reached
38 No dialling tone Call failed
39 Waiting for retry A new call will be made
ts
integer

Unix (POSIX) timestamp of the status update (Paris time).

Responses

Incoming Message (Reply) Webhook

Incoming SMS received on your keyword (shared number), dedicated number, or in response to messages sent via Response mode.

Prerequisites: Configure your callback URL in your Customer Area under My settings > My preferences > Callback URLs (field "SMS-MO / STOP").

Method: GET

Example request to your server:

GET https://your-server.com/callback?modem=33XXXXXXXXX&numero=33600123456&reference=12345678&ts=1705326600&charset=ISO-8859-1&message=Hello+world

How to respond: Return HTTP 200 with body OK to confirm successful processing. If processing fails, return ERROR with any non-200 status code.

Automatic retries: Failed callbacks are retried every 15 minutes for up to 12 hours.

⚠️ Warning: HTTP codes 401, 403, and 404 are considered permanent failures and are not retried.

Performance requirement: Respond within 3 seconds. We recommend storing the data immediately and processing it asynchronously. If your script is slow, our system waits before sending the next callback.

Request Body schema: application/x-www-form-urlencoded
modem
string

Number that received the message from your correspondent. Blank if not applicable.

numero
string

Phone number of the sender (your correspondent) in international format.

reference
string

Internal reference of the received message.

⚠️ This reference does not match the reference of the sent message to which the recipient may have replied.

ts
integer

Unix (POSIX) timestamp of message reception (Paris time).

charset
string

Character set used for encoding the message content.

keyword
string

Keyword used for reception (shared numbers only).

message
string

Content of the message received from your correspondent.

link_reference
string

Reference of the last message sent to this phone number from your account.

Warning: This is not necessarily the message the person wanted to reply to if you have sent them more than one.

Responses