legacy.bulk_sync

‹ BACK TO API PAGE

Description

WARNING: This method cannot be combined with any other method call within the same POST command.

Use this resource when you need to post a large amount of data. By design, this method is designed to keep the most data possible. Only those fields included within the data file will be updated for the contact records. Fields of contact records not included in the data file will retain their existing data.

Provide a text file that contains the contact records and information that you want to upload. The file can be comma (CSV) or tab delimited or you can set a custom delimiter. The first row of the file must contain column headers that represent the column data. Your data file must be accessible either via HTTP or via FTP.

If you include any date fields in your data file, the date must be formatted as YYYY-MM-DD.

The response XML message will include a <task_id> element which you can use as one of the input parameters for the utilities.getTasks method call in order to retrieve the latest status of the bulk sync job.

The table below includes the possible column header values that can be used in the data import file:

Column Header Description
email The email address of the subscriber (260 characters max)
external_id The subscriber's identifier defined within an external system. This ID must be unique across all subscribers (64 characters max).
firstname The subscriber's first name (260 characters max)
lastname The subscriber's last name (260 characters max)
address Street address (1000 characters max)
city City name (1000 characters max)
state State or province (250 characters max)
country Country name or ISO code (250 characters max)
postal_code Postal code (30 characters max)
phone_hm Home phone number (50 characters max)
phone_wk Work phone number (50 characters max)
fax Fax number (50 characters max)
epref A one-letter code defining the subscriber's email address preference as:
  • P – plain text
  • H – HTML
  • N – No preference
tz_id Time zone identifier
custvalNNNN A custom field that exists within the system where NNNN is the custom field ID to be referenced. To view a list of custom fields and their corresponding ID numbers, log in to the application and navigate to Assets > Manage Custom Fields. Scroll down on the screen to the Custom Fields section to find the custom field name and its corresponding custom field ID.
customfieldssNNNN A custom field that exists within the system where NNNN is the custom field ID to be referenced. To view a list of custom fields and their corresponding ID numbers, log in to the application and navigate to Assets > Manage Custom Fields. Scroll down on the screen to the Custom Fields section to find the custom field name and its corresponding custom field ID.

This column is only included for backwards compatibility. All references to custom fields should use the custvalNNNN notation.
customdatefldNNNN A custom date field that exists within the system where NNNN is the custom field ID to be referenced. To view a list of custom fields and their corresponding ID numbers, log in to the application and navigate to Assets > Manage Custom Fields. Scroll down on the screen to the Custom Fields section to find the custom field name and its corresponding custom field ID. The date must be in the format YYYY-MM-DD.

This column is only included for backwards compatibility. All references to custom fields should use the custvalNNNN notation.

Arguments

field Description Field Type Required Example
reply_email The email address which will receive the email confirmation when the bulk synchronization is complete string Yes jsmith@example.com
ignore_existing Specifies whether to update existing records in the database with the information provided in the data file where:
  • 0 – Do not ignore existing subscriber contact records. Any record that already exists in the subscriber database will be updated with the information provided in the data file. (default)
  • 1 – Ignore existing subscriber contact records. Any record that already exists in the subscriber database will not be updated with the information provided in the data file. This is an Add Only option.
 boolean No 1
ignore_new Specifies whether to create records in the database with the information provided in the data file where:
  • 0 – Do not ignore new subscriber contact records. Contact records for subscribers that are new to the database will be created. (default)
  • 1 – Ignore new subscriber contact records. Any record that does not exist in the subscriber database will not be created with the information provided in the data file.
 boolean No 1
grp A comma delimited list of the ID numbers of the static segments to which this subscriber should be added as a member. To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Segmentation > Manage Static Segments. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID. string No 34982,93833
clear_grp Including a comma delimited list of static segment ID numbers in this element will remove all subscribers from the static segments referenced here. Including a static segment ID in both the <clear_grp> element and the <grp> element has the effect of completely emptying the membership of the static segment prior to repopulated it with the subscribers being uploaded in the data file. As a short cut resetting the membership of static segments, include a comma delimited list of static segment IDs in the <grp> element and pass the value of 'Y' for the <clear_grp> element.

To view a list of static segments and their corresponding ID numbers, log in to the application and navigate to Segmentation > Manage Static Segments. Scroll down on the screen to the Segments section to find the static segment name and its corresponding segment ID.

string No 34982,12345 or Y
welcome_letter Applies only to new subscriber records. Specifies whether to send the new subscriber a welcome letter. If <doi>1</doi> is also included in the XML payload, the subscriber will receive the welcome letter after confirming the double opt-in request.
  • 0 – do not send a welcome letter (default)
  • 1 – send a welcome letter
 boolean No 1
