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
When Segment loads data into your warehouse, each sync goes through two steps:
2
+
1.**Ping:** Segment servers connect to your warehouse. For Redshift warehouses, Segment also runs a query to determine how many slices a cluster has. Common reasons a sync might fail at this step include a blocked VPN or IP, a warehouse that isn't set to be publicly accessible, or an issue with user permissions or credentials.
3
+
2.**Load:** Segment de-duplicates the transformed data and loads it into your warehouse. If you have queries set up in your warehouse, they run after the data is loaded into your warehouse.
{% include content/source-region-unsupported.md %}
6
6
7
-
SendGrid is a trusted platform for transactional email and email marketing.[Visit Website](http://sendgrid.com)
7
+
[SendGrid](http://sendgrid.com) is a trusted platform for transactional email and email marketing.
8
8
9
-
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 load them into your data warehouse.
9
+
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.
10
10
11
11
## Getting Started
12
12
13
-
1. From the [Source catalog page](https://app.segment.com/goto-my-workspace/sources/catalog) in your Segment workspace, enter "Sendgrid" and select the Sendgrid source that appears.
14
-
2. From the Sendgrid information panel that appears, click **Add source**.
13
+
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:
15
14
16
-
3. Give the Source a name and add any labels to help you organize and filter your sources.
17
-
You can give the source any name, but Segment recommends a name that reflects the source itself, as this name autopopulates the schema name. For example, the source name `Sendgrid` creates the schema `sendgrid`. You can add multiple instances if you have multiple SendGrid accounts.
15
+
1. Log in to your SendGrid account.
16
+
2. Navigate to **Settings > API Keys**, then click **General API Key**.
17
+
3. Name the key and, optionally, adjust its settings.
18
+
4. Copy the API Key, omitting all spaces.
18
19
19
-
4. Provide your API Key. In order to pull information about your contacts, we'll make requests to SendGrid's API with our [sync component](#sync). You can create an API Key by navigating to **Settings > API Keys**, clicking **General API Key**.
20
+
> info "SendGrid API Key Settings"
21
+
> Segment recommends providing read permissions for **Email Activity** and **Marketing Activity**.
20
22
21
-
You will then be prompted to name that key and given the option to adjust the settings. We recommend providing read permissions for **Email Activity** and **Marketing Activity**.
23
+
To finish adding the SendGrid source, return to your Segment Workspace and follow these steps:
22
24
23
-
6. Finally, copy the resulting API Key into the Segment interface, taking care to trim any errant trailing spaces from copying and pasting, and press connect.
25
+
1. From the [Source catalog page](https://app.segment.com/goto-my-workspace/sources/catalog) in your Segment workspace, enter **SendGrid** and select the SendGrid source that appears.
26
+
2. From the SendGrid information panel that appears, click **Add source**.
27
+
3. Give the Source a name and add any labels to help you organize and filter your sources.
28
+
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.
29
+
4. Paste the SendGrid API Key you copied above into the Segment interface. Click **Connect**.
30
+
24
31
25
-
32
+
6. Copy the auto-generated Webhook URL and paste it into SendGrid's Event Notification settings pane under **Settings > Mail Settings**.
33
+
26
34
27
-
7. Copy the auto-generated Webhook URL and paste it into SendGrid's Event Notification settings pane under **Settings > Mail Settings**.
28
-
29
-
30
-
31
-
8. Once you enable the Event Notification, you're good to go! Press **Next**, and then **Finish** to wrap up the set up flow.
35
+
7. Enable Event Notification in SendGrid. Select **Next** and then **Finish** to complete setup.
32
36
33
37
### Event URL
34
38
@@ -38,51 +42,54 @@ SendGrid has a single Event URL location. By using the SendGrid source, you will
38
42
39
43
### Sync
40
44
41
-
SendGrid has a sync component, which means we'll make requests to their API on your behalf on a 3 hour interval to pull the latest data into Segment. In the initial sync, we'll grab all the SendGrid objects (and their corresponding properties) according to the [Collections Table](#collections) below. **Note**: If you don't use Sendgrid's marketing campaigns features, these collections will be empty in Sendgrid and you'll see "Zero data synced" in your runs. The webhook will still be processing activity data (but only activity data) for you though!
45
+
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, these collections will be empty in SendGrid and you'll see "Zero data synced" in your runs. The webhook still processes activity data.
42
46
43
-
Our sync component gets resources from SendGrid and forwards them to Segment using an upsert API, so the dimensional data in your warehouse loaded will reflect the latest state of the corresponding resource in SendGrid. For example, if `lists.recipient_count` goes from `100` to `200` between syncs, on its next flush to your warehouse, that tickets status will be `200`.
47
+
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.
44
48
45
-
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 will sync with Segment every 3 hours. Depending on your Warehouses plan, we will push the Source data to your warehouse on the interval associated with your billing plan.
46
-
47
-
At the moment, we don't support filtering which objects or properties get synced. If you're interested in this feature, [let us know](https://segment.com/help/contact/)!
49
+
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.
48
50
51
+
> info "SendGrid Syncs"
52
+
> Segment syncs all objects and properties. [Reach out to support](https://segment.com/help/contact/) if you're interested in filtering objects or properties during syncs.
49
53
50
54
### Streaming
51
55
52
-
The SendGrid source also has a streaming component which listens in real time for inbound webhooks from SendGrid's Event Notifications and batches the events to be uploaded on your next warehouse flush. **These events only append to your warehouse.**
56
+
The SendGrid source's streaming component listens in real time for inbound webhooks from SendGrid's Event Notifications. The source batches these events for upload on your next warehouse flush. **These events only append to your warehouse.**
53
57
54
58
> note ""
55
59
> **NOTE:** 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 enable this component of the source destination.
56
60
57
61
58
62
## Collections
59
63
60
-
Collections are the groupings of resources we pull from your source. In your warehouse, each collection gets its own table.
64
+
Collections are the groupings of resources Segment pulls from your source. In your warehouse, each collection gets its own table.
61
65
62
66
**Object** collections are updated with each sync. These are pulled using Segment's sync component.
63
67
64
-
**Event** collections are append only, represent a user action or activity, and may be likened to fact tables in a traditional data warehouse. **Note:**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
+
**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.
65
69
66
70
67
71
| Collection | Type | Description |
68
72
| ------ | ------ | ------ |
69
-
| activity | Event | The union of all SendGrid **event** tables. Useful for creating funnels |
70
-
|_open | Event | Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event. |
71
-
| click | Event | Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event. |
73
+
| activity | Event | The union of all SendGrid **event** tables. Useful for creating funnels.|
74
+
|_open | Event | Recipient has opened the HTML message. Enable Open Tracking to get this type of event. |
75
+
| click | Event | Recipient clicked on a link within the message. Enable Click Tracking to get this type of event. |
72
76
| bounce | Event | Receiving server could not or would not accept message. |
73
77
| delivered | Event | Message has been successfully delivered to the receiving server. |
74
-
| processed | Event | Triggered when the email is processed |
78
+
| processed | Event | Triggered when the email is processed.|
75
79
| 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. |
| lists | Object |[Groups of contacts](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html). **Will only return data if you're using Marketing Campaign features of SendGrid.**|
80
-
| segments | Object |[Slices of lists](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html). **Will only return data if you're using Marketing Campaign features of SendGrid.**|
81
-
| 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). **Will only return data if you're using Marketing Campaign features of SendGrid.**|
82
-
| campaigns | Object | All campaigns you've created in Sendgrid. [More Info](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.html). **Will only return data if you're using Marketing Campaign features of SendGrid.**|
83
+
| lists | Object |[Groups of contacts](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html). **Will only return data if you're using SendGrid's Marketing Campaign features.**|
84
+
| segments | Object |[Slices of lists](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html). **Will only return data if you're using SendGrid's Marketing Campaign features.**|
85
+
| 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). **Will only return data if you're using SendGrid's Marketing Campaign features.**|
86
+
| campaigns | Object | All campaigns you've created in SendGrid. [More Info](https://sendgrid.com/docs/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.html). **Will only return data if you're using SendGrid's Marketing Campaign features.**|
87
+
88
+
> info "SendGrid and Personas"
89
+
> SendGrid data is not available in Personas.
83
90
84
-
## Troubleshooting
91
+
## Troubleshooting
85
92
86
93
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) to test if you're using the correct credentials.
87
94
88
-
Make sure you whitelist the Segment IP addresses on Sendgrid. [Contact Segment](https://segment.com/help/contact/) for the list of IP addresses to whitelist.
95
+
Make sure you allowlist Segment IP addresses on SendGrid. [Contact Segment](https://segment.com/help/contact/) for the list of IP addresses to allowlist.
**Note:** The enqueue method takes a `MessageBuilder` instance and not a `Message` instance directly. This is to allow you to use a `MessageTransformer` that applies to all incoming messages and transform or add data. <!-- LR: Can't find that we ever had a doc about this. Read more about it in the [transformer reference docs](/docs/connections/sources/catalog/libraries/server/java#transformer).-->
You should call `client.track(...)` and know that events will be queued and eventually sent to Segment. To prevent losing messages, be sure to capture any interruption (for example, a server restart) and call flush to know of and delay the process shutdown.
Short-lived functions have a predictably short and linear lifecycle, so use a queue big enough to hold all messages and then await flush to complete its work.
0 commit comments