Rate this page:

Create and Manage Contacts

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.

Add Contacts

You can add contacts to Marketing Campaigns by uploading a CSV, manually via the UI, using a Signup Form, or by integrating with the Contacts API.

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.

Adding contacts may effect 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

A common way to add contacts is to upload a CSV and map your data to custom fields.

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

  1. Use this CSV template to make sure your CSV is formatted correctly.
  2. Click Add Contacts and then select Upload CSV.
  3. Choose whether to add your contacts to All Contacts, to an existing list, or to a new list you create.
  4. Upload your file by dragging it into or clicking the CSV upload area and selecting a file from your computer.
  5. Click Next: Review CSV Upload.
  6. On this page, all fields are listed and you can see which fields don't have a corresponding reserved or system field.
  7. For each unmapped field, select a custom field from the drop-down or to create a new custom field, click Create New Custom Field.
  8. When you're done mapping the fields, click Next: Add Contacts.

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

Add Manually

You can add your contacts manually including alternate email addresses, addresses and names from the Contacts page.

  1. Navigate to Marketing and then click Contacts.
  2. Select Add Contacts and then click on Manual Add in the drop down 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, and then any other information you may have.
  5. When you're done, click Add Contacts.

Create a signup form

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.

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 and select Signup Forms.
  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.

If a contact (defined by a unique email address) 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

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.

Manage signup forms

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

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.

Manage 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.

Viewing a contact

To view a specific contact profile, find the contact in one of your lists 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 in the Contact Fields tab to edit the contact's information within that section. This includes the Twilio 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.

Managing your list

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 senders list.

Identifying Suppressions

In your Twilio SendGrid Account are different Suppressions lists.

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 Bounce, invalid, Spam, and Unsubscribe list are automatically dropped by Twilio SendGrid. Feel free to remove these addresses from your lists to save money and time.

Delete unusable contacts

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, click the action menu in the upper right corner, then select Download as CSV.
  3. Repeat step 2 for each of the groups that you want to remove (unsubscribes, spam reports, etc.) and merge each of those lists into a single CSV file.
  4. Return to your dashboard, navigate to the left-hand menu and select Marketing, then Contacts.
  5. In the upper right corner click Add Contacts and select Upload CSV.
  6. Select Create New List and name it something obvious, like "Remove Invalid Emails."
  7. Once uploaded, click the action menu to the right of that new list and select Delete.
  8. Check the box indicating to delete "all contacts associated with this list."

Delete a specific contact

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.

There are two methods to delete contacts; one in which only a specific list or segment will be deleted and the contacts will remain in All Contacts, and the second in which you can delete a list or segment and ALL associated contacts.

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

To remove a list or segment, but keep the contacts in All Contacts:

  1. Navigate to your list or segment.
  2. Click the checkbox to the left of your list or segment.
  3. Click # selected dropdown and delete.

To remove a list or segment, and ALL associated contacts:

  1. Navigate to your list or segment.
  2. Hover over the Action menu to the right of the list or segment.
  3. Click on the trash icon.
  4. Check the box "Delete all contacts associated with this list from my account."
  5. Select delete.

To remove one or more contacts from a list:

  1. Navigate to the All Contacts list.
  2. Search for the contact you want to delete.
  3. Click delete to remove the contact permanently.

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

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 checkbox to confirm that you want to delete all contacts and then click Delete.

Edit or Remove Contacts from a list

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

To edit a contact:

  1. Navigate to the Contacts page and search for the contact you want to edit.
  2. Click the contact you wish to edit. This takes you to the contact details page.
  3. To edit any of the profile fields, click on the Edit 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 the Contacts page and search for the contact you want to edit.
  2. To delete a contact from the contact list, you can click the delete icon in the action menu. To delete a contact from the contact details page, click the delete icon at the top-right of the page.
  3. 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 the Contacts page and search for the contact you want to edit.
  2. Click the email of the contact to view contact details.
  3. Click the Associated Lists tab from the contact details page.
  4. Find the list you want to remove the contact from and click the delete icon.
  5. When you see "Are you sure you want to remove this contact?" click Remove Contact.

Contacts that are deleted from your SendGrid account are removed compliantly, according to GDPR. Click here for more information on GDPR.

Export contacts

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 the Contacts page within the Automation Beta experience.
  2. Locate the contact list you want to export and click the action menu.
  3. Select Export. The Export page appears with a list of all current and previous exports.
  4. From here you can find the exported contact list and select the action menu.
  5. Select the Download CSV icon next to the list to download the contact list to your computer.

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

Contact Management APIs

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.

Additional Resources

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more