Skip to contentSkip to navigationSkip to topbar
On this page

Create and Manage Contacts


(information)

Info

The content on this page describes the experience in the latest version of Marketing Campaigns. If you're using the legacy version of Marketing Campaigns, your experience may be different. To explore Marketing Campaigns plans and upgrade, click here(link takes you to an external page).


Add Contacts

add-contacts page anchor

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
(information)

Info

Note that automations will only trigger to contacts who are added to an entry criteria list after the automation is set live. Contacts who you add to a list before the automation is set live will not receive any emails in the series.

(warning)

Warning

Adding contacts may affect your Twilio SendGrid bill. Be aware that deleting and re-adding contacts will count toward your monthly allotment of added contacts. For more information about how your contact count will impact your bill, see "Understanding Contact Counts in Marketing Campaigns" in the Twilio SendGrid Billing docs.

Upload a CSV

upload-a-csv page anchor

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

(information)

Info

You can upload a CSV containing up to 1M contacts or 5GB of data, whichever is less.

  1. Use this CSV template(link takes you to an external page) to make sure your upload is formatted correctly.
  2. Navigate to Marketing > Contacts(link takes you to an external page) 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(link takes you to an external page) 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(link takes you to an external page) to capture new contacts and add them directly to Marketing Campaigns. You can embed your forms directly into webpages using an <iframe>(link takes you to an external page). 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.

(information)

Info

If you add contacts using a list that's acting as the entry criteria for a live automation, the new contacts will automatically receive any emails you've created as part of that automation.

To create a new signup form:

  1. Navigate to Marketing > Signup Forms(link takes you to an external page) in the Twilio SendGrid App.
  2. Click Create a Signup Form.
The Signup Forms page with a 'Create a Signup Form' button.
  1. A page will load with configuration tabs and a preview of the form. On the Settings tab, add a Form Name.
  2. You can populate the Add contacts to field with any of your contacts lists, including All Contacts.
  3. Next, add a Confirmation Message. This field contains the text that contacts will see once they've submitted the form.
The Signup Forms page with the Settings tab open.
  1. 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.
The Signup Forms page with the Build tab open. Two custom fields are selected and showing in the form preview.
(information)

Info

If a contact (defined by a unique identifier) already exists in your contact database, any new or updated data will be reflected on that existing contact.

  1. 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.
  2. Once you are happy with the form, select Save & Apply.

Share Code to make your form accessible

share-code-to-make-your-form-accessible page anchor

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.
The action menu (three dots) open with the 'Share Code' menu item highlighted.
  1. 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.
The signup form's share modal.

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.

Action menu for signup forms'.
(information)

Info

Because of the <iframe> technology used to create the signup form, the form dynamically updates on the page or pages where you have the form embedded anytime you edit a form and click Save & Apply.


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(link takes you to an external page) 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.

(information)

Info

Searches are case-agnostic and can be done on any identifier. Partial values of identifiers are allowed with the following limitations:

  • At least three characters are required
  • Only characters at the beginning of the identifier are searchable

For example, to search for myemail@sendgrid.com, mye is an acceptable search but mai is not.

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.

(information)

Info

The Phone Number ID field is different from the existing Phone Number field. The Phone Number ID field must be unique and can act as an identifier for a contact while the Phone Number field cannot. The Phone Number field is treated as a reserved field and does not need to be unique. You can store the same data in both fields but it is not required that you do so. Make sure to format the Phone Number ID field as a phone number.

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.

Identifying Suppressions

identifying-suppressions page anchor

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.

(warning)

Warning

Each email you attempt to send to a suppressed address will consume one email from your account.

Delete unusable contacts

delete-unusable-contacts page anchor

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.

(warning)

Warning

Be aware that deleting and re-adding contacts will count toward your monthly allotment of added contacts. For more information about how your contact count will impact your bill, see "Understanding Contact Counts in Marketing Campaigns" in the Twilio SendGrid Billing docs.

(warning)

Warning

When you delete a contact, all stats related to that contact will also be removed.

To delete a contact list:

  1. Navigate to Marketing > Contacts(link takes you to an external page) 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.
(warning)

Warning

You can permanently delete contacts from your account when deleting a contact list. However, this same functionality is not available when deleting a segment. If you wish to delete a segment and permanently delete its associated contacts, you must delete the contacts from your account in addition to deleting the segment. See our segmentation docs for more about working with segments.

Delete individual contacts from your account

delete-individual-contacts-from-your-account page anchor
  1. Navigate to the All Contacts(link takes you to an external page) 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.
(warning)

Warning

Use this to permanently delete your recipients from all of your contact lists and all segments if required by applicable law.

To delete all of your contacts at once:

  1. Navigate to Marketing > Contacts(link takes you to an external page) 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.

Edit or Remove Contacts from a list

edit-or-remove-contacts-from-a-list page anchor

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(link takes you to an external page) 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(link takes you to an external page) 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(link takes you to an external page) 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.
(information)

Info

Contacts that are deleted from your SendGrid account are removed compliantly, according to GDPR. Click here(link takes you to an external page) for more information on GDPR.


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(link takes you to an external page) 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(link takes you to an external page) 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.
(warning)

Warning

Exported CSV files are only available for download for 72 hours after the export is initialized.


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.


Need some help?

Terms of service

Copyright © 2024 Twilio Inc.