# Sync Contacts with SendGrid

The [Sync Contacts with SendGrid Firebase extension](https://firebase.google.com/products/extensions/twilio-sendgrid-sync-contacts/) 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:

```js
admin.firestore().collection('contacts').add({
  email: 'someone@example.com',
  first_name: 'Bob',
  last_name: 'Bobson'
});
```

## Installation

You can install the extension using either the Firebase console or the [Firebase CLI](/docs/twilio-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)](https://firebase.google.com/pricing).

### Pre-installation

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](https://signup.sendgrid.com/)
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:

```bash
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](https://firebase.google.com/products/extensions) to find the *Sync Contacts with SendGrid extension*, or [install the extension directly here](https://console.firebase.google.com/u/0/project/_/extensions/install?ref=twilio%2Fsendgrid-sync-contacts). 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.

## Usage

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.

```js
{
  email: "test@example.com"
}
```

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](https://github.com/twilio-labs/twilio-firebase-extensions)

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!