Create and Manage Contacts

You can add contacts to Marketing Campaigns by uploading CSV files, working with the Twilio SendGrid user interface, deploying Signup Forms, and integrating with the Contacts API. Twilio SendGrid provides multiple ways to manage contacts so that you can interact with Marketing Campaigns in the way that best fits your needs. In order to add contacts, you need to provide one of the following identifiers for each contact:

• Email
• Phone Number ID
• External ID
• Anonymous ID

Uploading a CSV file to Marketing Campaigns is one of the most common ways to import contacts.

1. Use this CSV template to make sure your upload is formatted correctly.
2. Navigate to Marketing > Contacts in the Twilio SendGrid App.
3. Click Add Contacts on the top right corner of the page. Then, select Upload CSV from the menu.
4. A page will load where you can choose whether to add your contacts to All Contacts, an existing contacts list, or a new list you create.
5. Upload your CSV file by dragging and dropping it onto the upload box or by clicking the select a CSV file to upload.
6. Click Next: Review CSV Upload.
7. A new page will load where all fields related to your contacts are listed. You can see which fields don't have a corresponding reserved or system field.
8. For each unmapped field, either select a custom field from the drop-down or create a new custom field by clicking Create New Custom Field.
   1. You can also choose Skip Column for any fields you do not want to map to your contacts.
9. When you're done mapping the fields, click Next: Add Contacts.
10. Your contacts are now queued to be uploaded. Depending on the number of contacts you added, it may take some time before you see the new contacts in your account.

Once the CSV has processed, you will receive a notification email.

You can add your contacts manually from the Contacts page.

1. Navigate to Marketing > Contacts in the Twilio SendGrid App.
2. Click Add Contacts on the top right corner of the page. Then, select Manual Add from the menu.
3. Choose whether to add your contacts to All Contacts, to an existing list, or to a new list you create.
4. Add your contact's email address and any other information you have.
5. When you're done, click Add Contacts.

You can use Signup Forms to capture new contacts and add them directly to Marketing Campaigns. You can embed your forms directly into webpages using an <iframe>. Forms can also be shared using a Twilio SendGrid-hosted link, making them a great way to grow your lists by engaging customers wherever they are.

You can create as many as 15 Signup Forms, allowing you to deploy lists and segment contacts in the ways that best suite your business needs.

To create a new signup form:

1. Navigate to Marketing > Signup Forms in the Twilio SendGrid App.
2. Click Create a Signup Form.

Expand image

3. A page will load with configuration tabs and a preview of the form. On the Settings tab, add a Form Name.
4. You can populate the Add contacts to field with any of your contacts lists, including All Contacts.
5. Next, add a Confirmation Message. This field contains the text that contacts will see once they've submitted the form.

Expand image

6. Navigate to the Build tab to add fields to the form itself.

   • The Build tab allows you to label your form by setting a Header. You can also add any Intro Copy that might help customers understand the purpose of your form.
   • The Build tab also provides the opportunity to add Reserved Fields and Custom Fields to the form. This means you can collect helpful information about new contacts at the time of signup. Expand the Reserved Fields and Custom Fields menus, and select any fields you want to include — they will appear in the form preview beside the Build tab.

Expand image

7. You can change the look of your form using the Styles tab. In addition to modifying fonts and colors, you can change the button styles and the width of the form.
8. Once you are happy with the form, select Save & Apply.

Once your form has been created, you can share it by embedding it into your own webpages or by providing customers with a direct link to the form. The link is hosted by Twilio SendGrid. If you choose to embed your form, it will be hosted in an <iframe>.

To share the code for your signup form:

1. Navigate to the signup form you want to share or embed.
2. Click the action menu and select Share Code.

Expand image

3. A modal will open where you can copy either the direct link to the Twilio SendGrid-hosted form — titled, Landing Page — or the embeddable <iframe> code — titled, Direct Embed.

   • The Landing Page link can be pasted anywhere, including in an email or on a social media site.
   • The Direct Embed code can be pasted into the HTML of your website wherever you want to display the form.

Expand image

You can also find the options to share the signup form in the form editor by clicking Share Code in the top right corner of the editor.

Using the action menu on the Signup Forms page you can edit, duplicate, or delete existing signup forms.

Expand image

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 contacts database.

To view a specific contact profile, search your contact database from the search field on the Marketing > Contacts page in the Twilio SendGrid App. You can also search a specific list or your All Contacts list. Once you have located the contact, click the contact's identifier. You will be able to view the email, engagement data, profile information, custom fields, and list associations in a detail view for the contact.

