The SendGrid is a communication platform for transactional and marketing emails.
User Expectations
- User will retrieve API Keys (Restricted Access) from their SendGrid account for Event Notification, Marketing Campaigns, Suppressions and Tracking.
- User will enable Active Tracking in their account - Click, Open and Subscription tracking is enabled.
- Uses SendGrid v3 REST API and Webhooks to sync your data.
- Retrieves
- Marketing Campaigns
- Automation
- Single Sends
- Senders
- Contacts
- Segments
- Schedule *
- Stats
- Global Stats
- Category Stats
- Advanced Stats
- Suppressions
- Bounces
- Global Unsubscribes
- Group Unsubscribes
- Spam Reports **
- Blocks **
* is present as state in the list of Automation/Single Send, but could be parsed as separate list of both entities to represent the current schedule and be a dynamic entity
** currently no way to test or get info about those endpoints as for that, test account should have been reported for spam and have some blocks - Marketing Campaigns
User Configurations
Section | User Configuration Label | Label Description | Options | Default | Variable | User Widget |
|---|---|---|---|---|---|---|
| Standard | API Key | The SendGrid API Key taken from the SendGrid account of choice | sendgrid-api-key | Text Box | ||
| Username | Login name for Sendgrid | username | Text Box | |||
| Password | Login password for the username specified above | password | Text Box | |||
| Data Source | One of the above sources picked from list | data-source | List Box | |||
| Data Source Fields | List of fields to be retrieved | data-source-fields | Text Box | |||
| Start Date | (required by some SG API Endpoints) The date in format YYYY-MM-DD, starting from which the data is requested. | not set | start-date | TODO | ||
| End Date | (required by some SG API Endpoints) The date in format YYYY-MM-DD, the end date for the requested data | not set | end-date | TODO | ||
| Error Handling | On Record Error | How to handle error in record processing |
| Skip error | on-error | Radio Button (layout: block) |
Plugin Type
- Batch Source
- Batch Sink
- Real-time Source
- Real-time Sink
- Action
- Post-Run Action
- Aggregate
- Join
- Spark Model
- Spark Compute
Design Tips and references
SendGrid v3 API:
- https://sendgrid.api-docs.io/v3.0/
- https://sendgrid.com/docs/API_Reference/api_v3.html
SendGrid supports API v2 and v3 legacy and and SendGrid v3 API . As v2 and v3 legacy are outdated, we going to support and use the latest SendGrid v3 API.
Data source reference
Data sources description
| Field name | Type | Description |
|---|---|---|
Automation | ||
| id | string | |
| name | string | |
| status | string | |
| type | string | |
| message_count | number | |
| created_at | datetime | |
| updated_at | datetime | |
| live_at | datetime | |
SingleSends | ||
| id | string | |
| name | string | |
| status | string | |
| created_at | datetime | |
| updated_at | datetime | |
| is_abtest | boolean | |
Senders | ||
| id | string | |
| nickname | string | |
| address | string | |
| address_2 | string | |
| city | string | |
| country | string | |
| state | string | |
| zip | number | |
| locked | boolean | |
| created_at | datetime | |
| updated_at | datetime | |
| from_email | string | |
| from_name | string | |
| verified_status | string | |
| verified_reason | string | |
| reply_to_name | string | |
| reply_to_email | string | |
Contacts | ||
| id | string | |
| first_name | string | |
| last_name | string | |
| list_ids | list[string] | |
| created_at | datetime | |
| updated_at | datetime | |
| string | ||
Segments | ||
| id | string | |
| name | string | |
| parent_list_id | string | |
| created_at | datetime | |
| updated_at | datetime | |
| sample_updated_at | datetime | |
| contacts_count | number | |
GlobalStats | ||
| date | datetime | |
| metrics_blocks | number | |
| metrics_bounce_drops | number | |
| metrics_bounces | number | |
| metrics_clicks | number | |
| metrics_deferred | number | |
| metrics_invalid_emails | number | |
| metrics_opens | number | |
| metrics_processed | number | |
| metrics_requests | number | |
| metrics_spam_report_drops | number | |
| metrics_spam_reports | number | |
| metrics_unique_clicks | number | |
| metrics_unique_opens | number | |
| metrics_unsubscribe_drops | number | |
| metrics_unsubscribes | number | |
CategoryStats | ||
| name | string | |
| type | string | |
| date | datetime | |
| metrics_blocks | number | |
| metrics_bounce_drops | number | |
| metrics_bounces | number | |
| metrics_clicks | number | |
| metrics_deferred | number | |
| metrics_delivered | number | |
| metrics_invalid_emails | number | |
| metrics_opens | number | |
| metrics_processed | number | |
| metrics_requests | number | |
| metrics_spam_report_drops | number | |
| metrics_spam_reports | number | |
| metrics_unique_clicks | number | |
| metrics_unique_opens | number | |
| metrics_unsubscribe_drops | number | |
| metrics_unsubscribes | number | |
AdvancedStats | ||
| name | string | |
| type | string | |
| date | datetime | |
| metrics_clicks | number | |
| metrics_opens | number | |
| metrics_unique_clicks | number | |
| metrics_unique_opens | number | |
Bounces | ||
| created | datetime | |
| string | ||
| reason | string | |
| status | string | |
GlobalUnsubscribes (TODO) | ||
GroupUnsubscribes | ||
| id | string | |
| name | string | |
| description | string | |
| is_default | boolean | |
| last_email_send_at | datetime | |
| unsubscribes | number | |
SpamReports (TODO) | ||
Blocks (TODO) | ||
Schedule (TODO) | ||
Authorization
Plugin supporting Basic and API Key authorization, with using API Key by default when provided.
Rate limiting
SendGrid v3 API have an request rate limiting. # todo: what to do if the plugin will hit the rate limit?
Approach
TODO
UI Impact or Changes
TODO
Test Case(s)
TODO
Sample Pipeline
TODO