Subscriber Opt-Out Import

The Subscriber Opt-Out Import file is used to opt-out SMS subscribers from an existing mobile subscription list. It should only be used to unsubscribe existing subscribers in the Vibes platform who have indicated that they would like to unsubscribe in another source. This bulk file import can be used during the onboarding process or for managing opt-outs from another source.


Confirmation messages using imports

This import will NOT send a confirmation of opt-out to the subscribers on this list. If you’d like to notify the subscribers that they have been unsubscribed, do not use the bulk opt-out import.

File Specifications

File Name

[file name].opt_outs

File Format

The contents of the file should be plain text separated by commas or another delimiter.

File Size

If you are uploading via the platform, we recommend files are less than 5MB, which is usually about 100,000 rows of data.

If you are uploading files via SFTP, there is no limit; however, larger files may take more time to upload.


You can include the following headers in your subscriber import. Using headers is optional.

Header NameDescription
Content-TypeValue should always be TEXT.
Subscription-List-IDIf not specified here, it must be specified in every row. Any value specified in the row takes precedence over the header value.
FieldsThis is a comma-separated list of field names 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.
DelimiterThe character used to delimit the columns. If omitted, it defaults to a comma.


In each row, at least one identifier needs to be specified. Available identifiers are person_id, external_person_id, person_key, vibes_device_id, or mdn. If more than one value is specified, we will use the value with the highest precedence.

The file body can contain the following fields as data. All field names must be lowercase.

Field NameData TypeDescription
person_idIntegerA Vibes-assigned number identifier, used to identify a person record that already exists in the Vibes system. First in precedence.
person_keyStringThe Vibes-assigned string identifying a person record that already exists in the Vibes system. The person_key must be lowercase. Second in precedence.
external_person_idStringThe external system's identifier of the person you’d like removed from the subscription list. Third in precedence.
mdnStringThe mobile phone number to remove from the subscription list. Fourth in precedence.

For non-US numbers, the MDN must be in E.164 format.
subscription_list_idStringThe subscription list from which you'd like to remove the person. If not specified, the subscription-list-id from the header will be used.
opt_out_dateStringAn ISO8601 formatted string (what we store as the opt-out date). If not specified, the current date/time will be used.

Example Files

Download example files here.