REST API
Legacy Poppulo platform REST API
Subscriber Import Job
Overview
This is a Subscriber Import Job. It provides a convenient way to bulk create or update Subscribers. The import job takes some delimited text data (typically CSV) representing per-subscriber information, and also some global settings that will be applied to each subscriber. It is also a good way to add [Tags]/api-reference/legacy(/api-entities/api-tag), Permissions or Sections to subscribers.
The import job uses the email addresses or the employee IDs to match existing subscribers, and to create new ones. In order to be imported successfully a subscriber needs to have either an email or an employee ID. You must have an "email" column in the CSV data section and this has to be left blank if the subscriber only has an employee ID1. For subscribers without email addresses, the mobile access code field is mandatory. If update_existing is not set, only lines containing new emails will be used. It is not possible to specify an import job that doesn't create new subscribers.
Using import jobs can save on hundreds or thousands of calls, so it is highly recommended for reducing your bandwidth, reducing the time waiting for the process to finish, and for playing nicely with our usage limitations.
Fields
| Field name | Description | Type/Allowed values |
|---|---|---|
accept_terms | Whether your organization is willing to act under Poppulo's email policy for importing lists2. | Boolean |
update_existing | If false, only create new subscribers. If true, update existing subscribers too. | Boolean |
reactivate_api_removed | If true, subscribers that have been de-activated through the API will be activated if possible | Boolean |
reactivate_admin_removed | If true, subscribers that have been de-activated through our web application will be activated if possible | Boolean |
reactivate_bounced_removed | If true, subscribers that have been de-activated by our bounce detector will be activated if possible | Boolean |
set_fields | A list of field values to apply to all subscribers | Tag List of set_field sub-tags |
set_field | A field (name, value) to set for all subscribers. The name is specified using an attribute. | Value to set field to. Type Depends on the field (see Subscriber Entitiy) |
add_permissions | A list of permissions to add to subscribers | Tag List of permission sub-tags |
remove_permissions | A list of permissions to add to subscribers | Tag List of permission sub-tags |
permission | A permission to add/remove from imported subscribers. The name is specified using an attribute. | No content |
tags | A list of tags to add to subscribers | Tag List of tag sub-tags |
replace_tags | A list of tags that will be replaced by this import | Tag List of tag sub-tags |
tag | A tag to add to all subscribers. The name is specified using an attribute. | No content |
| Field name | Description | Type/Allowed values | |
|---|---|---|---|
| subscriber_data | columns | A comma separated list of canonical column names for the data | Text |
| subscriber_data | skip_first_line | True if the first line of data should be skipped (e.g. it is a CSV header with column names) | Boolean |
| subscriber_data | field_separator | What type of character is the data delimiter. Auto uses some hueristics to guess the correct character | Enumeration of auto, comma, tab, pipe |
| subscriber_data | data | The actual subscriber data, rows delimited with newlines | Text |
Examples
Import subscribers with email (all fields):
<subscriber_import_job>
<accept_terms>true</accept_terms>
<update_existing>true</update_existing>
<reactivate_api_removed>false</reactivate_api_removed>
<reactivate_admin_removed>false</reactivate_admin_removed>
<reactivate_bounced_removed>false</reactivate_bounced_removed>
<set_fields>
<set_field name="source">website</set_field>
</set_fields>
<add_permissions>
<permission name="Newletter Permission" />
<permission name="Flyer Permission" />
</add_permissions>
<remove_permissions>
<permission name="Old Permission" />
<permission name="Unused Permission" />
</remove_permissions>
<tags>
<tag name="Some Tag" />
<tag name="Other Tag" />
</tags>
<replace_tags>
<tag name="Some Tag"/>
</replace_tags>
<subscriber_data>
<columns>email,name.surname,name.first name</columns>
<skip_first_line>true</skip_first_line>
<field_separator>comma</field_separator>
<data>
email,Last Name,First Name
xyz@newsweaver.ie,Roycroft,George
hsdafgj@newsweaver.co.uk,Wolfenstein,Alexander
</data>
</subscriber_data>
</subscriber_import_job>Import subscribers without email addresses:
<subscriber_import_job>
<accept_terms>true</accept_terms>
<reactivate_api_removed>false</reactivate_api_removed>
<reactivate_admin_removed>false</reactivate_admin_removed>
<reactivate_bounced_removed>false</reactivate_bounced_removed>
<subscriber_data>
<columns>email,name.surname,name.first name,employeeId,mobileAccessCode</columns>
<skip_first_line>true</skip_first_line>
<data>email,Last Name,First Name,employeeId,mobileAccessCode
,Roycroft,George,EMP_ID_1,1654160809328
,Wolfenstein,Alexander,EMP_ID_2,8902160809328
</data>
</subscriber_data>
</subscriber_import_job>Import subscribers with and without email addresses:
<subscriber_import_job>
<accept_terms>true</accept_terms>
<reactivate_api_removed>false</reactivate_api_removed>
<reactivate_admin_removed>false</reactivate_admin_removed>
<reactivate_bounced_removed>false</reactivate_bounced_removed>
<subscriber_data>
<columns>email,name.surname,name.first name,employeeId,mobileAccessCode</columns>
<skip_first_line>true</skip_first_line>
<data>email,Last Name,First Name,employeeId,mobileAccessCode
xyz@newsweaver.ie,g.roycroft@work.com,Roycroft,George,EMP_ID_1,
,Wolfenstein,Alexander,EMP_ID_2,8902160809328
</data>
</subscriber_data>
</subscriber_import_job>