Import Mapping

The Subscriber Import Job Entity specifies the data in a delimited text segment1. The delimited data is sub-divided into rows and columns. The rows are delimited by newlines, and the columns by the delimiter. This data is then used to populate the imported subscribers.

To enable this, these columns must be mapped onto subscriber fields. Columns can be mapped to any2 of the Poppulo built-in fields, or to any custom field you have created.

Please note that the automatic mapping described below is deprecated and is not available to new integrations. New integrations must specify a columns tag when submitting an import job.

Unless the columns tag is included, these columns are automatically mapped into the Poppulo system. This automatic mapping uses a variety of heuristics to determine which values should be mapped to which fields in our system. For example, a typical import might be a CSV file with a header line consisting of column names.

However, the automatic mapping process will not always do what is desired. More importantly, the automatic mapping algorithm can be tweaked, which could cause automatically submitted imports to be mapped differently over time. For API imports, we recommend instead that an explicit mapping is provided. This is the purpose of the columns tag. It is a comma separated list of Poppulo's canonical field names3. The number of columns specified in the tag must match the number of columns in the file. If specified, the automatic mapping will not be performed and the subscriber data will instead be mapped exclusively according to the content of this tag.

The following is the complete list of canonical column names for the columns tag of the subscriber import job. The exact name must be used, including any dots and spacing. Custom field names should be included verbatim.

Column name Column description Example CSV value(s)
email Subscriber's email address joe.m.bloggs@example.com
employeeId 4 Subscriber's employee id empl_1234
mobileAccessCode 4 Subscriber's mobile access code 654160809328
salutation Subscriber's salutation Mr, Ms, etc...
name.first name Subscriber's first name Joe
name.middle initial Subscriber's middle initial M
name.surname Subscriber's last name Bloggs
company The company the subscriber works at Poppulo
position The subscriber's job title Developer
address.address line 1 First line of subscriber's address Building 101
address.address line 2 Second line of subscriber's address 123 Fake Street
address.address line 3 Final line of subscriber's address Brooklyn
address.city The city the subscriber is in New York
address.state/region The state or region the subscriber is in NY
address.postal code The postal code for the subscriber 11201
address.country The subscriber's country USA
phoneNumber.phone number The subscriber's phone number 555 123456
fax.fax number The subscriber's fax number 555 123456
website A website associated with the subscriber www.example.com
source The source of the subscriber October mailing
mail format The subscriber's preferred email format Html, Text
externalId An identifier used in your system to refer to the subscriber Free text
status Subscriber status Active, Inactive or Opt_Out
optoutReason The reason the subscriber has opted out Admin, Subscriber
tags Comma separated list of tags to add Imported via API
topics Comma separated list of topics to add World News
permissions Comma separated list of permissions to add Newsletter
sections5 Comma separated list of sections to add Feature Story
removetags Comma separated list of tags to remove Imported via API, *
removetopics Comma separated list of topics to remove World News, *
removepermissions Comma separated list of permissions to remove Newsletter, *
removesections5 Comma separated list of sections to remove Feature Story, *
doNotImport This column will be ignored6 Free Text
Custom field name Custom fields are referred to by their own names My Custom Field Value

Some of the columns do not map directly to individual fields in a subscriber. The permissions, sections and tags fields are special values that allow the client program to specify these entities on a per-subscriber level. The remove versions of these fields remove the specified values from the subscribers. The special wildcard value * can be used with the remove to remove all permissions/sections/tags from the specified subscriber.

Please read Tag Synchronisation for more information about the risks of removing all Tags in your integration

1. The delimiter is by default a comma. Thus the data is typically CSV. The field_separator tag can override this default. ↩
2. Some fields are read only system fields, e.g. date created or date updated. If you want to maintain such data explicitly, create a custom field. ↩
3. The values in the columns tag is always comma separated, even if field_separator is present and specifies a different delimiter. ↩
4. These fields are optional, and rely on the non-email feature being enabled for the account. Please contact our Customer Support team if you need this feature turned on. ↩
5. This functionality is deprecated and may not be available to you. Please use "topics" instead. ↩
6. The doNotImport column is useful if there is an existing process that generates the data, and it is to be used unmodified. ↩

results matching ""

    No results matching ""