Manage contacts

When you create a contact, it requires a unique identifier and it impacts your Twilio SendGrid limits, billing, and configured automations.

Each contact requires a unique identifier assigned to it. Twilio SendGrid supports setting one of the following four fields as an identifier for a contact. The chosen identifier must be unique among all contacts in your account. If you provide more than one identifier, only one of those identifiers must be unique.

• Email. Primary email address that your contact uses.

  This serves as the default contact identifier as every Twilio SendGrid contact requires an email address.

• Phone Number ID. Primary phone number that your contact uses.

  The Phone Number ID field differs from the existing Phone Number field.

  View the differences between these fields

  You can store the same value in both fields but that's not required.

• External ID. An identifier that links with data stored in an external system.

  • Twilio provides this ID for flexibility in your use cases.

• Anonymous ID. An identifier that link an anonymous contact with data stored in an external system.

  • Twilio provides this ID for flexibility in your use cases.

• Adding contacts might affect your Twilio SendGrid bill.
• Deleting and re-adding contacts counts toward your monthly limit of added contacts.

• Twilio triggers automations only for contacts that you added to an entry criteria list after you activated the automation.
• Contacts added to a list before you activate the automation don't receive any email messages in the series.

To add contacts to Marketing Campaigns, choose from these four methods:

1. Upload multiple contacts listed in a CSV file.
2. Add one at a time from the Twilio SendGrid console.
3. Create and deploy a signup form.
4. Use the Contacts API.

To add multiple contacts at a time, upload a comma-separated value (CSV) file. These CSV files can contain a maximum of one million contacts or 5 GB in file size, whichever is less.

1. Download this CSV template. It ensures the correct format for your import.
2. Log in to the Twilio SendGrid console if needed.
3. Go to Marketing > Contacts in the Twilio SendGrid console.
4. From the Add Contacts menu, select Upload CSV.
5. A page displays where you can choose where you want to add your contacts:
   • All Contacts
   • To an existing list
   • To a new list you create
6. Upload your CSV file using one of two options:
   • Drag and drop it onto the upload box.
   • Click the select a CSV file to upload.
7. Click Next: Review CSV Upload.
8. Another page displays that lists all fields related to your contacts. This displays fields without a corresponding reserved or system field.
9. With each unmapped field, choose one of three options:
   1. Select a custom field from the drop-down.
   2. Click Create New Custom Field for a new custom field.
   3. Choose Skip Column for any fields you don't want to map.
10. When you're done mapping the fields, click Next: Add Contacts.
11. This queues your contacts for upload. Added contacts might take some time to display depending on the number of contacts added.
12. After Twilio processes the CSV file, it sends you a notification email.

You can add your contacts from the Contacts page.

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Contacts in the Twilio SendGrid console.
3. Click Add Contacts then select Manual Add.
4. Choose where you want to add your contacts:
   • All Contacts
   • To an existing list
   • To a new list you create
5. Add your contact's email address and any other data you possess.
6. Click Add Contacts.

To capture contacts and add them to Marketing Campaigns, create, then embed, signup forms. You can create up to 15 signup forms.

To create a signup form in the Twilio SendGrid console:

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Signup Forms.
3. Click Create a Signup Form. A page displays with configuration tabs and a preview of the form.
4. On the Settings tab, add a Form Name.
5. You can populate the Add contacts to field with any of your contacts lists, including All Contacts.
6. Add a Confirmation Message. This field contains the text that contacts will see once they've submitted the form.
7. To add fields to the form, go to the Build tab.
   • To label your form, set a Header and any Intro Copy that might help customers understand the purpose of your form.
   • To set tracking data, add Reserved Fields and Custom Fields to the form.
     • Expand the Reserved Fields and Custom Fields menus then select any fields you want to include.
     • The selected fields display in the form preview beside the Build tab. If a contact exists in your contact database, any added or updated data gets added to or changed in that existing contact.
8. To change the look of your form, use the Styles tab. From this tab, you can modify fonts, colors, button styles, and the form's width.
9. Select Save & Apply.

To share a form, either embed it into your own web pages or send a direct link to the form to your customers. Twilio SendGrid hosts the link. If you choose to embed your form, it displays within an <iframe> HTML tag.

To share the code for your signup form:

