Adding Contacts

From our Contacts page, you can add, upload, modify, and delete your contacts. Contacts can be added to your contacts database using the API, or by manually adding or uploading a CSV file through the SendGrid App.

Your first 2,000 contacts are free. After 2,000 contacts, SendGrid charges $10 for every additional 10,000 contacts.

Formatting a CSV

You can easily add contacts to your contact database by uploading a CSV of your contacts to SendGrid. If you have your contacts in a spreadsheet, simply save that sheet as a .csv file using a spreadsheet application like Microsoft Excel or Google Sheets. You can also export your contacts from most database systems as a .csv file.

Your CSV file MUST be in UTF-8 format.

Your CSV should contain the following information about each contact:

  • email (required)
  • first_name
  • last_name

You can also include custom fields with additional identifying information for each contact in the CSV. For example, you can specify “country,” “city,” and “age” as the custom fields. The data in the custom fields are critical for both segmentation and content personalization.

The first row of your CSV must be a header row containing labels identifying each column. We have provided an example CSV file for you to look at. Headers must only use letters, numbers, and underscores. If you add custom field data to your CSV, you can save some time when uploading by naming the columns the same as the custom fields you have previously defined.

SendGrid identifies individual contacts by their email, so you must include email as one of the CSV headers. If you do not include the email column, SendGrid will not add any information to your contact database or list. Rows in your CSV without an email address in the email column will automatically fail, but will not cause the entire upload to fail.

Uploading a CSV

To add new contacts:

  1. Click Add Contacts and then select Upload CSV.
  2. Choose an existing list or create a new list to add the contacts to.

    If you choose to add the contacts without assigning them to a list, they are added to the contacts database without any additional context. All contact, regardless of whether or not they are added to a list exist in the contacts database once they have been uploaded.

  3. Upload your file by dragging it into or clicking the CSV upload area.

  4. Once the CSV has populated, click Next: Review CSV Upload.

    A page appears displaying the data from the header row from of the CSV file. From the list you can select a custom field to associate with the data in the column. If there isn’t a corresponding field, you can add one. Only the Email field is required to complete the upload. Skipped column headers are not uploaded and do not appear as custom fields within an individual contact’s profile.

  5. Select Skip Column to omit data from the contacts list.

  6. Once you’ve gone through all of the headers, click Save Contacts.

After uploading contacts, you can define segments for individual contacts or lists based on specified criteria. For more information, see Lists and Segmentation.

The maximum CSV file size is 2GB.

Once we have completed processing your new contacts, you will receive an email to any addresses specified under Notifications with the following information:

  • Total processed contacts
  • Number of new contacts
  • Number of updated contacts
  • Number of errors
  • Error messages for each errored row

If there are any errors, there will be a link to download a CSV containing the errored rows so that you can reformat and reupload those contacts. For more help resolving issues with uploading a CSV, see List Upload Troubleshooting.

The download link to your CSV of errored rows will be available for 24 hours.

If you upload the same contact more than once, SendGrid updates the data, assuming the most recent upload has the most up-to-date information. Updates to your contacts cannot be rolled back. Multiples of the same contact (as identified by email) can be added to different lists or segments and count as one contact against your total contacts per account or subuser account.

Manually Add a Contact

To manually add a contact to your contact database:

  1. Navigate to Marketing Campaigns and then click Contacts.
  2. In the top right-hand corner, click Add Contacts.
  3. Click Manual Add.
  4. Select the list you want to add the contact to from the drop-down, or select Add to New List and enter the name of the list.
  5. Enter the information for the new contact.
  6. Click Save.

To add Custom Field data to a manually imported contact, navigate to the Contact Details page of the new contact.

Managing Contacts

Managing contacts is an integral part of your marketing campaigns lifecycle. You can create lists for contacts, as well as view and edit each individual contact within your contact database.

Creating a New List

To create a new list from your CSV:

  1. Click Add Contacts and then select Upload CSV.
  2. Click +Add to New List and enter the name of the list you would like to create.
  3. Choose a CSV file for upload and complete the steps listed in Uploading a CSV .

Add Contacts to a List

To manually add contacts to a list:

  1. Navigate to Marketing Campaigns and then click Contacts.
  2. Locate the list you wish to edit and select the Action Menu next to the list name.
  3. Select Edit.
  4. Enter the information for the new contact.
  5. Click Save.

If you create a segment before you upload a list, any contact that fits the segment criteria you’ve defined will be added to that segment.

Viewing a Contact

To view a specific contact profile, find the contact in one of your lists or segments by searching your contact database. Then click the contact’s email address. You will then be able to view the email, engagement data, profile information, custom fields, and list associations for this contact.

Searches are case agnostic but must be done using a whole email address that includes an “@” and any top-level domain like “.com” or “.io”.

To view any custom fields you have assigned to this contact, or to view any lists that you have added this contact to, you may flip through the tabs beneath the Contact Details. You may either view all custom fields at once, or you can filter them by the following types: “Text”, “Date”, and “Number”.

Editing a Contact

When you are viewing a contact, click any of the Edit buttons to edit the contact’s information within that section. This includes the SendGrid provided reserved fields, except email, any custom fields you’ve added for this contact, and any lists the contact is associated with.

To edit the associated lists for your contact:

  1. Select the Associated Lists tab.
  2. Enter or select the list you would like to use.
  3. Click Add.

Delete a Specific Contact

To remove one or more contacts from a list:

  1. Navigate to the contact you wish to modify and click the Action Menu.
  2. Click Remove From List. This option removes the contact from the list. To remove the contact completely, select delete.

Delete All Contacts

To delete all of your contacts at once:

  1. Navigate to your Contacts page and hover over the Action Menu next to All Contacts.
  2. Click the trash can icon.
  3. Select the check box to confirm that you want to delete all contacts and then click Delete.

Additional Resources