Rate this page:

Sync Contacts with SendGrid

The Sync Contacts with SendGrid Firebase extension will automatically sync contact data to your SendGrid marketing campaigns contact list based on information from documents added to a specified Cloud Firestore collection.

Adding a document triggers this extension to add a contact to the Marketing Campaigns contact list. Updating a document will update the contact's data and deleting the document will trigger its removal from the contact list in SendGrid.

Here's an example document that would trigger this extension:

  email: '',
  first_name: 'Bob',
  last_name: 'Bobson'


You can install the extension using either the Firebase console or the Firebase CLI. To install or manage extensions, you must be assigned either the Owner, Editor or Firebase Admin role. Your Firebase project must also be on the Blaze (pay as you go plan).


Before you install the extension you will need to do the following:

  1. If you don't already have a SendGrid Marketing Campaigns account, sign up for a free account
  2. Create a SendGrid API key
    It needs to have permission to add contacts to the marketing campaign.
  3. Create a collection in Firestore for your contacts

    This extension listens for changes to documents in a Cloud Firestore collection that you specify. When it finds a new document, it creates a new contact in SendGrid, when a document is edited the contact is updated and when the document is deleted the contact is removed. You can use any Cloud Firestore collection for this purpose.

  4. Set up security rules for your contacts document collection.

    This extension can be used to create, update and delete contacts directly from client applications. However, you should carefully control client access to the collection to avoid potential abuse. Adding a contact to your list will trigger any automations you have set up for the list and you don't want users able to add new contacts to your without their permission.

    Security rules will vary from application to application, but you should always make sure that only contacts that have signed up to join your list are added to the collection.

Installation via the Firebase CLI

Make sure you have the latest version of the Firebase CLI and you have your Firebase project ID or alias to hand.

Run this command to install the extension:

firebase ext:install twilio/sendgrid-sync-contacts --project=projectId-or-alias

The command will prompt you for details like your SendGrid API Key and the name of a the Cloud Firestore collection you want to use.

Once installation is complete, check out the instructions below for how to use the extension.

Installation via the Firebase console

Visit the Firebase Extensions directory to find the Sync Contacts with SendGrid extension, or install the extension directly here. Click Install and follow the on-screen instructions to install the extension. The installation process will prompt you for the details you collected earlier, including your SendGrid API key and the name of your Cloud Firestore collection.


After installation, this extension monitors all document writes to the collection you configured. Contacts are added, updated, or deleted based on the contents of the document's fields.

Example: Add a new contact

To create a new contact with the minimal data, add a document to your messages collection with an email field.

  email: ""

You can add any of the following fields to your document and they will be applied to your contact:

Field Type
email string required
alternate_emails Array<string>
first_name string
last_name string
address_line_1 string
address_line_2 string
city string
postal_code string
state_province_region string
country string
phone_number string
whatsapp string
line string
facebook string
unique_name string
custom_fields Map<string, string>

custom_fields must be defined within your SendGrid account and are a map of the custom field's ID to the content.

Need further assistance?

Check out the GitHub repo

On GitHub, you can take a look at the source code, or read through the existing issues to see if somebody else had a similar problem. If you're still stuck, feel free to create a pull request or open an issue yourself!

Rate this page:

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        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