To view any custom fields you have assigned to this contact, or to view any lists that you have added this contact to, you can flip through the Reserved Fields, Custom Fields, and Associated Lists tabs in the contact's detail view. You may view all custom fields at once, or you can filter custom fields by the following types: "Text", "Date," and "Number".

When viewing a contact, click the Edit button (pencil icon) to edit the contact's information. This includes the Twilio SendGrid-provided reserved fields, any custom fields you've added for the contact, and any lists the contact is associated with.

Identifier fields are reserved fields and are only editable via API to limit abuse of the Contacts system. To modify an identifier field from the UI, you are required to create a new contact with the updated identifier values. To modify an identifier via API, you will need to first delete the identifier using the Delete a Contact Identifier endpoint, then update the contact using the Update Contact endpoint.

To edit the associated lists for your contact:

1. Select the Associated Lists tab.
2. Click Add to list.
3. A menu will open where you can select one of your lists.
4. Click Add.

Each contact must have a unique identifier assigned to it. Twilio SendGrid supports the following identifier fields for a contact:

• Email. Primary email address for your Contact.
• Phone Number ID. Primary Phone Number used to identify a Contact.
• External ID. An identifier you can assign to a Contact that enables you to link it with data stored in an external system.
• Anonymous ID. An identifier you can assign to a Contact that enables you to link an anonymous Contact with data stored in an external system.

At least one identifier is required to be present in order to add a contact and the identifiers must be unique. Minimal data validation is done on External and Anonymous ID, as these are intended to be flexible in order to serve your use case.

Sending to a well-managed address list can drastically improve your delivery. We have put together some simple steps and guidelines that will improve any sender's list, including the process to delete lists, delete contacts from lists, and delete contacts from your account entirely.

• Suppressions
• Delete unusable contacts
• Delete a contacts list
• Delete all contacts

Twilio SendGrid provides several different Suppressions lists. A suppression is the action a sender takes when choosing not to send email to an address. This action is usually initiated when a recipient has unsubscribed from your messages or a recipient's email provider has rejected emails sent to the address.

• Global Unsubscribes - Addresses on this list are opted out of all mail.
• Bounces - Addresses that have failed to deliver to the recipient's inbox. Once an address has been added to this list, we do not attempt to deliver further messages to it. We will instead drop them to protect your external reputation.
• Spam Reports - Addresses that have marked your mail as spam.
• Blocks - Addresses that have blocked your mail temporarily, usually due to factors like a denied IP address. You can attempt to resend to these addresses.
• Invalid - Addresses on this list are malformed and do not have a valid email address structure. (Ex. info.sendgrid.com, info@sendgridcom, info @ sendgrid.com)

Emails sent to addresses listed in the Bounces, Invalid, Spam Reports, Group Unsubscribes, and Global Unsubscribes lists are automatically dropped by Twilio SendGrid. Feel free to remove these addresses from your lists to save money and time.

It is common to have contacts that result in a group unsubscribe, block, bounce, invalid email address, or spam report. Attempting to send email to these contacts can negatively impact your reputation since these contacts do not want to (and will not) receive your marketing emails.

To remove all of your unusable Marketing Campaigns contacts:

1. When viewing your dashboard, navigate to the left-hand menu and click Suppressions.
2. Open a specific group, such as Bounces or Spam Reports, and click the action menu (gear wheel) in the upper right corner. Then select Download as CSV.
3. Repeat the previous step for each of the groups that you want to remove and merge each of those lists into a single CSV file.
   1. You will merge the CSVs in your software of choice outside the Twilio SendGrid App.
4. Return to your dashboard, navigate to the left-hand menu, and select Marketing > Contacts.
5. In the upper right corner, click Add Contacts and select Upload CSV from the dropdown menu.
6. A new page will load where you can select Add Contacts to a new list. Name the new list something obvious to you like "Remove Invalid Emails."
7. Either drag and drop your CSV file into the upload box or select a CSV file to upload and click Next: Review CSV Upload.
8. You will now be asked to map fields to columns for your contacts. You may have fields without pre-existing columns such as reason that are returned in the CSV reports. Select Skip Column for these fields. Then, select Next: Add Contacts.
9. Your contacts will now be added to the new list. This may take some time depending on the number of contacts.
10. Once your list is populated with the contacts, you will see a Count associated with the list on the Marketing > Contacts page.
11. From the Marketing > Contacts page, click the action menu (three dots) to the right of your newly created list and select Delete This List.
12. A modal will load asking if you want to delete the list only or the list and its associated contacts. Check the box indicating you want to permanently delete "all <Number> contacts associated with this list."
13. Once you have selected the correct radio button in the modal, the confirmation button text will change to reflect your choice. Select Delete This List and All <Number> Contacts.
14. Your new list and all associated contacts will now be queued for deletion. Your contact count may take some time to update.

