Uploading mailing lists to Smartmessages.net

The upload format for Smartmessages.net mailing lists is a plain text format known as "Comma-Separated Values" or CSV, which is commonly supported by database and spreadsheet applications such as LibreOffice, Microsoft Excel, Filemaker, MySQL, etc. See the technical notes section below for more details on the format. An uploaded record for your account should look like this:

emailaddress,allow_tracking,ownerdata,title,initials,jobtitle,firstname,lastname,dear,companyname,address1,address2,address3,posttown,county,postcode,country,phone,mobile,dob,custom1,custom2,custom3,custom4,custom5,custom6,custom7,custom8,custom9,custom10,custom11,custom12,custom13,custom14,custom15,custom16,custom17,custom18,custom19,custom20,custom21,custom22,custom23,custom24,custom25,custom26,custom27,custom28,custom29,custom30,custom31,custom32,preferred_format,preferred_language,url,agent,verified_at,ip,subscription_url

You can download an empty file that's in the right format so that you can shuffle your data into the correct fields.

Field notes

When uploading via the web interface or our API you may specify a subset of these fields, in whatever order you like by putting the field names on the first line of the uploaded CSV file and selecting the 'field names on first line' option. Fields that are not recognised will simply be ignored.

Most field names are self-explanatory, but some fields need particular care:

Ownerdata: A general purpose field used to identify this record within your own database or contact system, and is stored in Smartmessages.net to facilitate round-tripping of data between your database and ours. You can put whatever you like in here, and when you download data from Smartmessages.net again, the value will be passed back untouched, so you can be sure that you're dealing with exactly the same record, even if other identifiers have changed. This field is not available in mailings.
Emailaddress: is used as a unique identifier in Smartmessages.net, so there can only ever be one person with a given (case-insensitive) email address among your recipients. Records with blank, duplicate or invalid email addresses will be skipped. Note that if we detect invalid addresses that cannot possibly have completed a double-opt-in, the entire list upload will be rejected, as its source cannot be trusted.
Title: Can be anything, but must be less than 6 characters (Mr, Mrs, Dr etc.).
Dear: is a greeting, as in what goes after "dear" to be used in preference to a real name without having to corrupt a real name field for this purpose, e.g. "Sir", "Fred", "Dr. Smith", "Mr. President".
DOB: (Date of birth) should be in the ISO8601 format YYYY-MM-DD.
Preferred format: Stores whether the recipient prefers HTML or plain text messages, and can be html or plain, defaulting to html.
Custom fields: are named simply custom1 to custom32. Their meaning and content is entirely up to you but they have a limit of 255 characters. Any line breaks in their values are translated to | (pipe) characters on export for easier CSV handling.
Preferred language: A 2-character (by convention, in lower case) ISO639-1 language code, e.g. en for English, fr for French etc., to represent the language that the recipient would most like to receive messages in. Supporting this field does not necessarily mean that you have to produce content in this language, but it tells you what your recipients would actually like.
Country: An ISO3166 2-character (by convention, in upper case) country code, e.g. FR for France, ES for Spain and notably, GB for the UK.
Sub_verified: A subscription-level field containing the verification status of each subscriber. This will either be yes (for those that have completed a double-opt-in process, or have sufficient subscription information imported), or n/a for those that were imported from lists. For reference, there is an internal no value used to track those that have requested a subscription directly with Smartmessages.net, but that have not yet confirmed it – subscribers with that status are not visible to you and are not included in downloads. This field is not directly importable and will be ignored, but records containing valid ip and verified_at values will have their sub_verified status set to yes.
IP: A subscription-level field containing the IP address that a double-opt-in confirmation click was received from. This field may be uploaded, but the verified_at field must also contain a valid value.
Verified_at: A subscription-level field containing an ISO8601 timestamp (in the UTC time zone) that the subscription was verified. This may be earlier than the creation date if it was imported from another ESP. This field may be uploaded, but the ip field must also contain a valid value.
Agent: A subscription-level field containing the user agent string of the browser that was used to make the confirmation click. This may be imported if the ip and verified_at fields are populated too, but will be ignored otherwise.
subscription_url: A subscription-level field containing the URL of the page from which the subscription request originated. If someone signed up using our standard subscribe pages, it will be that. If you're using your own form, but our form processor (as described in our help pages), your URL will be recorded there.

Technical notes

You MUST include the emailaddress field – a record without one is obviously useless for emailing!
The CSV spec is defined in RFC4180. We use , as the separator, and " as the (optional) quoting character. Fields that contain commas will need quotes wrapped around them, and quotes within fields will be escaped by themselves, so a single field containing Hello, "Joe" would be downloaded as "Hello, ""Joe""". You should NOT use \ to escape quotes. Most proper CSV import/export filters will deal with this correctly. We recommend LibreOffice (free) for working with CSV files directly – it's significantly better at it than Microsoft Excel.
Any fields that have unknown values should be left completely blank, that is, they should not contain any spaces, tabs etc.
All fields are subject to filtering for length, format, type and content.
You can compress your files using zip before upload in order to make uploads faster.
All data should use the UTF-8 encoding of the Unicode character set.
You may leave fields off the end of each line, but not off the beginning, so for example if you want to include the firstname field, you must include values (even empty ones) for ownerdata, emailaddress, title, initials and jobtitle.
Smartmessages.net will handle MacOS, Windows and UNIX line-break formats automatically.
Importing mailing lists can take a while after the upload itself completes. Progress will be reported on the upload history section of each mailing list page.

There is more detail of the upload process on our help pages.

A significant feature of Smartmessages.net is that personal data is stored separately from mailing list subscription information. A recipient who is, for example, subscribed to your 'Newsletter' mailing list would reference the same data from your 'Events' mailing list. This protects you against having duplicate sets of data for one person. This also means that if you want to create a sub-list from existing recipients, you can use the simpler 'Add multiple subscribers' form on the mailing list page – you don't need to upload all the same information again, just their email addresses, and Smartmessages.net will automatically link their data to their new subscriptions.

Uploading lists from other ESPs

Other ESPs that provide list downloads may include subscription confirmation data in the form of an IP address, a timestamp and a user agent string (mapping to the ip, verified_at and agent fields described above). We accept that as opt-in proof so that lists are reasonably portable across ESPs. If you have a list containing this kind of subscription information and we do not handle it correctly, please contact us so that we can add the format you have.

Downloading mailing lists from Smartmessages.net

You can download mailing lists in the same format as they are uploaded in from a mailing list's actions tab.