The Subscriber Import Job Entity specifies the data in a delimited text segment¹. 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 any² 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 names³. 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

---

Footnotes

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. ↩