This method is used to schedule or immediately start sending email or SMS messages. The same message can be sent several times, but the moments of sending should have an interval of at least an hour.
This method is used to send the already created messages. To create messages in advance, use the createEmailMessage and createSmsMessage methods.
Principle of use
| Syntax and URL to call the method |
| createCampaign (int message_id [, datetime start_time, string timezone, bool track_read, bool track_links, string contacts, string contacts_url, bool track_ga, stringga_medium, string ga_source, string ga_campaign, string ga_content,string ga_term], int payment_limit, string payment_currency) |
| https://api.selzy.com/en/api/createCampaign?format=json&api_key=KEY&message_id=ID&start_time=TIME&timezone= ZONE&track_read=X&track_links=Y&contacts=LIST&payment_limit =100&payment_currency=usd |
| Arguments | |
| api_key * | API access key. |
| message_id * | Code of the message to be sent. The code returned by the createEmailMessage or createSmsMessage method should be transferred. |
| start_time | Campaign launch date and time in the "YYYY-MM-DD hh:mm" format, which do not exceed 100 days from the current date. If the argument is not set, the campaign starts immediately. The time zone specified in the settings of the user's personal account is applied. To explicitly specify a time zone, use the "timezone" argument. To provide additional error protection, you should not schedule two sendings of the same message within an hour. |
| timezone | Time zone in which the time is set in the "start_time" argument. If it is not specified, the time zone is used from the settings of the Personal Account. You can explicitly specify the time zone, but currently the only one option is supported: "UTC". |
| track_read | The value obtained is either 0 or 1 – whether to track the fact of reading the email message. The default value is 0 (do not track). If 1, a link to a small image tracking the reference will be added to the email. The track_read argument is ignored for SMS messages. |
| track_links | The value obtained is either 0 or 1 – to track whether there are any click-throughs in email messages, the default value is 0 (do not track). If 1, all external links will be replaced with special ones that allow you to track the fact of a click-through, and then forward the user to the desired page. The track_links argument is ignored for SMS messages. |
| contacts | Email addresses separated by commas (or phone numbers for sms messages) to which sending of a message should be limited. If this argument is absent, sending will be made to all contacts on the list for which the message is made (possibly, taking into account segmentation by tags). If the contacts argument is present, only those contacts that are on the list will be taken into account, while the other will be ignored. If there are too many addresses (phone numbers) for sending in the contacts parameter, the contacts_url parameter can be used instead. You can't set both parameters at the same time |
| contacts_url | Instead of the contacts parameter containing the actual email addresses or phone numbers, in this parameter you can specify the URL of the file from which the addresses (phone numbers) will be read. The URL must start with "http://", "https://" or "ftp://". The file must contain one contact per string, without commas; strings must be separated by "n" or "rn" (Mac format — only "r" — not supported). The file can be deleted after the campaign has shifted to the 'scheduled' status. You can find out the campaign status using the getCampaignStatus method. |
| track_ga | The value obtained is either 0 or 1 – whether to enable Google Analytics/Yandex.Metrica integration for this campaign. Only explicitly indicated values are valid, default usage parameters are not applied. The default value is 0 (disabled). |
| payment_limit, payment_currency | Parameter that allows you to limit the campaign budget to the amount specified in the payment_limit in the currency specified in the payment_currency. If the payment_limit parameter is not set or is 0, it will not be taken into account. If the amount on the user's account is less than the specified budget, this will result in displaying an error. If the payment_currency parameter is not transferred, the system will use the currency set in the user profile. If an unsupported currency code is specified, an error will be returned. Valid currency codes: USD. The parameter can be set in upper or lower case. |
| ga_medium, ga_source, ga_campaign, ga_content, ga_term | Integration parameters with Google Analytics/Yandex.Metrica (valid if track_ga=1). Only explicitly indicated values are valid, default usage parameters are not applied. |
| Return value | |
| JSON object with the following fields: | |
| campaign_id | Unique campaign code – a positive 31-bit integer. |
| status | String mailing status, one of the following:
|
| count | The number of email addresses (or phone numbers in case of an SMS message) to which the message will be sent. |
If there are any errors or warnings, they are returned in the error/warnings fields as described. For example, an error may occur if there is insufficient money. The special campaign_already_exists error code means that this letter has already been scheduled to be sent within an hour of the specified time and you may be trying to send the same letter again. Response example:
{"result":{"campaign_id":932188,"status":"scheduled","count":0}}
|
|
Technical limitations
The request execution time is proportional to the number of contacts, the timeout for sending messages to 50,000 addresses is 30 seconds, and it increases with larger numbers.
The limitation in a Post request is exactly 32 mb. You can increase it through compression. See details on the request compression here.
In case no response is received after the timeout, you are recommended to repeat the request maximum two times. If the repeated request ends with an error message with the 'campaign_already_exists' code, one of the previous attempts worked though with a delay. If repeated attempts result in the timeout again, please .
