Page Comparison

This page provides you with information about how to use MailUp REST API to create text messages (SMS) and to send them to specified recipients.

...

title	Reference Links

...

Automated help page

...

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

The import process is able to 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 querystring 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 querystring 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

Code Block

language	xml
title	Add to a MailUp list

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Recipients

Code Block

language	xml
title	Add to a MailUp group

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Group/{id_Group}/Recipients

Reference

Go to automated doc

Expand

title	Click here to learn more about request parameters

Request The request is composed of a list of comma-separated objects, each one of them is composed of the following mandatory fields:

Field Name	Type	Description
Fields	Array of objects [0..39]. Each object is composed of the following fields: Description (String, optional) Id (Integer, from 1 to 39) Value (String)	Each array object is a personal data field. If the recipient is already existing, the "fields" values can be used to update the recipient's personal data
Name	String	Not used but required, it can be empty (i.e. "Name":"")
MobileNumber	String	Number The number format is checked by an asynchronous process, hence in case of invalid number import fails but no error is returned
MobilePrefix	String	International prefix. Allowed formats are: prefix with 00 (e.g. "0039") prefix with + (e.g. "+39") empty prefix (e.g. "", default list prefix is applied)

JSON request (example)

Expand

Code Block

language	xml

[{
  "Fields":[{
             "Description":"String content",
             "Id":1,
             "Value":"String content"
           }],
  "Name":"String content",
  "MobileNumber":"10123456",
  "MobilePrefix":"0039"
}]

JSON response (example)

Returns import ID

Paging and filtering (example)

...

Description

Specific methods are available for retrieving recipients that are, respectively, subscribed, pending, or unsubscribed on the SMS channel.

HTTP Method

GET

URL

Code Block

language	xml

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)

Expand

The same data format is used in the responses related to "Subscribed", "Pending" and "Unsubscribed". Full recipient details are returned.

Code Block

language	xml

{
   "IsPaginated" : false,
   "Items" : [
      {
         "Fields" : [
            {
               "Description" : "LatestOrderAmount",
               "Id" : 15,
               "Value" : ""
            },
            {
               "Description" : "FirstName",
               "Id" : 1,
               "Value" : "Mary"
            },
            {
               "Description" : "Region",
               "Id" : 8,
               "Value" : ""
            },
            {
               "Description" : "LatestOrderProductIDs",
               "Id" : 16,
               "Value" : ""
            },
            {
               "Description" : "LastName",
               "Id" : 2,
               "Value" : "Johnson"
            },
            {
               "Description" : "Address",
               "Id" : 9,
               "Value" : ""
            },
            {
               "Description" : "LatestOrderCategoryIDs",
               "Id" : 17,
               "Value" : ""
            },
            {
               "Description" : "Company",
               "Id" : 3,
               "Value" : ""
            },
            {
               "Description" : "Gender ",
               "Id" : 10,
               "Value" : ""
            },
            {
               "Description" : "LatestShippedOrderDate",
               "Id" : 18,
               "Value" : ""
            },
            {
               "Description" : "City",
               "Id" : 4,
               "Value" : ""
            },
            {
               "Description" : "phone",
               "Id" : 11,
               "Value" : ""
            },
            {
               "Description" : "LatestShippedOrderID",
               "Id" : 19,
               "Value" : ""
            },
            {
               "Description" : "Province",
               "Id" : 5,
               "Value" : ""
            },
            {
               "Description" : "CustomerID",
               "Id" : 12,
               "Value" : ""
            },
            {
               "Description" : "LatestAbandonedCartDate",
               "Id" : 20,
               "Value" : ""
            },
            {
               "Description" : "ZIP",
               "Id" : 6,
               "Value" : ""
            },
            {
               "Description" : "LatestOrderID",
               "Id" : 13,
               "Value" : ""
            },
            {
               "Description" : "State",
               "Id" : 7,
               "Value" : ""
            },
            {
               "Description" : "LatestOrderDate",
               "Id" : 14,
               "Value" : ""
            },
            {
               "Description" : "LatestAbandonedCartTotal",
               "Id" : 21,
               "Value" : ""
            },
            {
               "Description" : "LatestAbandonedCartID",
               "Id" : 22,
               "Value" : ""
            },
            {
               "Description" : "TotalOrdered",
               "Id" : 23,
               "Value" : ""
            },
            {
               "Description" : "TotalOrderedLast12m",
               "Id" : 24,
               "Value" : ""
            },
            {
               "Description" : "TotalOrderedLast30d",
               "Id" : 25,
               "Value" : ""
            },
            {
               "Description" : "AllOrderedProductIDs",
               "Id" : 26,
               "Value" : ""
            }
         ],
         "Name" : null,
         "idRecipient" : 15,
         "Email" : null,
         "MobileNumber" : "323456789",
         "MobilePrefix" : "001"
      }
   ],
   "PageNumber" : 0,
   "PageSize" : 10,
   "Skipped" : 0,
   "TotalElementsCount" : 1
}

