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:


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:

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.
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.
Can be anything, but must be less than 6 characters (Mr, Mrs, Dr etc.).
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".
(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.
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.
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.
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.
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.
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.
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

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.