Add contacts

Learn how to import existing contacts into Bird, or add new contacts manually.

Ways to add contacts to Bird

Bulk import new contacts from a CSV

You can manually import a large number of contacts into MessageBird by uploading a CSV file.

Step one: Format your CSV file

To ensure a smooth import, it's important to structure your CSV file correctly. We provide a demo file in the CSV importer that you can use as a template to ensure that your file is properly formatted.

At a minimum, your CSV file must include one identifier for each contact, such as a phone number or email address. You can also include any other non-identifier attributes you want to add to your contacts.

For our system to recognize identifiers, the identifier column names must be written as follows:

  • phone

  • email

Example CSV file formatting

If you format your CSV file like the one below, you will be able to successfully complete your import.

Note that not all fields are completed, but each contact has data in either the phone or email columns.





+44 7123 456789






+52 55 1234 5678

Step two: Upload your CSV file

  1. On the side panel, click Contacts. You'll be taken to the Contacts directory.

  2. Click Add Contact in the top right-hand corner, then click Import from CSV.

  3. Drag and drop your formatted CSV into the upload window, or click Browse to locate a file from your device.

  4. Next, review your CSV file.

  5. Click Next step.

Step three: Set subscription statuses for the new contacts you are importing

If the CSV file you're uploading contains the subscription statuses of your contacts, you do not need to take any action during this step. Jump ahead to add the contacts you are importing to a list.

If the CSV you're uploading doesn't contain subscription statuses, set them during this step.

  1. Make sure the 'Update subscription status for imported contacts' checkbox is selected.

  2. Select the checkboxes next to the channels that the contacts you are importing have opted-in to receive marketing messages on.

If the contacts in your CSV are not subscribed to receive any marketing messages, select the 'Import without updating subscription status' checkbox instead.

Your new contacts will still be imported, but you will not be able to send them marketing campaigns.

Step four: Add the new contacts you are importing to a list

By default, new contacts are assigned to a automatically-generated list. The name of this list contains the date and time of the import. For example: Import 2023-11-02 12:45:32 UTC.

If you don't want to add new contacts to the automatically-generated list, uncheck the box next to the list's name.

To add your imported contacts to a new list:

  1. Click Add list.

  2. Scroll past any existing lists to select Create " ".

  3. In the panel on the right-hand side, enter a List name and optional List description.

  4. Click Create.

  5. Click Finish. Your import will start.

To add your imported contacts to an existing list:

  1. Click Add list.

  2. Select a list from the dropdown.

  3. Click Finish. Your import will start.

You can add new imports to more than one list at a time, including the automatically-generated list, existing lists, and new lists. To do this, click Add list.

Step five: See the status of your CSV import

In the Imports tab, you can view all of the imports that have been performed.

Imports are listed with the following information:

  • File name

  • Lists the contacts were added to

  • Contacts that were skipped, updated, or had errors

  • Total number of contacts uploaded

  • Timestamp of when the import was created

To view more detailed information about a specific import job, click on its corresponding entry. This will bring up a panel on the right-hand side, showing:

  • Start import time

  • End import time

  • Status (e.g., completed)

Create an individual contact

Creating a contact manually is useful when you only have a few contacts to add.

  1. On the side panel, click Contacts, You'll be taken to the Contacts directory.

  2. Click the Actions button in the top right-hand corner, then click Create contact.

  3. Under "Identifier 1", select the identifier type from the drop-down menu (either phonenumber or emailaddress.

  4. In the "Identifier value" field, enter the phone number or email address of the contact (e.g.

  5. Optionally, you can add an additional identifier by clicking Add new identitifer.

  6. In the "Display name" field, enter the contact's name.

  7. Optionally, you can fill out the following attribute fields if you have the information:

    • First name

    • Last name

    • Avatar URL

    • Country

    • Locales

    • Gender

    • Custom attribute

  8. Click Create contact.

Last updated