This page provides you information about how to use MailUp REST API to create text messages (SMS) and to send them to specified recipients.
On this page:
Subscribe on SMS channel
Add (i.e. subscribe) recipients
In case of already existing recipients the following behaviour applies on subscription:
- already subscribed remain subscribed
- pending or unsubscribed on SMS channel do not change their subscription status
Description | Asynchronous import of one or more recipients on SMS channel |
---|---|
HTTP Method | POST |
URL | Add to a MailUp list https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Recipients Add to a MailUp group https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Group/{id_Group}/Recipients |
Reference | |
JSON request (example) | |
JSON response (example) | Returns import ID
|
Paging and filtering (example) |
|
Read recipients
Description | Specific methods are available for retrieving recipients that are, respectively, subscribed, pending or unsubscribed on SMS channel. |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Recipients/Subscribed https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Recipients/Pending https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Recipients/Unsubscribed |
Reference | Automated docs are available for Subscribed, Pending and Unsubscribed
|
JSON request (example) | |
JSON response (example) |
|
Paging and filtering (example) |
|
Text messages
A text message is always created inside the environment of a MailUp list, so it cannot be managed outside of that list.
Create a message
Please note that, when creating a new text message, any referenced tag must be created in advance for that list.
Known limitations:
- In some countries, like Italy, some restrictions on SMS senders apply. Use MailUp admin console to verify if the specified sender is subject to limitations in some countries
- MailUp REST API applies, on alphanumeric senders, looser format restrictions than the admin console. While admin console allows only letters and numbers, API also allow spaces, puntuaction and other special characters. Please consider that letters and numbers are supported by any carrier, while other characters may be replaced in some cases. It is recommended that you perform some tests before using a sender with spaces, puntuaction or special characters
- In case of empty Sender the default list settings are applied
Description | Create a new text message |
---|---|
HTTP Method | POST |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Message |
Reference | |
JSON request (example) | |
JSON response (example) | { "Subject" : "Appointment #1", "idList" : 1, "idMessage" : 2 }
|
Paging and filtering (example) |
|
List Messages
Description | Retrieve text messages of specified list |
---|---|
HTTP Method | GET |
URL | GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Messages |
Reference | Go to automated doc |
JSON request (example) | none |
JSON response (example) | All the text messages of specified list |
Paging and filtering (example) | Use this filter to extract only the SMS messages of list 1 that contain the word "promo" in their subject GET /Console/Sms/List/1/Messages?filterby="Subject.Contains('promo')" |
Read message details
Description | Retrieve the text message details by specified message id |
---|---|
HTTP Method | GET |
URL | Retrieve the SMS details by specified id https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Message/{id_Message} |
Reference | Go to automated doc |
JSON request (example) | none |
JSON response (example) | |
Paging and filtering (example) |
Update message
Description | Update a text message by specifying the message id |
---|---|
HTTP Method | PUT |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{ID_LIST}/Message/{ID_MESSAGE} |
Reference | Go to automated doc |
JSON request (example) | |
JSON response (example) | |
Paging and filtering (example) |
Delete Message
Description | Delete a text message by specifying its ID |
---|---|
HTTP Method | DELETE |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{ID_LIST}/Message/{ID_MESSAGE} |
Reference | Go to automated doc |
JSON request (example) | none |
JSON response (example) | none |
Paging and filtering (example) |
Send a text message
Single Send
Description | Send a text message to a mobile number by specifying message ID. Recipient is automatically subscribed to the SMS channel of the list in which the message was created. |
---|---|
HTTP Method | POST |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Send |
Reference | Go to automated doc |
JSON request (example) | |
JSON response (example) | |
Paging and filtering (example) |
Send to group / list
Description | Immediate or scheduled mailing to a list or to a group |
---|---|
HTTP Method | POST |
URL | <!-- Immediate Send to all subscribers on SMS channel for specified list --> https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Message/{id_Message}/Send <!-- Immediate Send to all subscribers on SMS channel for specified group --> https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Group/{id_Group}/Message/{id_Message}/Send <!-- Scheduled Send to all subscribers on SMS channel for specified list (UTC timezone is expected) --> https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Message/{id_Message}/Send?datetime="2015-10-20 05:00:00Z" <!-- Scheduled Send to all subscribers on SMS channel for specified group (UTC timezone is expected) --> https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Group/{id_Group}/Message/{id_Message}/Send?datetime="2015-10-20 05:00:00Z" |
Reference | Go to automated doc (all operations) |
JSON request (example) | none |
JSON response (example) | |
Paging and filtering (example) |
Manage Send Queue
Known limitations:
- scheduled date and time cannot be modified
- at the moment there is no way to move from immediate/scheduled queues to "waiting to be sent" queue
Description | Query the send queue |
---|---|
HTTP Method | GET, POST |
URL | <!-- Retrieve the status of sms sending queues for immediate scheduled dispatches --> GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Sendings/Immediate <!-- Retrieve the status of sms sending queues for deferred scheduled dispatches --> GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Sendings/Deferred <!-- Retrieves the status of sms sending queues for dispatches to be scheduled --> GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Sendings/Undefined <!-- Retrieves the earliest date and time to schedule the given sending task --> GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Sending/{id_Sending}/Deferred <!-- Move from "waiting to be sent" to "immediate sending" queue (without starting send) --> POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Sendings/{id_Sending}/Immediate <!-- Move from "waiting to be sent" to "scheduled sending" queue (scheduled date and time is passed as POST parameter) --> POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Sendings/{id_Sending}/Deferred |
Reference | Go to automated doc (all operations) |
JSON request (example) | |
JSON response (example) | |
Paging and filtering (example) |
SMS Statistics
Summary report
Description | Retrieve the SMS message sending report by specifying SMS ID. |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/{id_Message}/Sendings/Report |
Reference | Go to automated doc |
JSON request (example) | none |
JSON response (example) | |
Paging and filtering (example) |
Detailed report
Description | Retrieve the SMS message sending report details by specifying SMS ID. |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/{ID_MESSAGE}/Sendings/ReportDetails |
Reference | Go to automated doc |
JSON request (example) | none |
JSON response (example) | |
Paging and filtering (example) | Use this filter to extract the result of the latest message with ID=24 that was sent to number +3933512345678 If you used the sending method of the Transactional API for SMS you can also filter by the DeliveryId that was returned by that method. GET /Console/Sms/24/Sendings/ReportDetails?DeliveryId=1648 In this case paging and further filtering is not required, since no more than one result can be returned |
SMS Credits
Summary report
Description | Retrieve several account details, including the amount of available credits |
---|---|
HTTP Method | GET |
URL | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Authentication/Details |
Reference | Go to automated doc |
JSON request (example) | none |
JSON response (example) | |
Paging and filtering (example) |