doi Applies only to new subscriber records. Specifies whether to send the new subscriber a standard Opt-in confirmation email. Only when the message recipient confirms will the record be marked as a subscriber.
  • 0 – follow the account default setting for Double Opt-in (default)
  • 1 – send the Double Opt-in email regardless of the account's default setting
 boolean No 1
file_type Specifies the import file type. Acceptable values are:
  • comma – indicates that columns are separated by commas
  • tab – indicates that columns are separated by tabs
  • zipcomma – indicates that the file is a comma-delimited file that is ZIP compressed
  • ziptab – indicates that the file is a tab-delimited file that is ZIP compressed
  • gzipcomma – indicates that the file is a comma-delimited file that is GZIP compressed
  • gziptab – indicates that the file is a tab-delimited file that is GZIP compressed
  • custom – indicates that columns are separated by a custom delimited specified by the <custom_delimiter> element (see below).
 string Yes ziptab
number An integer that indicates the number of data columns within the file number Yes 13
source A text string that indicates where the list came from. This will only be applied to new subscribers and it will be available to them for spam complaint prevention. string Yes These subscribers dropped their business card in a fishbowl.
custom_delimiter A text character indicating the custom text delimiter being used. string Conditional; required if <file_type>custom</file_type> is included in XML payload |
data_url The URL of the data source located on the Internet. Allowable file extensions are .txt, .csv or .zip string Conditional; required if not using FTP as the transfer protocol https://www.mysite.com/data/segment5.csv
ftp_server IP address or host name of your FTP server string Conditional; required if file transfer is via FTP ftp.mysite.com
ftp_user_name FTP username string Conditional; required if file transfer is via FTP ftp_user
ftp_user_pass FTP password string Conditional; required if file transfer is via FTP ftp_pass
filename name of data file on FTP server (may include file path). Allowable file extensions are .txt, .csv or .zip string Conditional; required if file transfer is via FTP datafile.txt or /path/to_file/datafile.txt
sftp Indicator of whether connection is via the sFTP protocol where:
  • 0 – Do not connect via sFTP (default)
  • 1 – Connect via sFTP

NOTE: If both <sftp>1<sftp> and <ftp_ssl>1</ftp_ssl> are included in the XML payload, then the connection will be via sFTP protocol. If the sftp port is something other than 22, the port number should be specified in the ftp_server parameter preceded with a colon (e.g sftp.myftpserver.com:2222)

boolean No 1
ftp_ssl Indicator of whether FTP with a valid SSL certificate should be applied where:
  • 0 – Do not apply SSL certificate (default)
  • 1 – Apply SSL certificate
 boolean No 1

Response

Field Description Example
message A code indicating either a success or a failure of the bulk sync 1
task_id Use the value returned in this XML element as one of the input parameters for the utilities.getTasks method call in order to retrieve the current status of the bulk sync job. 123456
list_id This element only appears in the response message in the case of a successful bulk sync. It corresponds to the internal ID of the list that has been successfully loaded. 58605
reason This element only appears in the response message in the case of a failed bulk sync. It will contain a human-readable explanation of the reason for failure. file must contain email column

Response Codes

Response Code Response Text Description
201 Result: Submitted import (list ID <LIST_ID>) A successful submission of a file to be uploaded into your subscriber database.
401 invalid file_type variable The value of the <file_type> element is not one of the acceptable values.
402 data source not specified Elements specifying the location of the upload file are missing from the request.
403 filename or data_url not passed The <filename> element or the <data_url> element is missing from the request.
404 can't create folder There was a problem encountered when attempting to upload the file into Mapp.
405 not all variables passed through Incomplete set of elements included in the request that are necessary.
406 unique identifier feature must be enabled The data file included the external_id column header, but your account is not enabled for the Unique identifer feature.
407 Non integer values in clear_grp The <clear_grp> element included non-numeric values (other than the comma character, or the 'Y' character)
408 error in file upload process There was a problem encountered when attempting to upload the file into Mapp
409 Cannot create bulk_sync job, please try again later There was a problem encountered in the process.

Example Post

<methodCall>

<methodName>legacy.bulk_sync</methodName>

<reply_email>test@Mapp.com</reply_email>

<file_type>tab</file_type>

<number>3</number>

<source>Subscribed on-site</source>

<grp>1967,1966</grp>

<clear_grp>1966</clear_grp>

<welcome_letter></welcome_letter>

<doi></doi>

<data_url>https://www.mysite.com/list.txt</data_url>

</methodCall>

Example Response

Example response from a successful list load:

<methodResponse>

<item>

<methodName>legacy.bulk_sync</methodName>

<responseData>

<message>1</message>

<list_id>58605</list_id>

<task_id>123456</task_id>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>

Example Error

Example response from an unsuccessful list load:

<methodResponse>

<item>

<methodName>legacy.bulk_sync</methodName>

<responseData>

<message>2</message>

<reason>file must contain email column</reason>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>

Back to API Reference Guide