1. Log in to the Twilio SendGrid console if needed.
2. Go to the signup form you want to share or embed.
3. Click the Action menu (⋮) then select Share Code.
4. A modal opens where you can copy how to get to reach your form:
   • Landing Page. A direct link to the Twilio SendGrid-hosted form that you can paste anywhere, including in an email or on a social media site.
   • Direct Embed. Embeddable <iframe> HTML code that you can paste into the HTML of your website wherever you want to display the form.

To find and view a specific contact profile:

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Contacts. You can also search a specific list or your All Contacts list.
3. Type the identifier into the Search by identifier field.
   • Search terms are case insensitive.
   • Partial search terms require a minimum of three characters from the beginning of the identifier.
4. Click Search (🔍).
5. From the search results, click the contact's identifier. The Contact Details page for that contact appears.

The Contact Details page includes three tabs: Reserved Fields, Custom Fields, and Associated Lists filled with the related data. You can filter custom fields using these data types: Text, Date, and Number.

Contact details include the Twilio SendGrid-provided reserved fields, any custom fields you've added for the contact, and any associated contact lists.

To edit a contact:

1. View the contact as described in Find a contact.

2. Click the tab with the data you want to edit:

   Reserved FieldsCustom FieldsAssociated Lists

   3. Go to Marketing > Contacts.

   4. Search for the contact you want to edit.

   5. Click the identifier of the contact you wish to edit. That contact's Contact Details page displays.

   6. Click the Reserved Fields tab.

   7. Click ✎ Edit. The Edit Reserved Fields panel appears.

   8. Edit any of the displayed fields, except Email. That field is both required and immutable.

      View the list of fields

   9. Accept or decline your changes:

      • To accept the changes, click Save.
      • To decline the changes, click Cancel. The Edit Reserved Fields panel closes.

Sending to a well-managed address list improves successful message deliveries. List maintenance involves identifying and removing contacts flagged as undeliverable or unwanted.

When an email sender like Twilio SendGrid chooses not to send an email message to a specific email address, they suppress that email address. Twilio SendGrid adds contacts to one of several different suppression lists based on reasons that the recipient or recipient system provide:

• The receiving email server or ISP rejects, or blocks, an email message. This might occur because the recipient has a full mailbox or the server received too many messages too quickly.
• The receiving email server bounces the email message. This might occur for reasons like the following:
  • The recipient's address is invalid.
  • The domain name doesn't exist.
  • The recipient is unknown.
• The recipient chose to unsubscribe from your email marketing.
• The recipient gave an invalid email address.
• The recipient reported your email message as spam.

When you attempt to send email messages to addresses listed in the Bounces, Invalid, Spam Reports, Group Unsubscribes, and Global Unsubscribes suppression lists, Twilio SendGrid supresses that attempt. You can and should delete these email addresses from your lists.

When you attempt to send an email to a suppressed address, the attempt consumes one email message attempt from your account quota.

As your campaigns continue, contacts might fall into a group unsubscribe, block, bounce, invalid email address, or spam report status. If you attempting to send email to these contacts, your reputation score decreases. These contacts don't want to and can't receive your marketing emails. Removing suppressed contacts involves downloading and aggregating all suppression lists into a single CSV, uploading that CSV as an additional list, then deleting that list.

To remove all of your suppressed Marketing Campaigns contacts:

1. Log in to the Twilio SendGrid console if needed.
2. Click Suppressions.
3. For every link under Suppressions, export the displayed list as a CSV file.
   1. Click the Action menu (gear wheel).
   2. Select Export CSV.
   3. Save each CSV file to the same directory on your computer.
4. Merge the downloaded lists into a single CSV file using the software of your choice outside the Twilio SendGrid console.
5. Go to the left-hand menu, then select Marketing > Contacts.
6. Click Add Contacts, then select Upload CSV. The Upload CSV page appears.
7. Click Add Contacts to a new list. Type a memorable name for this new list like Remove Invalid Emails.
8. Upload your CSV file in one of two ways:
   1. Drag and drop your CSV file into the upload box.
   2. Click select a CSV file to upload then Next: Review CSV Upload.
9. Map fields to the columns for your contacts.
   • Select a custom field from the drop-down.
   • Choose Skip Column for any fields you don't want to map.
   • The CSV reports return fields without pre-existing columns such as reason. Choose Skip Column for these fields.