Paging and filtering (example)

...

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, 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, punctuation, puntuaction 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

Code Block

language	xml

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/List/{id_List}/Message

Reference

Go to automated doc

Expand

title	Click here to learn more about request parameters

Field Name	Type	Description
Subject	String	Message title (for MailUp users only, it will not be visible to recipients)
idList	Integer	List-ID
Content	String	Message content
Fields	Array of objects [0..39]. Each object is composed of the following fields: Description (String, optional) Id (Integer, from 1 to 39) Value (String)	Each array object will be used to fill the correspondent dynamic field when its value has been left empty or blank.
Notes	String	Message notes (for MailUp users only, it will not be visible to recipients)
Tags	Array of objects Each object is composed of the following fields: Enabled (Boolean) Id (Integer, from 1 to 39) Value (String)	Optional An optional field , is used to link existing tags to the text message. Tags can be used to classify messages, please check this page for more details about tags
IsUnicode	Boolean	False if the message contains only letters or symbols that belong to the Western alphabet (GSM charset). True if at least one message character belongs to a non-western alphabet (Unicode)
Sender	String	Message sender. It can be a phone number (e.g. +393351234567) or a string (up to 11 chars, only letters, and numbernumbers). Please note that in some countrycountries, like Italy, some restrictions on SMS senders apply. Use the MailUp admin console to verify if the specified sender is subject to limitations in some countries. If you leave this field empty will be applied the SMS sender defined for the current List.

JSON request (example)

Expand

In this case recipients with an empty field as "FirstName" will receive "Hello dear customer, your appointment is confirmed for today at 5PM5 PM, Main Building 1st floor"
from "ABCandCO"

Code Block

language	xml

{
    "Subject":"Appointment #1",
    "idList":2,
    "Content":"Hello [firstname], your appointment is confirmed for today at 5PM, Main Building 1st floor",
    "Fields":[{
               "Id":1,
               "Value":"dear customer"
             }],
    "Notes":"Appointment is confirmed",
    "IsUnicode":false,
    "Sender":"ABCandCO"
}

JSON response (example)

Code Block

language	xml

{
   "Subject" : "Appointment #1",
   "idList" : 1,
   "idMessage" : 2
}

Paging and filtering (example)

...

Description

Retrieve text messages of a specified list

HTTP Method

GET

URL

Code Block

language	xml

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 a specified list

Expand

Code Block

language	xml

{
   "IsPaginated" : false,
   "Items" : [
      {
         "Subject" : "Appointment #1",
         "idList" : 2,
         "idMessage" : 2
      },
      {
         "Subject" : "Happy Holidays",
         "idList" : 2,
         "idMessage" : 6
      },
      {
         "Subject" : "Happy Birthday",
         "idList" : 2,
         "idMessage" : 5
      }
   ],
   "PageNumber" : 0,
   "PageSize" : 10,
   "Skipped" : 0,
   "TotalElementsCount" : 3
}

Paging and filtering (example)

Use this filter to extract only the SMS messages of list 1 that contain the word "promo" in their subject.
Strict filter matching with "==" instead of "Contains" is much more performing.

Code Block
GET /Console/Sms/List/1/Messages?filterby="Subject.Contains('promo')"

...

Description

Retrieve the text message details by specified message-id

HTTP Method

GET

URL

Retrieve the SMS details by specified id

Code Block