There are two options when deleting a contacts list. First, you may delete a list only but retain the contacts in your All Contacts list. This first option allows you to remove a list without further impact to the contacts associated with that list. Second, you may delete a list and all of its associated contacts from your All Contacts list. This second option removes not only the list but also its associated contacts from your account.

To delete a contact list:

1. Navigate to Marketing > Contacts in the Twilio SendGrid application.
2. Click the action menu (three dots) to the right of your list.
3. Click Delete This List from the menu that appears.
4. A dialog will then load asking if you want to delete the list only or the list and its associated contacts.
   1. To delete the list only but retain its associated contacts in your All Contacts list, check the box labeled Only delete this list and keep contacts associated with this list.
   2. To delete the list and permanently delete its associated contacts from your All Contacts list, check the box labeled Delete this list and permanently delete all <number> contacts associate with this list from my account.
5. Once you have checked the radio button that corresponds to your desired deletion behavior, you will see a delete button with one of the following text snippets: Delete This List or Delete This List and All <number> Contacts. Click this delete button.
6. The dialog will close and, depending on your selection, either the list or the list and its associated contacts will be removed.

1. Navigate to the All Contacts list from the Marketing > Contacts page in the Twilio SendGrid App.
2. Search for the contact you want to delete.
3. Click the Delete This Contact button (trash can icon) to the right of the contact.
4. A modal will load asking you to confirm the deletion. Select Delete This Contact to permanently delete the contact from your account.

To delete all of your contacts at once:

1. Navigate to Marketing > Contacts page in the Twilio SendGrid App.
2. Click the action menu (three dots) to the right of the All Contacts list.
3. A menu will display where you can select Delete All Contacts.
4. Once you select Delete All Contacts, a confirmation modal will load.
5. Type "Delete All Contacts" in the modal's form field to activate the Delete All Contacts button.
6. Select Delete All Contacts to permanently delete all contacts from your account.

To manage your contacts and lists more efficiently, you can edit your lists and contacts from the Contacts page.

To edit a contact:

1. Navigate to Marketing > Contacts page in the Twilio SendGrid App and search for the contact you want to edit.
2. Click the identifier of the contact you wish to edit. This takes you to the contact's detail page.
3. To edit any of the profile fields, click on the Edit button (pencil icon) to the right of the field.
4. Once you have finished making all of your changes, click Save.

To delete a contact from your account:

1. Navigate to Marketing > Contacts page in the Twilio SendGrid App.
2. Search for the contact you want to edit.
3. Once the contact is found, you can either click the Delete This Contact button. (trash icon) or click on the email address to see the contact's detail page. From the detail page, click the Delete button at the top-right of the page.
4. If you are deleting the contact from a specific list and not All Contacts, click Remove Contact. If you are deleting the contact from the account, select Permanently delete this contact from my account.

To remove a contact from a list:

1. Navigate to Marketing > Contacts page in the Twilio SendGrid App and search for the contact you want to edit.
2. Click the identifier of the contact you wish to edit. This takes you to the contact's detail page.
3. Click the Associated Lists tab.
4. Find the list you want to remove the contact from and click Remove from list (trash icon) to the right side of the list.
5. When you see "Are you sure you want to remove this contact?" click Remove List.
6. The contact will no longer be associate with the list.

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

To export contacts:

1. Navigate to Marketing > Contacts page in the Twilio SendGrid App.
2. Locate the contact list you want to export and click the action menu (three dots) to the right of the list.
3. Select Export. This will initiate an export.
   1. You will receive an email when your export is ready to be downloaded.
4. Navigate to the Active Exports page in the Twilio SendGrid App.
5. You will see a list of all current and previous exports that are ready for download.
6. From here, you can find the exported contacts list and select Download CSV.

You can integrate with the Contact Management APIs to create and update lists, add contacts, manage reserved field data, export contact lists, and pull data about your contacts and lists. Learn more through the documentation for the Marketing Campaigns Contact APIs.

• Custom Fields
• Formatting a CSV
• Segmenting your Contacts