Skip to end of metadata
Go to start of metadata

Last Updated: Wednesday, April 15, 2020

A Recipient List is a collection of Person references that can be loaded into the Mobile Database and used as a target filter for Broadcast messages. The most common use case is when there is a Customer-defined CRM/targeting system that creates a targeted list of Broadcast recipients that needs to be loaded and used within Vibes Mobile Engagement Platform targeting.

Recipient Lists may be channel specific depending on the fields you upload. For example, if you upload a Recipient List with just person_id, person_key or external_person_id, it can be used on any channel. But, if you upload just an mdn, then it only works for an SMS/MMS channel; or, if you upload a vibes_device_id field, then it is for push only.

Recipient Lists can also include additional columns of data that can be used as message variables. For example, if you had a column titled “first_name”, you could pull that personalization value into a Broadcast or file triggered message.

Note: UTF-8 or ASCII encoding for integration files is recommended (UTF-16LE encoding is not supported).

File Name


File Format

The file format is a Comma-Separated Values (CSV) file. This stores tabular data (numbers and text) in plain text, where the line of the file is a data record. Each record consists of one or more fields, separated by commas.


You can include the following headers in your Recipient List.

Note: Using headers is entirely optional.

Header Name



Value should always be TEXT.


This is the list name that will be displayed in the User Interface. If omitted, a default value based on the filename will be used.


This is a comma separated list of the fields that will be in the body of the text file. If omitted, then the first row of the body must contain the field names, with the same delimiter as the body.

File Body

The file body can contain the following fields as data, separated by the delimiter.

Note: The field names must be lowercase.

Field Name

Data Type




The Mobile Database Person ID to include in the Recipient List. The person_id must be lowercase.



The Person Key is a UUID to include in the Recipient List. The person_key must be lowercase.

external_person_idStringThe external system's Person ID to include in the Recipient List.
vibes_device_idStringThe Vibes Device ID to include in the Recipient List. The vibes_device_id must be lowercase.



A Mobile Directory Number (mdn) is the mobile_phone number to include in the Recipient List.

  • For non-US numbers, the Mobile Directory Number (mdn) must be in E.164 format.




link to E.164 format: E.164 Support for Platform APIs

  • US numbers can use the 10-digit mdn format.



A custom field that can be used for Broadcast personalization.


  • "Custom" is not a specific string. It means that any custom field name may be used in the data file.
  • The header row must match the name of the custom field EXACTLY.

A custom string that can be used for targeting.

Note: You can only use the segment_code option in Broadcasts − it is not supported in File Triggered messages.
client_message_idStringA custom string that can be later tracked through exports from our data warehouse.

Identifying Persons
For a particular row, only one of person_id, external_person_id, person_key, or mdn need to be specified, as these are alternate means of referencing a Person. If more than one value is specified, we will use the value with the highest precedence. The precedence order is shown in the table above.

Error Messages

The following tables show the error codes that can occur when importing a file.

Row Level Errors

Error ClassError MessageDescription
RecipientListEntryErrors::DuplicatePersonIdduplicate person_idThe Recipient List already has a record with this person_id.
RecipientListEntryErrors::DuplicatePersonKeyduplicate person_keyThe Recipient List already has a record with this person_key.
RecipientListEntryErrors::DuplicateExternalPersonIdduplicate external_person_idThe Recipient List already has a record with this external_person_id.
RecipientListEntryErrors::DuplicateMDNduplicate mdnThe Recipient List already has a record with this mdn.
RecipientListEntryErrors::DuplicateVibesDeviceIdduplicate vibes_device_idThe Recipient List already has a record with this vibes_device_id.
RecipientListEntryErrors::InvalidPersonIdinvalid person_idThe person_id or person_key in this record doesn't point to a valid Person, or the person_id is formatted incorrectly.
RecipientListEntryErrors::InvalidMDNinvalid mdnThe mdn isn't a valid E.164 phone number.
PG::NumericValueOutOfRangeinteger out of rangeThe error message means the import has a number that’s too big for our database to handle.

File Level Errors

Error ClassError MessageDescription
A Recipient List with that name already exists.
RecipientListErrors::InvalidImportFileFormatCouldn't find a person_id, external_person_id, mdn, or vibes_device_id fieldYou must specify at least one field to identify the Person or device you wish to send to.
RecipientListErrors::InvalidImportFileFormatspecify an mdn, or a vibes_device_id, or neitherYou cannot specify both and mdn and vibes_device_id in the same file.
There are no valid entries in the file, so the Recipient List was not created.
You have too many unique values for the segment code. (max 100)

Common Errors

The following errors can occur in imports of all file types.

File Level Errors

Error Class

Error Message



Schema name for company <company_id> (is nil|was not found)The company that the file is target for is not set up in MobileDB, or there was some other system level error.

Example Files

See the attached files for some examples.

  File Modified
File just_external_id.recipient_list Jun 06, 2018 by dean.lappi
File just_mdn.recipient_list Jun 06, 2018 by dean.lappi
File mdn_personalizationfields.recipient_list Jun 06, 2018 by dean.lappi
File mdn_segmentcode.recipient_list Jun 06, 2018 by dean.lappi
File mdn_segmentcode_personalizationfields.recipient_list Jun 06, 2018 by dean.lappi
File custom_fields.recipient_list Dec 19, 2018 by dean.lappi
File full_defaults.recipient_list Dec 19, 2018 by dean.lappi
File minimal.recipient_list Dec 19, 2018 by dean.lappi
File minimal_with_quotes.recipient_list Dec 19, 2018 by dean.lappi
File no_header_row.recipient_list Dec 19, 2018 by dean.lappi

  • No labels