This page provides you with information about how to use MailUp REST API to create email text messages (SMS) and to send them to specified recipients.
Panel | ||
---|---|---|
| ||
On this page:
Table of Contents |
---|
Subscribe on SMS channel
Add
...
recipients
In the case of already existing recipients the following behaviour behavior applies on subscriptionto subscriptions:
- already subscribed remain subscribed
- pending or unsubscribed on SMS channel do does not change their subscription status
Description | Asynchronous import of one or more recipients on SMS channel | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST | ||||||||||||||||||||
URL |
| ||||||||||||||||||||
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
...
The import process can recognize existing recipients, using the mobile number as unique identifiers, and update them according to the given input details. It is possible to add some query string parameters to specify some advanced behavior for the import process:
- clearMissingOrEmptyFields: when set to "true", the import process clears on the MailUp field that is not specified or set as empty in the request body.
- removeFromPrevGroups: when set to "true", first the import process removes the given recipients from any group they have been part of, then it adds them only to the group specified along with this request. This query string parameter applies only to "Add to a MailUp group" cases.
Description | Asynchronous import of one or more recipients on SMS channel | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST | ||||||||||||||||||||
URL |
| ||||||||||||||||||||
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 the SMS channel. | |||||
---|---|---|---|---|---|---|
HTTP Method | GET | |||||
URL |
|
Automated docs are available for Subscribed, Pending and 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 email text message, any referenced tag or attachment must be created in advance for that list.
...
Description
...
Create a new text message
...
HTTP Method
...
POST
...
URL
...
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 the admin console allows only letters and numbers, API also allow spaces, punctuation, 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, punctuation, or special characters
- In the case of an empty Sender, the default list settings are applied
Description | Create a new text message | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST | |||||||||||||||||||||||||
URL |
| |||||||||||||||||||||||||
Reference |
|
|
|
|
|
| |||
JSON request (example) |
|
---|
| ||||||
JSON response (example) |
|
---|
Paging and filtering (example) |
---|
List Messages
Description | Retrieve text messages of a specified list | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL |
| |||||||
Reference | Go to automated doc | |||||||
JSON request (example) | none | |||||||
JSON response (example) | All the text messages of a specified list
| |||||||
Paging and filtering (example) |
Read message details
Use this filter to extract only the SMS messages of list 1 that contain the word "promo" in their subject.
|
Read message details
Description | Retrieve the text message details by specified message-id | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | GET | |||||||
URL | Retrieve the SMS details by specified id
| |||||||
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 |
| |||||||
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 |
| |||||
Reference | Go to automated doc | |||||
JSON request (example) | none | |||||
JSON response (example) | none | |||||
Paging and filtering (example) |
Send a text message
...
Note |
---|
...
| ||
Regardless of the sender, you set when creating a message, MailUp REST API always sends SMS using the sender that is specified at the list level. If you want to change the sender you must modify the list properties. |
Single Send
Description | Send a text message to a mobile number by specifying message ID. The recipient is automatically subscribed to the SMS channel of the list in which the message was created. | |||||||
---|---|---|---|---|---|---|---|---|
HTTP Method | POST | |||||||
URL |
| |||||||
Reference | Go to automated doc | |||||||
JSON request (example) |
| |||||||
JSON response (example) |
|
| ||
Paging and filtering (example) |
---|
Send to group/list
Manage Send Queue
SMS Statistics
Summary report
Detailed report
Sending Queue Status
It is possible to retrieve the status of the sending queue for the outgoing messages by calling the following methods:
...
Description | Immediate or scheduled mailing to a list or a group | |||||
---|---|---|---|---|---|---|
HTTP Method | POST | |||||
URL |
|
...
|
...
|
...
3) status of sending to be planned: GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Email/Sendings/Undefined
Moreover, it is possible to retrieve the first available date to send a specific sending:
...
|
...
|
...
|
...
|
...
|
...
Update message
This method allows you to modify an existing message (content and settings).
Please note that
- "Tags" field is mandatory, if you leave it empty the existing tags of that message are not modified. There is no way to clear all tags
- "Fields" parameter is optional
- "TrackingInfo > Protocols" field values are ignored if "TrackingInfo > Enabled" is set to false
Description | Modify an existing message | ||||
---|---|---|---|---|---|
HTTP Method | PUT | ||||
URL |
| ||||
JSON request (example) | Request data format is the same as the response of "GET /Console/List/{id_List}/Email/{id_Message}"
| ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none |
Manage tags
HTTP Method
GET, POST, PUT, DELETE
URL
Retrieve list tags:
| ||||||||
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 |
|
|
|
Create a new tag:
| |||
Reference | Go to automated doc (all operations) | ||
---|---|---|---|
JSON request (example) |
|
|
Modify a tag:
Code Block |
---|
PUT https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Tag/{id_Tag} |
Remove a list tag:
Code Block |
---|
DELETE https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Tag/{id_Tag} |
JSON request (example)
- No request body is required for GET and DELETE methods
- POST method requires a simple string as parameter (e.g. "my-new-tag"), not a JSON structure
- PUT method requires a full structure like {"Enabled":true,"Id":6,"Name":"my-new-tag"}
JSON response (example)
GET method returns the retrieved tags list
Expand | ||
---|---|---|
|
POST and PUT methods return the full structure of the created/updated tag, e.g. {"Enabled":true,"Id":6,"Name":"my-new-tag"}
An empty response is returned by DELETE method
Paging and filtering (example)
none
Manage email attachments
MailUp messages support a maximum of five attachments. Each attachment is placed in a specified "slot": adding and removing an attachment means adding to a message "slot" or removing from it.
Description | Read, add and remove message attachments | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | GET, POST, DELETE | ||||||||||||
URL | Retrieve all the attachments of a specified message
Add an attachment to message slot
Remove an attachment from a message slot
| ||||||||||||
JSON request (example) | Only POST method needs a request parameter. Attachment has to be Base64 encoded
| ||||||||||||
JSON response (example) | GET method returns a list of the documents that are attached to specified message. An empty array ([], not JSON format) is returned if no document is attached.
POST method returns the list of attachments after the command execution
DELETE method returns details about remaining attachments after deletion
| ||||||||||||
Paging and filtering (example) | none |
Send Email Messages
Email messages are usually sent with the sender name and the sender name that are specified as default settings for the MailUp list. As an alternative you can specify a different sender for a certain sending by specifying "SenderName" and "SenderAddress" (both, not only one of them) as querystring parameters.
Example: POST /Console/List/2/Email/30/Send?SenderName='John Smith'&SenderAddress='smith@example.com'
It is possible to specify an eventual date/time for a deferred sending, using the 'datetime' querystring parameter (UTC value), with the format described in the section 'Type and cast definition' of this page: "Paging and filtering"
Example: POST /Console/List/2/Email/30/Send?datetime='2014-10-20 05:00:00Z'
Note |
---|
Message sending fails with HTTP 500 error if no authorized sender email nor sender email are provided. Ensure that sender name and sender email have been configured at list level (starting from MailUp version 8.6.1 the sender address has also to be a verified address) |
Send to all subscribers
Description | Send a message to all list subscribers | ||||
---|---|---|---|---|---|
HTTP Method | POST | ||||
URL | Use the default list sender
Use the sender that is provided by querystring parameters
| ||||
JSON request (example) | none | ||||
JSON response (example) | See notes at the bottom of this page1
| ||||
Paging and filtering (example) | none |
Send to a group
Use the default list sender or a sender that is provided by querystring parameters (see example above)
Description | Send a message to all subscribers of specified group | ||
---|---|---|---|
HTTP Method | POST | ||
URL |
| ||
JSON request (example) | none | ||
JSON response (example) | See notes at the bottom of this page1
| ||
Paging and filtering (example) | none |
Send to a recipient
Use the default list sender or a sender that is provided by querystring parameters (see example above)
Description | Send message to a single recipient | ||
---|---|---|---|
HTTP Method | POST | ||
URL |
| ||
JSON request (example) |
| ||
JSON response (example) | See notes at the bottom of this page1
| ||
Paging and filtering (example) | none |
Retrieve sending history
An email message can be sent several times. This feature allows to retrieve details about each sending.
HTTP Method
GET
URL
| |||||||||||||||||||||||||||||||||||||
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 |
| |||||||
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 |
| |||||
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 number of available credits | |||||
---|---|---|---|---|---|---|
HTTP Method | GET | |||||
URL |
|
JSON request (example)
none
JSON response (example)
Expand | ||
---|---|---|
An email message has been sent three times with different senders, here below the results
|
Paging and filtering (example)
N/A
...
| ||||||||
Reference | Go to automated doc | |||||||
---|---|---|---|---|---|---|---|---|
JSON request (example) | none | |||||||
JSON response (example) |
| |||||||
Paging and filtering (example) |