You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/connections/sources/catalog/cloud-apps/sendgrid/index.md
+53-44Lines changed: 53 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,52 +3,63 @@ title: SendGrid Source
3
3
id: jhr8dT2yHn
4
4
---
5
5
6
-
[SendGrid](http://sendgrid.com){:target="_blank”} is a trusted platform for transactional email and email marketing.
6
+
[SendGrid](http://sendgrid.com){:target="_blank”} is a trusted platform for transactional email and email marketing.
7
7
8
-
Take your company's analysis to the next level by **adding SendGrid as a Source to Segment.** Segment automatically collects events like `Click` or `Delivered` and objects such as `Recipients` or `Campaigns` and loads them into your data warehouse.
8
+
Take your company's analysis to the next level by **adding SendGrid as a Source to Segment**. Segment automatically collects events like `Click` or `Delivered` and objects such as `Recipients` or `Campaigns` and loads them into your data warehouse.
9
9
10
-
## Getting Started
10
+
## Getting started
11
+
12
+
### Sendgrid API key
11
13
12
14
Adding SendGrid as a Source in Segment requires a SendGrid API key. If you don't yet have a SendGrid API key, first follow these steps within your SendGrid account:
13
15
14
16
1. Log in to your SendGrid account.
15
-
2. Navigate to **Settings > API Keys**, then click **General API Key**.
16
-
3. Name the key and, optionally, adjust its settings.
17
-
4.Copy the API Key, omitting all spaces.
17
+
2. Navigate to **Settings > API Keys**, then click **Create API Key**.
18
+
3. Name the key, configure the key permissions, and click **Create & View**.
19
+
4.Make note of the API key as it will not be shown again.
18
20
19
-
> info "SendGrid API Key Settings"
21
+
> info "SendGrid API key settings"
20
22
> Segment recommends providing read permissions for **Email Activity** and **Marketing Activity**.
21
23
22
-
To finish adding the SendGrid source, return to your Segment Workspace and follow these steps:
24
+
### Set up Sendgrid source
23
25
24
-
1. From the [Source catalog page](https://app.segment.com/goto-my-workspace/sources/catalog){:target="_blank”} in your Segment workspace, enter **SendGrid** and select the SendGrid source that appears.
25
-
2. From the SendGrid information panel that appears, click **Add source**.
26
-
3. Give the Source a name and add any labels to help you organize and filter your sources.
27
-
Segment recommends a name that reflects the source itself, as this name populates the schema name. For example, the source name `SendGrid` creates the schema `SendGrid`. You can add multiple instances if you have multiple SendGrid accounts.
28
-
4. Paste the SendGrid API Key you copied above into the Segment interface. Click **Connect**.
29
-
26
+
To add the Sendgrid source to Segment, return to your Segment Workspace and follow these steps:
30
27
31
-
6. Copy the auto-generated Webhook URL and paste it into SendGrid's Event Notification settings pane under **Settings > Mail Settings**.
28
+
1. Navigate to **Connections > Catalog**, and search for "Sendgrid".
29
+
2. Click the "Sendgrid" source and click **Add Source**. **Note**: This source only supports [warehouses](docs/connections/storage/warehouses/) as a destination.
30
+
3. Give the source a meaningful name and (optional) add any labels to help you organize and filter your sources. Select all of the Warehouse destinations from the existing connections.
31
+
> **Note**: Segment recommends that you give your source a name that reflects the source itself as this name populates the schema name. For example, the source name `SendGrid` creates the schema `SendGrid`. You can add multiple instances if you have multiple SendGrid accounts.
32
+
4. Add the [SendGrid API key](#sendgrid-api-key) to connect Sendgrid to Segment. Click **Connect**.
33
+
34
+
5. Copy the auto-generated Webhook URL from Segment and paste it in your Sendgrid account. Navigate to **Settings > Mail Settings > Event Webhooks** and create a new event webhook.
32
35
33
-
34
-
7. Enable Event Notification in SendGrid. Select **Next** and then **Finish** to complete setup.
36
+
6. Set up **Selective Sync**. You have the options to:
37
+
> ***Configure the source sync schedule**. This is how often the data syncs. The default option is every three hours.
38
+
> ***Select the start date**. This is the date from which the first sync happens. If left blank, a full sync is initiated.
39
+
> ***Select the collections to sync**. The collections that you select are synced from the start date.
40
+
7. Click **Finish** to complete connecting your Sendgrid source to Segment.
41
+
8. To set the date from which the sync should start, go to **Settings > Basic Settings**, and configure the start date. Some things to note:
42
+
> * Changing the start date after the first sync doesn't change anything unless a full manual sync is initiated.
43
+
> * Changing the collections to be synced takes effect after the next sync. The previous data synced for any collection that has been unselected is stored in the warehouse.
44
+
> * The default value for Source Sync Schedule in 3 hours. To change the sync schedule, send a message to [[email protected]](mailto:[email protected]){:target="_blank”}.
45
+
9. Toggle **Enable source** on to start syncing data.
46
+
10. The first sync begins after you successfully create the source. To review the collections and number of rows synced, go to the **Overview** tab.
35
47
36
48
### Event URL
37
-
38
-
SendGrid has a single Event URL location. By using the SendGrid source, you will be using your only Event URL location. If you remove a pre-existing URL, then that location will no longer receive events.
49
+
SendGrid has a single Event URL location. By using the SendGrid source, you'll use your only Event URL location. If you remove a pre-existing URL, then that location no longer receives events.
39
50
40
51
## Components
41
52
42
53
### Sync
43
54
44
-
Segment makes requests to the SendGrid API every three hours. In the initial sync, Segment pulls all SendGrid objects (and their corresponding properties) according to the [Collections Table](#collections) below. If you don't use SendGrid's marketing campaigns features (Legacy or New), these collections will be empty in SendGrid and you'll see "Zero data synced" in your runs. The webhook still processes activity data.
55
+
Segment makes requests to the SendGrid API every three hours. In the initial sync, Segment pulls all SendGrid objects (and their corresponding properties) according to the [Collections table](#collections). If you don't use SendGrid's marketing campaigns features (Legacy or New), these collections will be empty in SendGrid and you'll see "Zero data synced" in your runs. The webhook still processes activity data.
45
56
46
57
Segment's sync component pulls and forwards SendGrid resources to Segment using an upsert API. As a result, dimensional data loaded into your warehouse reflects the latest state of the corresponding resource in SendGrid. For example, if `lists.recipient_count` goes from `100` to `200` between syncs, its status will be `200` on its next flush to your warehouse.
47
58
48
-
The source syncs and warehouse syncs are independent processes. Source runs pull your data into the Segment Hub, and warehouse runs flush that data to your warehouse. Sources sync with Segment every three hours. Depending on your Warehouses plan, Segment pushes the Source data to your warehouse on the interval associated with your billing plan.
59
+
The source syncs and warehouse syncs are independent processes. Source runs pull your data into the Segment Hub, and warehouse runs flush that data to your warehouse. Sources sync with Segment every three hours. Depending on your Warehouses plan, Segment pushes the source data to your warehouse on the interval associated with your billing plan.
49
60
50
-
> info "SendGrid Syncs"
51
-
> Segment syncs all objects and properties. [Reach out to support](https://segment.com/help/contact/){:target="_blank”} if you're interested in filtering objects or properties during syncs.
61
+
> info "SendGrid syncs"
62
+
> Segment syncs all objects and properties. [Reach out to Segment support](https://segment.com/help/contact/){:target="_blank”} if you're interested in filtering objects or properties during syncs.
52
63
53
64
### Streaming
54
65
@@ -57,52 +68,50 @@ The SendGrid source's streaming component listens in real time for inbound webho
57
68
> info ""
58
69
> If you don't use SendGrid's marketing features, this will be the only data that Segment receives from SendGrid. There isn't a way to retrieve email event history from SendGrid, so you will only have access to data that Segment collected after you successfully enabled this integration.
59
70
60
-
61
71
## Collections
62
72
63
73
Collections are the groupings of resources Segment pulls from your source. In your warehouse, each collection gets its own table.
64
74
65
-
**Object** collections are updated with each sync. These are pulled using Segment's sync component.
66
-
67
-
**Event** collections are append only, represent a user action or activity, and may be likened to fact tables in a traditional data warehouse. Unlike traditional events captured by Segment, you can't forward these events to Destinations you've configured in your Segment workspace. You can only sync these events to a supported data warehouse.
75
+
-**Object** collections are updated with each sync. These are pulled using Segment's sync component.
76
+
-**Event** collections are append-only, represent a user action or activity, and may be likened to fact tables in a traditional data warehouse. Unlike traditional events captured by Segment, you can't forward these events to destinations you've configured in your Segment workspace. You can only sync these events to a supported data warehouse.
68
77
69
78
70
79
| Collection | Type | Description |
71
80
| ------ | ------ | ------ |
72
81
| activity | Event | The union of all SendGrid **event** tables. Useful for creating funnels. |
73
-
|_open| Event | Recipient has opened the HTML message. Enable Open Tracking to get this type of event. |
74
-
| click | Event | Recipient clicked on a link within the message. Enable Click Tracking to get this type of event. |
82
+
|open| Event | Recipient has opened the HTML message. Enable **Open Tracking** to get this type of event. |
83
+
| click | Event | Recipient clicked on a link within the message. Enable **Click Tracking** to get this type of event. |
75
84
| bounce | Event | Receiving server could not or would not accept message. |
76
85
| delivered | Event | Message has been successfully delivered to the receiving server. |
77
86
| processed | Event | Triggered when the email is processed. |
78
-
| dropped | Event | You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota |
87
+
| dropped | Event | You may see the following drop reasons: `Invalid SMTPAPI header`, `Spam Content` (if spam checker app enabled), `Unsubscribed Address`, `Bounced Address`, `Spam Reporting Address`, `Invalid`, `Recipient List over Package Quota`.|
| unsubscribe | Event | Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event. |
81
-
| mc_contacts | Object | A sample of fifty latest contacts uploaded or linked from the list, returned from [Sendgrid](https://docs.sendgrid.com/api-reference/contacts/get-sample-contacts){:target="_blank"}. **Will only return data if you're using SendGrid's New Marketing Campaign features.**|
82
-
| mc_lists | Object | Lists returned from [Sendgrid Lists endpoint](https://docs.sendgrid.com/api-reference/lists/get-all-lists){:target="_blank"}. **Will only return data if you're using SendGrid's New Marketing Campaign features.**|
83
-
| mc_single_sends | Object | Single Sends with condensed details about each from [Sendgrid Single Sends endpoint](https://docs.sendgrid.com/api-reference/single-sends/get-all-single-sends){:target="_blank"}. **Will only return data if you're using SendGrid's New Marketing Campaign features.**|
89
+
| unsubscribe | Event | Recipient clicked on message's subscription management link. You need to enable **Subscription Tracking** for getting this type of event. |
90
+
| mc_contacts | Object | A sample of fifty latest contacts uploaded or linked from the list, returned from [Sendgrid](https://docs.sendgrid.com/api-reference/contacts/get-sample-contacts){:target="_blank"}. **Only returns data if you're using SendGrid's New Marketing Campaign features.**|
91
+
| mc_lists | Object | Lists returned from [Sendgrid Lists endpoint](https://docs.sendgrid.com/api-reference/lists/get-all-lists){:target="_blank"}. **Only returns data if you're using SendGrid's New Marketing Campaign features.**|
92
+
| mc_single_sends | Object | Single Sends with condensed details about each from [Sendgrid Single Sends endpoint](https://docs.sendgrid.com/api-reference/single-sends/get-all-single-sends){:target="_blank"}. **Only returns data if you're using SendGrid's New Marketing Campaign features.**|
| lists | Object |[Groups of contacts](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html){:target="_blank”}. **Will only return data if you had Legacy Marketing Campaigns data**|
86
-
| segments | Object |[Slices of lists](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html){:target="_blank”}. **Will only return data if you had Legacy Marketing Campaigns data**|
87
-
| recipients | Object | All contacts who have received an email, with information about their last activities and custom activities. [More Info](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html){:target="_blank”}. **Will only return data if you had Legacy Marketing Campaigns data**|
88
-
| campaigns | Object | All campaigns you've created in SendGrid. [More Info](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.html){:target="_blank”}. **Will only return data if you had Legacy Marketing Campaigns data**|
94
+
| lists | Object |[Groups of contacts](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html){:target="_blank”}. **Only returns data if you had Legacy Marketing Campaigns data.**|
95
+
| segments | Object |[Slices of lists](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html){:target="_blank”}. **Only returns data if you had Legacy Marketing Campaigns data.**|
96
+
| recipients | Object | All contacts who have received an email, with information about their last activities and custom activities. For more information, see the [Sendgrid docs](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html){:target="_blank”}. **Only returns data if you had Legacy Marketing Campaigns data.**|
97
+
| campaigns | Object | All campaigns you've created in SendGrid. For more information, see the [Sendgrid docs](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.html){:target="_blank”}. **Only returns data if you had Legacy Marketing Campaigns data.**|
89
98
90
99
## Troubleshooting
91
100
92
-
### Invalid Credentials error
101
+
####Invalid credentials error
93
102
94
103
If you're getting an "Invalid Credentials" error when setting up the SendGrid source, send a direct ping to the [SendGrid Marketing Campaigns API](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.html){:target="_blank”} to test if you're using the correct credentials.
95
104
96
105
Make sure you allowlist Segment IP addresses on SendGrid. [Contact Segment](https://segment.com/help/contact/){:target="_blank”} for the list of IP addresses to allowlist.
97
106
98
-
### Webhook configuration
107
+
####Webhook configuration
99
108
100
-
When you disable your SendGrid source, you'll need to also disable the webhook portion of your configuration.
109
+
When you disable your SendGrid source, you also need to disable the webhook portion of your configuration.
101
110
102
-
If you are only able to create one webhook, review your SendGrid [account plan details](https://sendgrid.com/en-us/pricing). On the Sendgrid free plan, you can only have 1 webhook.
111
+
If you are only able to create one webhook, review your SendGrid [account plan details](https://sendgrid.com/en-us/pricing). On the Sendgrid free plan, you can only have one webhook.
103
112
104
-
### Zero data or partial data syncs
113
+
####Zero data or partial data syncs
105
114
106
115
If you haven't subscribed to SendGrid’s marketing campaign features, the object collections do not sync. As a result, you might see “Zero data synced” in your runs on Source Overview page. If you have only selected a few objects to be synced, then only those objects are synced and show up in the Source Overview.
107
116
108
-
In both cases, the webhook still processes event data and syncs it to the warehouse. To view the data synced to the warehouse, navigate to **Connections > Destinations**, select the relevant Warehouse Destination, and then select the Source schema.
117
+
In both cases, the webhook still processes event data and syncs it to the warehouse. To view the data synced to the warehouse, navigate to **Connections > Destinations**, select the relevant warehouse destination, and then select the source schema.
0 commit comments