10. Click Next: Add Contacts.
11. Twilio adds your contacts to the created list. This may take some time depending on the number of contacts.
12. Once you populate your list with these contacts, the Marketing > Contacts page shows a Count for that list.
13. Click the Action menu (⋮) next to your created list then select Delete This List.
14. A confirmation modal appears and asks if you want to delete the list by itself or the list with its associated contacts.
15. Select all <Number> contacts associated with this list.
16. The confirmation button changes. Click Delete This List and All <Number> Contacts.
17. Twilio queues this list and all associated contacts for deletion. Your contact count may take some time to update.

Separate from list maintenance, you might remove one or more contacts in response to a change in marketing strategy.

To delete a contact from your account:

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Contacts.
3. Go to the All Contacts list.
4. Search for the contact you want to delete. The contact should display in the list.
5. Choose how you want to delete the contact:
   • Click Delete This Contact next to the contact.
   • Click the link on the contact's identifier. That contact's Contact Details page appears.
     • Click Delete Contact.
6. A confirmation modal appears: Are you sure you want to delete this contact?.
   • To delete the contact from your account, click Delete This Contact.
   • To keep the contact in your account, click Cancel.

In compliance with the GDPR, Twilio deletes the contact from your account.

To delete permanently all of your contacts from your account at once:

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Contacts.
3. Click the Action menu (⋮) next to the All Contacts list.
4. Select Delete All Contacts. A confirmation modal appears: Are you sure you want to delete all contacts?.
5. To confirm the deletion, type Delete All Contacts in the form box. This turns on the Delete All Contacts button.
6. Click Delete All Contacts.

The Action menu (⋮) on the Signup Forms page provides the following options.

• Preview
• Edit
• Share Code
• Duplicate
• Delete

As <iframe> technology displays the signup form, the form updates its display anywhere you embed the form each time you click Save & Apply.

Sending to a well-managed address list improves successful message deliveries.

To create a contact list:

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Contacts.
3. Choose New List from the Create menu.
4. Type a name for this list in the List Name box.
5. Click Save List.

To add a contact to a contact list:

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Contacts and search for the contact you want to add to a list.
3. Click the identifier of that contact. This displays that contact's Contact Details page.
4. Click the Associated Lists tab.
5. Click Add to List. The Add to List panel appears.
6. Click the Select a List menu.
7. Click your desired list.
8. Click Add.

To remove a contact from a contact list:

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Contacts and search for the contact you want to remove from a contact list.
3. Click the identifier of the found contact. This displays that contact's Contact Details page.
4. Click the Associated Lists tab.
5. Find the list from which you want to remove from the contact.
6. Click Remove from list (trash icon) next to that list. A confirmation modal appears: Are you sure you want to remove this contact from this list?.
7. Click Remove List.

This dissociates the contact with the specified list.

When deleting a contact list, the console offers two options:

1. Delete a list and retain the contacts in your account. This removes a list with no impact to its contacts.
2. Delete a list and delete all of its associated contacts from your account. This removes the list and its associated contacts from your account.

To delete a contact list:

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Contacts in the Twilio SendGrid console.
3. From the Action menu (⋮), select Delete This List.
4. A confirmation modal appears: Are you sure you want to delete this list? offering two choices:
   • Only delete this list and keep contacts associated with this list
     1. To delete the list only but retain its associated contacts in your account, select this option.
     2. Click Delete This List.
     3. The modal closes and removes the list.
   • Delete this list and permanently delete all <#> contacts associated with this list from my account
     1. To delete the list and its associated contacts from your account, select this option.
     2. Click Delete This List and All <#> Contacts.
     3. The modal closes and removes the list and its associated contacts.

To view the contents of a contact list, you can export the list to a CSV and download it to your computer.

1. Log in to the Twilio SendGrid console if needed.
2. Go to Marketing > Contacts.
3. Locate the contact list you want to export and click the Action menu (⋮) next to the list.
4. Click Export.
   • This starts an export.
   • The Active Exports page displays with the following banner:
     Copy code block

     1
     You successfully initiated your export.
     2
     You'll receive an email notification when your export is ready to download.

   • When Twilio finishes building the export list:
     1. The Active Exports page refreshes with the export request displayed.
     2. Twilio sends you an email message.
5. If you left the Active Exports page, return to that page.
   • This page lists of all exports ready for download.
6. Locate your desired exported contacts list, then click Download CSV.

You can download the generated CSV files for 12 hours after you initiated the export.

You can use the Contact Management API for list management. To learn more, see the Marketing Campaigns Contact APIs.

• Custom fields
• Format a CSV file
• Segment your contacts