Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 20 Next »

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

Reference Links

 

 

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

 Go to automated doc

 Click here to learn more about request parameters

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

Field NameTypeDescription
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 recipient is already existing, the "fields" values can be used to update recipient's personal data

NameStringNot used but required, it can be empty (i.e. "Name":"")
MobileNumberStringNumber format is checked by an asynchronous process, hence in case of invalid number import fails but no error is returned
MobilePrefixString

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)

 Click here to expand...
[{
  "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)

 

 

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)

 Click here to expand...

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

{
   "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)

 

 

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

Go to automated doc

 Click here to learn more about request parameters
Field NameTypeDescription
 SubjectStringMessage title (for MailUp users only, it will not be visible to recipients)
 idListIntegerList ID
ContentStringMessage 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.

NotesStringMessage notes (for MailUp users only, it will not be visible to recipients)
TagsArray of objects
Each object is composed of
the following fields:  
  • Enabled (Boolean)
  • Id (Integer, from 1 to 39)
  • Value (String)

Optional field, 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

IsUnicodeBooleanFalse if message contains only letters or symbols that belong to Western alphabet (GSM charset).
True if at least one message character belongs to a non-western alphabet (Unicode)
SenderString

Message sender. It can be a phone number (e.g. +393351234567) or a string (up to 11 chars,

only letters and number). Please note that in some country, 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.

If you leave this field empty a random numeric value will be applied.

JSON request (example)

 Click here to expand...

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

{
    "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)

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

 

 

Paging and filtering (example)

 

 

List Messages

DescriptionRetrieve 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
ReferenceGo to automated doc

JSON request (example)

none

JSON response (example)

All the text messages of specified list

 Click here to expand...
{
   "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

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

Read message details

DescriptionRetrieve 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}
ReferenceGo to automated doc

JSON request (example)

none

JSON response (example)

 Click here to expand...
{
   "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)

 

Update message

DescriptionUpdate 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}
ReferenceGo to automated doc

JSON request (example)

 Click here to expand...
{
 "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)

 Click here to expand...
{
   "Subject" : "Appointment #1",
   "idList" : 1,
   "idMessage" : 2,
}

Paging and filtering (example)

 

Delete Message

DescriptionDelete 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}
ReferenceGo to automated doc

JSON request (example)

none

JSON response (example)

none

Paging and filtering (example)

 

Send a text message

Single Send

DescriptionSend 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
ReferenceGo to automated doc

JSON request (example)

 Click here to expand...
{
   "Number":"3351234567",
   "Prefix":"0039",
   "idMessage":27
}

JSON response (example)

 Click here to expand...
{"InvalidRecipients":[],"Sent":1,"UnprocessedRecipients":[],"idMessage":27}

Paging and filtering (example)

 

Send to group / list

DescriptionImmediate 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" 
ReferenceGo to automated doc (all operations)

JSON request (example)

none

JSON response (example)

 Click here to expand...

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

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

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
DescriptionQuery 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
ReferenceGo to automated doc (all operations)

JSON request (example)

 Click here to expand...

Request example for POST /Console/Sms/Sendings/{id_Sending}/Deferred

{
    "Date":"2015-02-19 14:41:46Z"
}

JSON response (example)

 Click here to expand...
Immediate
 {"IsPaginated":false,"Items":[{"Id":74,"IdList":10,"IdMessage":41,"Notes":"","StartDate":"","State":"Running","Subject":"Welcome","Type":"Immediate"}],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":1}
Deferred
{"IsPaginated":false,"Items":[
{"Id":72,"IdList":10,"IdMessage":29,"Notes":"This is a test message","StartDate":"2015-02-12 17:00:00Z","State":"Queued","Subject":"Test #1","Type":"Deferred"},{"Id":73,"IdList":3,"IdMessage":19,"Notes":"","StartDate":"2015-03-02 15:00:00Z","State":"Queued","Subject":"Customer credentials","Type":"Deferred"}
],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":2}
Undefined
{"IsPaginated":false,"Items":[
{"Id":36,"IdList":8,"IdMessage":12,"Notes":"msg to be sent after 3 warnings", "StartDate":null,"State":"ToBePlanned","Subject":"Final notice", "Type":"Undefined"},
{"Id":44,"IdList":3,"IdMessage":4,"Notes":"","StartDate":null,"State":"ToBePlanned","Subject":"Valentine's day","Type":"Undefined"},{"Id":46,"IdList":2,"IdMessage":14,"Notes":"","StartDate":null,"State":"ToBePlanned","Subject":"Welcome","Type":"Undefined"},{"Id":52,"IdList":2,"IdMessage":18,"Notes":"","StartDate":null,"State":"ToBePlanned","Subject":"Happy birthday","Type":"Undefined"},{"Id":48,"IdList":2,"IdMessage":15,"Notes":"","StartDate":null,"State":"ToBePlanned","Subject":"Season greetings","Type":"Undefined"},{"Id":71,"IdList":10,"IdMessage":30,"Notes":"","StartDate":null,"State":"ToBePlanned","Subject":"Password reminder","Type":"Undefined"}
],"PageNumber":0,"PageSize":20,"Skipped":0,"TotalElementsCount":6}
Earliest date and time
"2015-02-09 14:41:46Z"
Moved from waiting to immedate
{"Id":74,"IdList":10,"IdMessage":41,"Notes":"","StartDate":"","State":"Running","Subject":"Welcome","Type":"Immediate"}
Moved from waining to deferred
{"Id":74,"IdList":10,"IdMessage":41,"Notes":"","StartDate":"2015-02-19 14:41:46Z","State":"Queued","Subject":"Welcome","Type":"Deferred"}

Paging and filtering (example)

 

 

SMS Statistics

Summary report

DescriptionRetrieve 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
ReferenceGo to automated doc

JSON request (example)

none

JSON response (example)

 Click here to expand...
StartDate = timestamp for mailing start
EndDate = timestamp for mailing start
Duration = mailing duration (from start to end dates)
IsCompleted = true if mailing is finished
TotalCost = number of spent credits
TotalMessagesSent = number of messages that compose the mailing (a concatenated message is treated as a single message)
TotalSmsSent = number of billed messages (a concatenated message is billed as a multiple message)

 

{
   "Duration" : "00:00:06.4270000",
   "EndDate" : "2014-11-27 10:35:49Z",
   "IsCompleted" : true,
   "StartDate" : "2014-11-27 10:35:43Z",
   "TotalCost" : 2,
   "TotalMessagesSent" : 1,
   "TotalSmsSent" : 2
}

Paging and filtering (example)

 

Detailed report

DescriptionRetrieve 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
ReferenceGo to automated doc

JSON request (example)

none

JSON response (example)

 Click here to 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)

{"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.Contains('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

 

 

  • No labels