language	xml

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)

Expand

Code Block

language	xml

{
   "Subject" : "Appointment #1",
   "idList" : 1,
   "idMessage" : 2,
   "Content" : "Hello [firstname], your appointment is confirmed for today at 5PM, Main Building 1st floor",
   "Fields" : [
      {
         "Description" : "FirstName",
         "Id" : 1,
         "Value" : "dear customer"
      },
      {
         "Description" : "LastName",
         "Id" : 2,
         "Value" : ""
      },
      {
         "Description" : "Company",
         "Id" : 3,
         "Value" : ""
      },
      {
         "Description" : "City",
         "Id" : 4,
         "Value" : ""
      },
      {
         "Description" : "Province",
         "Id" : 5,
         "Value" : ""
      },
      {
         "Description" : "ZIP",
         "Id" : 6,
         "Value" : ""
      },
      {
         "Description" : "State",
         "Id" : 7,
         "Value" : ""
      },
      {
         "Description" : "Region",
         "Id" : 8,
         "Value" : ""
      },
      {
         "Description" : "Address",
         "Id" : 9,
         "Value" : ""
      },
      {
         "Description" : "Gender ",
         "Id" : 10,
         "Value" : ""
      },
      {
         "Description" : "phone",
         "Id" : 11,
         "Value" : ""
      },
      {
         "Description" : "CustomerID",
         "Id" : 12,
         "Value" : ""
      },
      {
         "Description" : "LatestOrderID",
         "Id" : 13,
         "Value" : ""
      },
      {
         "Description" : "LatestOrderDate",
         "Id" : 14,
         "Value" : ""
      },
      {
         "Description" : "LatestOrderAmount",
         "Id" : 15,
         "Value" : ""
      },
      {
         "Description" : "LatestOrderProductIDs",
         "Id" : 16,
         "Value" : ""
      },
      {
         "Description" : "LatestOrderCategoryIDs",
         "Id" : 17,
         "Value" : ""
      },
      {
         "Description" : "LatestShippedOrderDate",
         "Id" : 18,
         "Value" : ""
      },
      {
         "Description" : "LatestShippedOrderID",
         "Id" : 19,
         "Value" : ""
      },
      {
         "Description" : "LatestAbandonedCartDate",
         "Id" : 20,
         "Value" : ""
      },
      {
         "Description" : "LatestAbandonedCartTotal",
         "Id" : 21,
         "Value" : ""
      },
      {
         "Description" : "LatestAbandonedCartID",
         "Id" : 22,
         "Value" : ""
      },
      {
         "Description" : "TotalOrdered",
         "Id" : 23,
         "Value" : ""
      },
      {
         "Description" : "TotalOrderedLast12m",
         "Id" : 24,
         "Value" : ""
      },
      {
         "Description" : "TotalOrderedLast30d",
         "Id" : 25,
         "Value" : ""
      },
      {
         "Description" : "AllOrderedProductIDs",
         "Id" : 26,
         "Value" : ""
      }
   ],
   "Notes" : "Appointment is confirmed",
   "Tags" : [
      
   ],
   "IsUnicode" : false,
   "Sender" : "ABCandCO"
}

Paging and filtering (example)

...

Description

Update a text message by specifying the message-id

HTTP Method

PUT

URL

Code Block

language	xml

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)

Expand

Code Block

language	xml

{
 "Subject" : "Appointment #1",
 "idList" : 1,
 "idMessage" : 2,
 "Content" : "Hello [firstname], your appointment is confirmed for today at 5PM, Main Building 1st floor",
}

JSON response (example)

Expand

Code Block

language	xml

{
   "Subject" : "Appointment #1",
   "idList" : 1,
   "idMessage" : 2,
}

Paging and filtering (example)

...

Note

title	SMS Sender

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.
Please note that in some countries the sender may be subject to local restrictions and it may be overwritten by the carriers before being delivered. You can contact us if you need support for some specific nations.

...

Description

Send a text message to a mobile number by specifying message ID.
Recipient The recipient is automatically subscribed to the SMS channel of the list in which the message was created.

HTTP Method

POST

URL

Code Block

language	xml

https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Sms/Send

Reference

Go to automated doc

