| Managing mailing listsActions with mailing listsTo create a mailing list, you need to call the GET or POST address method:
https://smscentre.com/sys/jobs.php?add=1&login=<login>&psw=<password>&name=<name>&phones=<phones>&mes=<message>
To delete a mailing list, call the GET or POST address method:
https://smscentre.com/sys/jobs.php?del=1&login=<login>&psw=<password>&id=<id>
To disable a mailing list that is waiting to be sent, you must call the GET or POST address method:
https://smscentre.com/sys/jobs.php?cancel=1&login=<login>&psw=<password>&id=<id>
To get information about a particular mailing list, you need to call the GET or POST address method:
https://smscentre.com/sys/jobs.php?get=1&login=<login>&psw=<password>&id=<id>
To receive mailing list, you need to call method GET or POST address:
https://smscentre.com/sys/jobs.php?get_all=1&login=<login>&psw=<password>
Description of the parameters passed to the Server when creating a mailing list (any of the additional parameters is applied to each message in the mailing list; to work with e-mail newsletters, you must pass the additional parameter mail=1 in the request):
| Option | The value
|
|---|
| login | Customer Login.
|
|---|
| psw | Client Password (you can add or change it on this page).
|
|---|
| apikey | A special API key used for simplified authorization instead of the "login+password" pair (you can create it on this page).
|
|---|
| name | Mailing list name.
|
|---|
| phones | The number or comma-separated or semicolon-separated list of mobile phone numbers in international format
to which the message is sent. Numbers can be passed without the "+ " sign.
If the number is passed without the " + " sign, it can be corrected by automatic formatting
and converted to the correct international format. Thus, some
errors when entering phone numbers can be corrected automatically.
To disable auto-correction, pass the number with the "+ " sign.".
You can also send a message to a group of numbersby specifying a special code " G<νξμεπ γπσοοϋ>".
The message will be sent to all numbers belonging to this group. For an e-mail message, a list of recipients' e-mail addresses is transmitted. For telegram, it is possible to specify the subscriber's nickname or ID as the recipient of the message in the form of #ID.
|
|---|
| mes | The text of the message being sent. The maximum size is 1000 characters. If
necessary, the message will be divided into several SMS messages sent to the subscriber and paid separately. Size of one
SMS 160 characters in Latin or 70 characters in Cyrillic. When splitting a message into multiple SMS
messages, a header is added to each part to combine the parts into a single message on the recipient's phone, and the maximum length becomes
67 for Cyrillic and 153 for Latin letters. You can add comments to the message text
that are intended for the sender to view the history in the personal account.
|
|---|
| Additional options
|
|---|
| sender | The sender's name displayed on the recipient's phone.
English letters, numbers, spaces, and some characters are allowed. Length 11 characters or 15 digits.
All names are registered in your personal account on this page.
|
|---|
| sender2 | This parameter is used as the sender's name when auto-replaying via SMS in case of non-delivery of messages via the original sending option..
|
|---|
| translit | A sign that the message you want to translate in translit.
0 (default) do not translate into transliteration.
1 translate to translit as " translate".
2 translate into transliteration as " mpaHc/Ium".
|
|---|
| tinyurl | Automatically shorten links in messages. Allows you to replace links in
the message text with short ones to reduce the length, as well as to track the number of clicks on
this page.
0 (default) leave links in the message text without changes.
1 shorten links.
|
|---|
| time | The time of sending the SMS message to the subscriber.
Formats:
- DDMMYYhhmm or DD.MM.YY hh: mm.
- h1-h2. Sets the time range in hours. If the current time is less than h1, the SMS message
will be sent to the subscriber when the time h1 occurs, if the current time falls in the interval from h1 to h2,
that message will be sent immediately, otherwise the message will be sent the next day when
the h1 time is reached. This function, for example, is useful in order to prevent subscribers from receiving SMS messages
at night.
- 0ts, where ts is timestamp, the time in seconds since January 1, 1970.
- +m. Sets the relative time offset from the current time in minutes. The + character must be encoded as %2B in the http request.
If time = 0 or the time already elapsed is specified, the message will be sent immediately.
|
|---|
| rpt | Determines the frequency of sending the newly created mailing list.
0 (default) manually.
1 every hour.
2 every day.
3 every working day.
4 every weekend.
5 every week.
6 every month.
7 every year.
|
|---|
| rptn | Sets the maximum number of repetitions for a deferred periodic distribution.
|
|---|
| tz | The time zone in which the time parameter is set. It is indicated relative to Moscow time.
The tz parameter can be either positive or negative. If tz is equal to 0, the Moscow time zone will be used
, if the tz parameter is not set, the time zone will be taken from the Client settings.
|
|---|
| period | The period of time during which you need to send the newsletter. Represents a number
in the range from 0.1 to 720 hours. Used in conjunction with the freq parameter. This parameter allows you to stretch the mailing list in
time for the gradual receipt of SMS messages by subscribers.
|
|---|
| freq | The interval or frequency at which to send an SMS message to the next group of numbers. The number
of numbers in the group is calculated automatically based on the period and freq parameters. Set in the interval from 1 to 1440 minutes.
Without the period parameter, the freq parameter is ignored.
|
|---|
| flash | Indicates whether a Flash message is displayed immediately on the phone screen.
0 (default) normal message.
1 Flash message.
|
|---|
| bin | Binary message flag.
0 (default) normal message.
1 binary message. In an http request, it must be encoded using the urlencode function.
2 binary message, represented as a hexadecimal string (hex).
The binary message is passed along with the UDH header at the beginning in the mes parameter, in which the first byte specifies the length of the header.
To send a binary message without a UDH header, specify a null byte at the beginning of the message (00 in hex).
To be able to pass the pid and dcs parameters, you need to add a special combination
"\n~~~\n" (line feed, 3 tilde characters, and again line feed) to the end of the binary message, and then the text "pid: value1, dcs: value2" with the exact preservation
of spaces.
|
|---|
| push | A sign of a wap-push message, with which you can send an Internet link to your phone.
0 (default) normal message.
1 wap-push message. In the mes parameter, you must pass the link and title through a line feed.
|
|---|
| hlr | A sign of the HLR-request for information about the number from the operator's database without sending real SMS.
0 (default) normal message.
1 HLR request. An HLR request will be executed for each phone number in the list. The mes parameter is not used.
|
|---|
| ping | Indicates a special SMS that is not displayed in the phone to check the numbers for availability in real time by the delivery status.
0 (default) normal message.
1 ping-sms. A Ping SMS will be sent to each phone number in the list.
The mes parameter is not used.
|
|---|
| mms | A feature of an MMS message that can be used to transmit text (txt), images in various formats (jpg, gif, png),
music (wav, amr, mp3, mid), and video (mp4, 3gp). The files are passed in the body of the http request.
0 (default) normal message.
1 An MMS message. An MMS will be sent to each phone number in the list.
|
|---|
| mail | The flag of the e-mail message. The files attached to the message are passed by the POST method in the body of the http request..
0 (default) normal message.
1 e-mail message.
|
|---|
| soc | A sign of a soc message sent to users of the social networks "Odnoklassniki", "VKontakte" or to users of " Mail.Ru Agent".
0 (default) normal message.
1 soc message.
|
|---|
| viber | Flag of the viber message sent to users of the Viber messenger.
0 (default) normal message.
1 viber message.
|
|---|
| whatsapp | A sign of a whatsapp message sent to WhatsApp messenger users.
0 (default) normal message.
1 whatsapp message.
|
|---|
| tg | If the value of this parameter is set to 1, a telegram message will be sent with the confirmation code passed in the mes parameter.
|
|---|
| bot | Bot's name to for sending a message in the format "@botname_bot".
|
|---|
| smsreq | When this parameter is specified, the system will not display the text of the message sent to the user and display a warning about the need to confirm the phone number if more than smsreq days have passed since the last confirmation. Range of values from 10 to 999.
|
|---|
| fileurl | The full http address of the file to upload and transmit in the message. The minimum file size is 101 bytes.
|
|---|
| mes2 | This parameter sets the message option to be sent via SMS in the automatic repeat mode in case of non-delivery to alternative routes, for example, sending to messengers. To enable automatic replay, you must additionally pass the fl[5] flagequal to 1 in the request.
|
|---|
| call | Indicates a voice message. When forming a voice message, you can send both text and attach files.
Files added to the message must be passed by the POST method in the body of the http request..
0 (default) normal message.
1 voice message.
|
|---|
| voice | The voice used for voicing the text (only for voice messages).
m male voice.
m2 male voice 2.
m3 (default) male voice 3.
m4 male voice 4.
w a woman's voice.
w2 female voice 2.
w3 female voice 3.
w4 female voice 4.
When sending messages, it is also possible to specify the language of the text in the form: "m,en", "w,fr", "w,de", etc..
|
|---|
| param | Comma-separated list of parameters for a voice message in the format " param=w, i,n".
Here:
- w the waiting time for the caller to pick up the phone after the call starts, in seconds. If the subscriber does not pick up the phone within the specified time,
the call will be repeated with the error "the subscriber is busy". The operating range of the parameter values is from 10 to 35, but you can specify an interval from 0 to 99
(if the value is less than 10, it will be reduced to 10, similarly for the upper bound).
- i repeat interval, that is, the time interval after which the call will be repeated (in seconds). The operating range of the parameter
is from 10 to 3600 (if the value is less than 10, it will be reduced to 10).
- n the total number of dial-up attempts. Operating range of values from 1 to 9 (0 will be reduced to 1).
When specifying the value of any parameter other than the possible ones, the default values of all parameters will be used (n = 8, w = 25, i from 3 to 14 seconds incrementally), except for advertising messages.
|
|---|
| subj | The subject of the MMS or e-mail message. When sending an e-mail, you must specify the subject, text, and address of the sender. For MMS
, it is mandatory to specify the subject or text. If you do not specify the subject of the MMS, then the sender's name, passed in the request or
used by default, will be used as it.
|
|---|
| charset | The encoding of the transmitted message, if used other than the
default encoding of windows-1251. Options: utf-8 and koi8-r.
|
|---|
| cost | Indicates whether you need to receive the cost of the mailing list.
0 (default) normal sending.
1
add the cost of mailing to the response.
|
|---|
| fmt | Format of the server response about successful sending.
0 (by default) as a string (OK - 1 SMS, ID - 1234).
1 return the response in the form of numbers: ID and number of SMS separated by commas (1234,1), with cost = 2, another comma-separated cost
(1234,1,1.40), with cost = 3, another new Customer balance (1234,1,1.40,100.50), with cost = 1, the cost and quantity
Comma separated SMS (1.40,1).
2 response in xml format.
3 response in json format.
|
|---|
| list | A list of phone numbers and their corresponding messages, separated by a colon or semicolon, and
presented as:
phones1:mes1
phones2:mes2
...
Lines are separated by a newline character (%0A). As phones, you can specify multiple phone numbers separated by
commas. If you want to pass a newline character in the mes message, specify it with \n. If it is not possible to correct the text of a multi-line message, it is possible to enable a special mode for transmitting this type of message. To do this, you must additionally pass the nl parameterequal to 1 in the request.
If it is necessary to transmit different names of senders (and possibly different time zones of subscribers (works only for requests in which the time parameter is represented as DDMMYYhhmm or DD.MM.YY hh:mm)) The following transmission format can be used for different messages:
sender1,tz1|phones1:mes1
sender2,tz2|phones2:mes2
...
In this case, the tz parameter is optional.
The list parameter allows you to send multiple messages with different messages to multiple phones.
an http request. The messages in the request are assigned a single identifier. The entire parameter must be encoded using the
urlencode function.
|
|---|
| tpl | ID of the template to be used as the message text. To use the template
, the mes parameter must be empty.
|
|---|
| valid | The "life" period of the SMS message. Specifies the time during which the operator will attempt to deliver
the message to the subscriber. Range from 1 to 24 hours. It is also possible to transmit the time in the hh:mm format in the range from 00:01 to 24:00.
|
|---|
The required parameters are login, psw, name, phones and mes or login, psw, name and list.
Description of the parameters passed to the Server when deleting, disabling, or receiving the mailing list:
| Option | The value
|
|---|
| login | Customer Login.
|
|---|
| psw | Client Password (you can add or change it on this page).
|
|---|
| id | ID of the mailing list. Returned by the Server after creation and used for further identification of the mailing list.
|
|---|
| Additional options
|
|---|
| start | The date from which you want to receive the mailing list. If this parameter is omitted, it returns the mailing list for the last 2 months, but no more than 10. It is used in conjunction with the get_all parameter. Format: 'dd.mm.yyyy'.
|
|---|
| end | The date before which you want to receive the mailing list. If this parameter is omitted, the mailing list is returned up to the current date, but no more than 10. It is used in conjunction with the get_all parameter. Format: 'dd.mm.yyyy'.
|
|---|
Required parameters are login, psw, and id.
After receiving and processing the data, the Server returns a confirmation to the Client indicating the result of processing.
All parameters that contain special characters (plus, space, etc.) must be encoded using the urlencode function to be passed in an HTTP request..
Mailing. Server response and error codes
The server sends the response as a string:
If an error occurred, the response will be one of the following:
When fmt = 0:
- ERROR = N (description) for 1,2,3,4,5,9 errors.
When fmt = 1:
- 0,-N for errors 1,2,3,4,5,9.
When fmt = 2:
- For 1 errors,2,3,4,5,9:
<result>
<error>description</error>
<error_code>N</error_code>
</result> |
When fmt = 3:
- For 1 errors,2,3,4,5,9:
{
"error": "description",
"error_code": N
} |
N error number, can take the following values:
| The value | Description
|
|---|
| 1 | Error in parameters.
|
|---|
| 2 | Invalid username or password. Also occurs when trying to send a message from an IP address that is not included in the list of allowed by the Client (if such a list was previously configured by the Client).
|
|---|
| 3 | Error saving a record.
|
|---|
| 4 | IP address is temporarily blocked due to frequent errors in the queries. read More
|
|---|
| 5 | Invalid date format.
|
|---|
| 9 | Sending more than one identical request for actions with mailing lists within a minute.
This error also occurs when you try to send fifteen or more requests simultaneously from different connections under the same username (too many concurrent requests).
|
|---|
If the request is processed successfully, a string of the following format is returned:
When creating a mailing list:
- when cost = 0 and fmt = 0: OK, ID - <id>
- when cost = 1 and fmt = 0: OK, ID - <id>, COST - <cost>
- when cost = 0 and fmt = 1: <id>
- when cost = 1 and fmt = 1: <id>,<cost>
- when cost = 0 and fmt = 2:
<result>
<id>id</id>
</result> |
- when cost = 1 and fmt = 2:
<result>
<id>id</id>
<cost>cost</cost>
</result> |
- when cost = 0 and fmt = 3:
- when cost = 1 and fmt = 3:
{
"id": <id>,
"cost": "<cost>"
} |
When you disable or delete a mailing list:
- when fmt = 0,1: OK
- when fmt = 2:
- when fmt = 3:
When receiving information about a specific mailing list (when mail=1, the "phones" parameter is replaced with " emails"):
- when fmt = 0: <id>|<name>|<subject>|<repeat_send>|<repeat_cnt>|<created>|<changed>|<need_date>|<last_sent>|<phones>|<message>|<format>|<validity>|<period>|<frequency>|<status>|<sender_id>
- when fmt = 1: <id>;<name>;<subject>;<repeat_send>;<repeat_cnt>;<created>;<changed>;<need_date>;<last_sent>;<phones>;<message>;<format>;<validity>;<period>;<frequency>;<status>;<sender_id>
- when fmt = 2:
<job>
<id>id</id>
<name>name</name>
<subject>subject</subject>
<repeat_send>repeat_send</repeat_send>
<repeat_cnt>repeat_cnt</repeat_cnt>
<created>created</created>
<changed>changed</changed>
<need_date>need_date</need_date>
<last_sent>last_sent</last_sent>
<phones>phones</phones>
<message>message</message>
<format>format</format>
<validity>validity</validity>
<period>period</period>
<frequency>frequency</frequency>
<status>status</status>
<sender_id>sender_id</sender_id>
</job> |
- when fmt = 3:
[
{
"id": <id>,
"name": "<name>",
"subject": "<subject>",
"repeat_send": <repeat_send>,
"repeat_cnt": <repeat_cnt>,
"created": "<created>",
"changed": "<changed>",
"need_date": "<need_date>",
"last_sent": "<last_sent>",
"phones": "<phones>",
"message": "<message>",
"format": <format>,
"validity": <validity>,
"period": "<period>",
"frequency": <frequency>,
"status": <status>,
"cost": "<cost>",
"sms_sent": <sms_sent>,
"sms_ok": <sms_ok>,
"sender_id": "<sender_id>"
}
] |
When receiving a mailing list (when mail=1, the "phones" parameter is replaced with " emails"):
- when fmt = 0: <id>|<name>|<changed>|<need_date>|<last_sent>|<phones>|<message>|<phones_cnt>|<cost>|<status>|<sender_id>|<format>
- when fmt = 1: <id>;<name>;<changed>;<need_date>;<last_sent>;<phones>;<message>;<phones_cnt>;<cost>;<status>;<sender_id>;<format>
- when fmt = 2:
<sms_jobs>
<job>
<id>id</id>
<name>name</name>
<changed>changed</changed>
<need_date>need_date</need_date>
<last_sent>last_sent</last_sent>
<phones>phones</phones>
<message>message</message>
<phones_cnt>phones_cnt</phones_cnt>
<cost>cost</cost>
<status>status</status>
<sender_id>sender_id</sender_id>
<format>format</format>
</job>
...
</sms_jobs>
|
- when fmt = 3:
[
{
"id": <id>,
"name": "<name>",
"changed": "<changed>",
"need_date": "<need_date>",
"last_sent": "<last_sent>",
"phones": "<phones>",
"message": "<message>",
"phones_cnt": <phones_cnt>,
"cost": "<cost>",
"status": <status>,
"sender_id": "<sender_id>",
"format": <format>,
"sms_sent": <sms_sent>,
"sms_ok": <sms_ok>
},
...
] |
Where:
<id> the distribution ID sent by the Client or assigned by the Server automatically.
<name> mailing list name.
<subject> subject (for e-mail newsletters).
<repeat_send> repeat period.
<repeat_cnt> the number of repetitions of the mailing list.
<created> mailing list creation date.
<changed> date of mailing list change.
<need_date> scheduled date of dispatch.
<last_sent> last sent date.
<phones> (<emails>) list of phone numbers (e-mail addresses) of message recipients.
<message> the text of the message.
<format> message format.
<validity> "lifetime" of the message.
<period> message sending interval.
<frequency> frequency of sending messages.
<status> mailing list status.
<sender_id> sender ID.
<phones_cnt> number of recipients.
<cost> cost of sending.
<sms_sent> number of messages sent.
<sms_ok> number of messages delivered.Examples of sending operationsExamples:
Creating an SMS mailing list:
https://smscentre.com/sys/jobs.php?add=1&login=alex&psw=123&phones=79999999999&name=Privet&mes=Hello!
Creating a mailing list with a voice message:
https://smscentre.com/sys/jobs.php?add=1&login=alex&psw=1234567890&phones=79999999999&call=1&voice=w2&name=Privet&mes=Hello!
Create a mailing list with an e-mail message to the address "alex@mysite.com" with the subject "Hi" and text "Hello!" from the sender "alex2@mysite2.com"
and the title of the mailing "Privet":
https://smscentre.com/sys/jobs.php?add=1&login=alex&psw=123&phones=alex%40mysite.com&mail=1&name=Privet&mes=Hello!&subj=Hi&sender=alex2%40mysite2.com
Creating a Viber mailing list with macros and auto-repeat via SMS (the text of the SMS is different from the text of the Viber message) to several numbers (the message texts must be encoded using the urlencode function):
https://smscentre.com/sys/jobs.php?add=1&login=alex&psw=123&phones=79999999999,78888888888&name=rassilka1&mes={Name}, this is a Viber message&mes2=This is an SMS for {Name}&sender=MyViber&fl[5]=1&viber=1
Deleting a created mailing list with an id equal to 701:
https://smscentre.com/sys/jobs.php?del=1&login=alex&psw=123&id=701
Disable deferred mailing with id equal to 701:
https://smscentre.com/sys/jobs.php?cancel=1&login=alex&psw=123&id=701 |
MANAGING MAILING LISTS
