Note |
---|
The MailUp transactional API for SMS does not use OAuth 2.0. Please refer to the "Getting started" section below for details. |
...
Code Block |
---|
Format: "Authorization: Basic " + Base64(username:password)
Example: username=m1234, password=hello123, Base64(m1234:hello123)=bTEyMzQ6aGVsbG8xMjM= => Authorization: Basic bTEyMzQ6aGVsbG8xMjM= |
Once you have obtained the value of the ListSecret parameter:
- you can start sending transactional text messages (see example below)
- basic authentication is no longer required in those API calls
Retrieving, creating, and deleting the ListSecret parameter
...
Sending a transactional SMS
Once you have the value of the ListSecret parameter, you can start sending transactional text messages and basic authentication is no longer required.
The example below sends an SMS to the number +393350000001
Code Block |
---|
language | groovy |
---|
title | ExampleRequest |
---|
|
POST https://sendsms.mailup.com/api/v2.0/sms/{account_ID}/{List_ID} HTTP/1.1
User-Agent: Fiddler
Host: sendsms.mailup.com
Content-Type: application/json;odata=verbose;charset=utf-8
Content-Length: 428
{
"Content":"Hi [Name], welcome to [City]",
"ListGuid":"xxxxxxxx-aaa-bbbb-cccc-e3a98b626156",
"ListSecret":"yyyyyyyy-ddd-eeee-ffff-3e1cb0e6e64c",
"Recipient":"+393350000001",
"CampaignCode":"Welcome messages",
"DynamicFields":[{"N":"Name","V":"John"},{"N":"City","V":"Cremona"}],
"isUnicode":0
} |
Anchor |
---|
| Transactional_SMS_parameters |
---|
| Transactional_SMS_parameters |
---|
|
Request
Expand |
---|
title | Click here to learn more about request parameters... |
---|
|
All fields are mandatory Parameter | Description | Type |
---|
Account ID | MailUp account ID (e.g. if the main user is "m59484", then the account ID is 59848). | Integer | List ID |
List MailUp list identifier for the selected |
list within that account. | Integer | List GUID | Hash code that identifies the |
same list. This parameter is unique to a list within the entire MailUp system, unlike the List ID, which is unique only within a given MailUp accountspecified MailUp list. | String | ListSecret |
The parameter described above and Auto-generated GUID that can be used to enable or disable the use of this API |
(it’s an auto-generated GUID). Together with the "List GUID" value, it is used to provide a security enforcement. See the sections above to learn how to get it. | String | CampaignCode | Used to aggregate statistics on MailUp under a container text message whose name correspond to the specified text string. If the specified value |
specified record in the “SMS” table, otherwise the . Otherwise the existing one is reused. | String | Content | The text of the message to be sent. No parsing nor length check is required. SIZE LIMIT: messages longer than |
459 characters 670 characters are truncated by the sending engine. | String | Recipient | The recipient’s number. Include the international prefix (either with 00 or +), or the default list prefix will be applied. (Ask for MailUp standard regex for phone numbers). Only a single phone number is allowed |
Always check subscription status on specified list (SMS_Optin table) New = subscribe and send Subscribed = send Pending or Unsubscribed = do not send | String | DynamicFields | An array of value pairs that allows you to use merge tags in your transactional text messages. | String | IsUnicode | (optional) Boolean value indicating whether to use Western alphabets only (0 means "false"), or Eastern alphabets as well, such as Arabic, Russian, Chinese, and so on (1 means "true"). |
It is up to you to decide The caller is responsible for specifying if the message contains Unicode characters. | Boolean | Sender | (optional) Message sender. It can be numeric or alphanumeric but some restrictions may apply. As a consequence, when the sender value is not allowed, the message may be blocked or the sender may be replaced. We recommend you to specify this value only when you are confident about the delivery result (e.g. you've already tested it using the MailUp web platform), otherwise it is better to not specify this parameter in the request. In addition, 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. | String* | TemplateId | (optional) reference to a MailUp message ID that has already been defined on MailUp. Do not add the "Content" parameter if you want to use TemplateId | Integer |
* max 11 chars, only letters and numbers (a-zA-Z0-9) |
Response
...
Expand |
---|
title | Click here for details about error codes... |
---|
|
HTTP response statuses that can be returned by this API, and the corresponding error code provided by the application (inside the response).
500 | HTTP response code | Application Code | Description |
---|
200 | 0 | Ok. | 200 | 301 | The message was sent but the statistics are incorrect due to an error | 400 | 100 | No request found | 400 | 101 | Missing or empty parameters | 400 | 102 | ListGUID is not valid for the current account or list | 400 | 103 | ListSecret is not valid for the current account or list | 400 | 104 | SMS sender name is empty for list nr. N | 400 | 105 | Number or Prefix missing in the recipient | 400 | 106 | Recipient is invalid | 400 | 107 | Content too long | 403 | 201 | listID is not valid for the current account or list | 403 | 202 | ListGUID is not in a correct format | 403 | 203 | ListSecret is not in a correct format | 403 | 204 | Cannot send SMS to USA recipient | 403 | 205 | Sending denied: NO CREDITS | 403 | 206 | SMS number [recipient] is in optout state for list nr.[idList]. | 403 | 207 | Provided SMS sender is not certified and cannot be used to send messages | 403 | 250 | Access denied | 500 | 300 | Operation failed: a generic error occur | 500 |
301 | The message was sent but the statistics are incorrect due to an error | 302 | Error delivering message to [recipient] |
|
In addition to HTTP and Application codes, a successful response has the following format: Code Block |
---|
{"Data":{"DeliveryId":1648,"Cost":1.0},"Code":"0","Description":"","State":"DONE"} |
where DeliveryId is a unique identifier that can be used to retrieve the result of a specific sending (link), while Cost is the cost in credits of the sending operation. Note: in case of a response with HTTP code = 200 and Application code = 301, the message is properly sent and a cost is charged, but the returned value of DeliveryId is 0 (zero) and it not possible to retieve the result
|