Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 20 Next »

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

User Configurations

Section

User Configuration Label

Label Description

Options

Default

Variable

User Widget

StandardAuthentication typeThe way, how user would like to be authenticated to the SendGrid acoount

Basic

Api Key

Basicauth-typeradio-group

API KeyThe SendGrid API Key taken from the SendGrid account of choiceShows if "Authentication type" is set to "apikey"
sendgrid-api-keytextbox

UsernameLogin name for SendGridShows if "Authentication type" is set to "basic"
usernametextbox

PasswordLogin password for the username specified aboveShows if "Authentication type" is set to "basic"
passwordpassword

Data Source TypesList of data source groups
  • Marketing Campaigns Fields
  • Stats Fields
  • Suppressions Fields

data-source-typesmulti-select

Data SourceOne of the above sources picked from list
  • Marketing Campaigns Fields
    • Automation
    • Single Sends
    • Senders
    • Contacts
    • Segments
  • Stats
    • Global Stats
    • Category Stats
    • Advanced Stats
  • Suppressions
    • Bounces
    • Global Unsubscribes
    • Group Unsubscribes

data-sourcemulti-select

Data Source FieldsList of fields to be retrievedsee "Data sources description" section below
data-source-fieldsmulti-select








Start Date(required by some SG API Endpoints)

The date in format YYYY-MM-DD, starting from which the data is requested.		Displayed depends on list of the selected data sourcesnot setstart-datetextbox

End Date(required by some SG API Endpoints)
The date in format YYYY-MM-DD, the end date for the requested data		Displayed depends on list of the selected data sourcesnot setend-datetextbox
Error HandlingOn Record ErrorHow to handle error in record processing
  • Skip error
  • Send to error port
  • Fail pipeline
Skip erroron-errorRadio 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

ObjectAPI ReferenceAPI PremissionsNotes
Automations-
No documentation available, but the usage could be revers engineered through debugging of official UI
Single Sendshttps://sendgrid.api-docs.io/v3.0/single-sends/get-all-single-sends

Senders-
No documentation available, but the usage could be revers engineered through debugging of official UI
Contactshttps://sendgrid.api-docs.io/v3.0/contacts/get-all-contacts

Segmentshttps://sendgrid.api-docs.io/v3.0/segmenting-contacts/get-list-of-segments

GlobalStatshttps://sendgrid.api-docs.io/v3.0/stats/retrieve-global-email-statistics

CategoryStatshttps://sendgrid.api-docs.io/v3.0/categories/retrieve-email-statistics-for-categories

AdvancedStatshttps://sendgrid.com/docs/API_Reference/Web_API_v3/Stats/advanced.html

Bounceshttps://sendgrid.api-docs.io/v3.0/bounces-api/retrieve-all-bounces

Global Unsubscribes-
No documentation available, but the usage could be revers engineered through debugging of official UI
Group Unsubscribeshttps://sendgrid.api-docs.io/v3.0/suppressions-unsubscribe-groups/retrieve-all-suppression-groups-associated-with-the-user

Spam Reportshttps://sendgrid.api-docs.io/v3.0/spam-reports-api/retrieve-all-spam-reports

Blockshttps://sendgrid.api-docs.io/v3.0/blocks-api/retrieve-all-blocks

Schedule-

Data sources description

Field nameTypeDescription

Automation

idstring
namestring
statusstring
typestring
message_countnumber
created_atdatetime

updated_atdatetime

live_atdatetime

SingleSends

idstring
namestring
statusstring
created_atdatetime
updated_atdatetime
is_abtestboolean

Senders

idstring
nicknamestring
addressstring
address_2string
citystring
countrystring
statestring
zipnumber
lockedboolean
created_atdatetime
updated_atdatetime
from_emailstring
from_namestring
verified_statusstring
verified_reasonstring
reply_to_namestring
reply_to_emailstring

Contacts

idstring
first_namestring
last_namestring
list_idslist[string]
created_atdatetime
updated_atdatetime
emailstring

Segments

idstring
namestring
parent_list_idstring
created_atdatetime
updated_atdatetime
sample_updated_atdatetime
contacts_countnumber

GlobalStats

datedatetime
metrics_blocksnumber
metrics_bounce_dropsnumber
metrics_bouncesnumber
metrics_clicksnumber
metrics_deferrednumber
metrics_invalid_emailsnumber
metrics_opensnumber
metrics_processednumber
metrics_requestsnumber
metrics_spam_report_dropsnumber
metrics_spam_reportsnumber
metrics_unique_clicksnumber
metrics_unique_opensnumber
metrics_unsubscribe_dropsnumber
metrics_unsubscribesnumber

CategoryStats

namestring
typestring
datedatetime
metrics_blocksnumber
metrics_bounce_dropsnumber
metrics_bouncesnumber
metrics_clicksnumber
metrics_deferrednumber
metrics_deliverednumber
metrics_invalid_emailsnumber
metrics_opensnumber
metrics_processednumber
metrics_requestsnumber
metrics_spam_report_dropsnumber
metrics_spam_reportsnumber
metrics_unique_clicksnumber
metrics_unique_opensnumber
metrics_unsubscribe_dropsnumber
metrics_unsubscribesnumber

AdvancedStats

namestring
typestring
datedatetime
metrics_clicksnumber
metrics_opensnumber
metrics_unique_clicksnumber
metrics_unique_opensnumber

Bounces

createddatetime
emailstring
reasonstring
statusstring

GlobalUnsubscribes (TODO)







GroupUnsubscribes

idstring
namestring
descriptionstring
is_defaultboolean
last_email_send_atdatetime
unsubscribesnumber

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

  • No labels