JSON request (example)

Expand

Code Block

language	xml

{
   "Number":"3351234567",
   "Prefix":"0039",
   "idMessage":27
}

JSON response (example)

Expand

Code Block

language	xml

{"InvalidRecipients":[],"Sent":1,"UnprocessedRecipients":[],"idMessage":27}

Paging and filtering (example)

...

Description

Immediate or scheduled mailing to a list or to a group

HTTP Method

POST

URL

Code Block

language	xml

<!-- 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)

Expand

"Sent" value refers to the number of recipients that will receive the message regardless of the type of sending (immediate or deferred)

Code Block

language	xml

{"InvalidRecipients":[],"Sent":10,"UnprocessedRecipients":[],"idMessage":42}

Paging and filtering (example)

...

Description

Retrieve the SMS message sending report details by specifying SMS ID.

HTTP Method

GET

URL

Code Block

language	xml

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)

Expand

ErrorCode = operation result (FAILED, UNKNOWN, NACK, UNDELIV, REJECTD, EXPIRED) + specific error code

Receiver = recipient's phone number, international prefix is specified uning neither '+' nor '00'

SentDate = sent date and time (UTC time zone)

Status = 0 (delivered), 1 (queued), 2 (error)

Code Block

{"IsPaginated":false,"Items":[
{"ErrorCode":"FAILED_AT_004","Receiver":"391111111111","SentDate":"2015-01-29 14:11:10Z","Status":2},
{"ErrorCode":"FAILED_AT_004","Receiver":"392222222222","SentDate":"2015-01-29 14:11:10Z","Status":2},
{"ErrorCode":"FAILED_AT_004","Receiver":"393333333333","SentDate":"2015-01-29 14:11:10Z","Status":2},
{"ErrorCode":"FAILED_AT_004","Receiver":"394444444444","SentDate":"2015-01-29 14:11:10Z","Status":2},
{"ErrorCode":"FAILED_AT_004","Receiver":"395555555555","SentDate":"2015-01-29 14:11:10Z","Status":2},
{"ErrorCode":"","Receiver":"396666666666","SentDate":"2015-01-29 14:11:10Z","Status":0},
{"ErrorCode":"","Receiver":"397777777777","SentDate":"2015-01-29 14:11:10Z","Status":0},
{"ErrorCode":"FAILED_AT_004","Receiver":"398888888888","SentDate":"2015-01-29 14:11:10Z","Status":2},
{"ErrorCode":"","Receiver":"399999999999","SentDate":"2015-01-29 14:11:10Z","Status":0}
],"PageNumber":0,"PageSize":0,"Skipped":0,"TotalElementsCount":0}

Paging and filtering (example)

Use this filter to extract the result of the latest message with ID=24 that was sent to number +3933512345678
GET /Console/Sms/24/Sendings/ReportDetails?filterby="Receiver=='3933512345678'"&orderby="SentDate+desc"&pageSize=1&pageNumber=0

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

...

Description

Retrieve several account details, including the amount number of available credits

HTTP Method

GET

URL

Code Block

language	xml

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)

Expand

Company = String, Customer name

IsTrial = Boolean, true in case of trial account

UID = String, user ID
Username = String, user name

Version = String, MailUp account version

Email = String, address used to activate the MailUp account
TotalCredits = Float, number of available credits

CreditsByList = Array of objects, number of available credits for each list (if credit's splitting by list is enabled)

Plan = Int, ID of purchased plan

ExpiryDate = Date

Autorenewal = Int, 1 if renewal is automatic, otherwise false

Lang = String, language

Code Block

language	xml

{
	"Company":"String content",
	"IsTrial":true,
	"UID":"String content",
	"Username":"String content",
	"Version":"String content"
	"Email":"String content"
	"TotalCredits":400.50
	"CreditsByList":[{"ListId":1,"Credit":10.3},{"ListId":2,"Credit":4.0}]
	"Plan":1
	"ExpiryDate":2025-02-20 00:00:00.000
	"AutoRenewal":1
	"Lang":"String content"
}

Paging and filtering (example)

...

Versions Compared

Old Version 28

New Version Current

Key

Subscribe on SMS channel

Add recipients