This feature allows to import contacts and send text messages in one single operation. You can deposit your .CSV file on a shared repository on MailUp servers: this file must contain all the required information for sending (e.g. sender, date and time of sending, body of the text message, recipients, and so on).
This feature was designed for handling files containing several hundreds or several thousands of recipients with a single file and no more than one file in a minute. If you are planning to develop an integration with an higher upload frequency or with smaller files, we recommend you consider using transactional APIs for SMS instead.
File format
Please ensure you save your file using UTF-8 encoding (with BOM), otherwise extended ASCII characters (e.g. accented letters, non western alphabets...) may be corrupted.
The .CSV file must be structured in two sections: header and messages.
Header
The header is made of a fixed number of rows: each one has a specific meaning and is preceded by the symbol "#" (number sign).
File import fails if the header has a number of rows other than seven, and/or if at least one of them has an incorrect format. Rows containing optional fields can be left empty, but the symbol "#" must be inserted anyway.
During the import process MailUp automatically removes from the header all the ";" characters, making the conversion from .XLS to .CSV easier.
| Row | Optional | Description | Example |
|---|---|---|---|
| 1 | Y | Indicates the author of the file. It can be an email address or a mobile number with prefix included | name.surname@myprovider.com |
| 2 | Y | Date and time of sending, with format "YYYY-MM-DD HH:MM". If the row is empty or the data indicate a time in the past, MailUp schedules an immediate sending. If the format is incorrect, an import error will occur. This row is used only if the field in row 3 is validated as "I" (i.e. sending) | 2012-03-01 14:30 |
| 3 | N | Action to be performed: Sending or Queueing. Allowed values are "I" for sending (capital "i", from the first letter of the Italian word "invio"), and "A" for queueing (capital"a", from the first letter of the Italian word "accodamento"). Queueing option arranges the sending but does not perform it: you will have to access the MailUp system to schedule it. | I |
| 4 | N | ID of the sender. It can be a valid phone number, or an alphanumeric ID (max 11 characters, with restrictions on allowed characters) | MailUp |
| 5 | Y | ID of the MailUp list. It indicates the "environment", the cost center or the category in which messages and recipients will be inserted (the ID of the list must be indicated, and not its name) | 5 |
| 6 | N | Campaign name. It identifies the different sendings when looking through the statistics. If the row is left empty, messages will be automatically associated to the campaign "Default N", where "N" stands for the ID of the MailUp list | Special offers |
| 7 | N | Non-duplication univocal code. This row can be used to assign a univocal code to each file. The system will perform the import only if a file containing that specific code has never been imported to that account. According to maximum allowed length, you can freely choose which string to use and the convention according to which each new code is generated. | COD1234567 |
Messages
The .csv file can contain an unlimited number of rows referring to the messages to be sent. Each row must have the following structure:
| Mobile number | Text | Field1 | ... | FieldN | Unicode |
|---|---|---|---|---|---|
| Mobile phone number of the recipient, complete with international prefix (both in the format "+" or "00"). Should the prefix not be indicated, the default prefix for the list will be used | Body of the text message: it might include placemarks [#1], [#2],... [#N] to allow MailUp to replace them with dynamic data | Placemark #1 | Placemark #N | Allowed values: 0,1. use value "1" (Unicode) only if the message is written using non-western characters. The use of Unicode option for languages such as Arabic, Russian, Chinese, and so on, restricts the maximum message length to 70 characters. It is possible to send longer messages by concatenating two or more of them. Maximum allowed length for Unicode concatenated messages is 134 characters for 2 messages and 201 characters for 3 messages. |
- The separator to be used is ";"
- The first row of the messages section must describe the different columns: e.g. MOBILE NUMBER;TEXT;Field1;Field2;Field3;Field4;UNICODE
- Insert a number of placemarks according to the needs of the file creator
- All the rows must contain the same number of fields (some of them might be empty as well)
- At least one column must be created for placemarks (e.g. Field1)
- The content of the placemark personalizes the message but does not update the data in the MailUp console
- At the end of the messages section you can add a row that serves as a commentary, it must begin with "#"
- Duplicated recipients inside the same file are ignored
Sample files
Queueing only (with non-duplication code)
#
#2012-02-29 09:50
#A
#MailUp
#1
#Special offer
#20120312-1
MOBILE NUMBER;TEXT;Field1;Field2;Field3;Field4;UNICODE
+18889624587;hello [#1] your surname is [#2] and you live in [#3] [#4];John;Smith;One Market Plaza, 5th floor;CA;0
0018881234567;hello [#2] your name is [#1] and you live in [#3] [#4];;Patricia;Johnson;Lexington, 1500;NY;0
Immediate sending to a list with default prefix 001 (international prefix is mandatory only when sending abroad)
#
#I
#MailUp
#1
#Special offer
#
MOBILE NUMBER;TEXT;Field1;Field2;Field3;Field4;UNICODE
8889624587;hello [#1] your surname is [#2] and you live in [#3] [#4];John;Smith;One Market Plaza, 5th floor;CA;0
8881234567;hello [#2] your name is [#1] and you live in [#3] [#4];;Patricia;Johnson;Lexington, 1500;NY;0
+34933181998;Hola [#2] tu nombre es [#1];Miguel;Bosè;Plaza Major, 28;Madrid;0
+4901512345678; Halo [#2], du heißt [#1];Merkel; Angela;2;Berlin;0
#commentary
Sending scheduled for February 29th, 2012 at 9:50 AM
#
#2012-02-29 09:50
#I
#MailUp
#1
#Special offer
#
MOBILE NUMBER;TEXT;Field1;Field2;Field3;Field4;UNICODE
+18889624587;hello [#1] your surname is [#2] and you live in [#3] [#4];John;Smith;One Market Plaza, 5th floor;CA;0
0018881234567;hello [#2] your name is [#1] and you live in [#3] [#4];;Patricia;Johnson;Lexington, 1500;NY;0
+34933181998;Hola [#2] tu nombre es [#1];Miguel;Bosè;Plaza Major, 28;Madrid;0
+4901512345678; Halo [#2], du heißt [#1];Merkel; Angela;2;Berlin;0
Immediate sending with one placemark only
#
#
#I
#MailUp
#1
#Special offer
#
MOBILE NUMBER;TEXT;Field1;UNICODE
8889624587;hello [#1];John;0
8881234567;hello [#1];Patricia;0
+34933181998;Hola [#1];Miguel;0
+4901512345678; Halo [#1];Angela;0
#commentary