SendGrid v1.1.0

About the connector

SendGrid is a cloud-based SMTP provider that allows you to send email without having to maintain email servers.

This document provides information about the SendGrid Connector, which facilitates automated interactions, with a SendGrid server using FortiSOAR™ playbooks. Add the SendGrid Connector as a step in FortiSOAR™ playbooks and perform automated operations such as sending an email using SendGrid, retrieving an array of all of your contact lists from SendGrid, or generating a new batch ID in SendGrid.

Version information

Connector Version: 1.1.0

Authored By: Community

Certified: No

Release Notes for version 1.1.0

Following enhancements have been made to the SendGrid connector in version 1.4.0:

• Added support for Email Templates in the action Send Email (only available in FortiSOAR™ v7.6.5 and later).

• Added a new parameter Body Type for the action Send Email with the following options:

  • Rich Text
  • Email Template

  Installing the connector

  Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

  You can also use the yum command to install the connector:

  sudo sudo yum install cyops-connector-sendgrid

  Prerequisites to configuring the connector

  • You must have the URL of the SendGrid server to which you will connect and perform automated operations and the API key configured for your account to access the SendGrid server.
  • The FortiSOAR™ server should have outbound connectivity to port 443 on the SendGrid server.

  Minimum Permissions Required

  • Not Applicable

  Configuring the connector

  For the procedure to configure a connector, click here

  Configuration parameters

  In FortiSOAR™, on the Connectors page, click the SendGrid connector row (if you are in the Grid view on the Connectors page), and in the Configurations tab enter the required configuration details:

  Parameter	Description
  Server Address	URL of the SendGrid server to which you will connect and perform the automated operations.
  API Key	API key configured for your account to access the SendGrid server.
  Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True.

  Actions supported by the connector

  The following automated operations can be included in playbooks and you can also use the annotations to access operations from version 4.10.0 onwards:

  Function	Description	Annotation and Category
  Send Email	Sends an email using SendGrid based on the From and To recipients and other input parameters you have specified.	send_email Investigation
  Get Email Statistics	Retrieves your email statistics between a specified date range from SendGrid based on the type of email statistics and other input parameters you have specified.	get_email_stats Investigation
  Search Emails	Filter all email messages to search your email activity in SendGrid based on the input query you have specified.	search_email Investigation
  Get Contact List	Returns an array of all of your contact lists from SendGrid	get_contact_list Investigation
  Get Alerts	Retrieves all of your alerts from SendGrid.	get_alerts Investigation
  Create Batch ID	Generates a new batch ID in SendGrid. Once a batch_id is created, you can associate it with a scheduled send using the "Send Email" action to schedule sending a batch of emails at the same time using your SendGrid account. Passing the batch_id as a field in the request body of the "Send Email" action assigns the batch ID to the schedule send you are creating.	create_batch_id Investigation
  Get Scheduled Send	Retrieves all canceled and paused scheduled send information from SendGrid based on the batch_id you have specified.	get_scheduled_send Investigation
  Update Scheduled Send	Cancels or pauses a scheduled send that is associated with the batch_id you have specified.	update_scheduled_send Investigation
  Delete Scheduled Send	Deletes a scheduled send that is associated with the batch_id you have specified. Note: Scheduled sends that are canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled.	delete_scheduled_send Investigation

  operation: Send Email

  Input parameters

  Parameter	Description
  From	The email ID of the sender from whose account you want to send the email. This address must be a verified sender in your SendGrid account.
  To Recipients	The email IDs of the recipients, in CSV or list format, to whose account you want to deliver the email.
  CC Recipients	(Optional) The email IDs of the members, in CSV or list format, that you want to add to the CC list of the email.
  BCC Recipients	(Optional) The email IDs of the members, in CSV or list format, that you want to add to the BCC list of the email.
  Body Type	Select the format in which you want to send the email. You can choose from the following options: Rich Text: Select to specify a subject and body of the email in the following fields. Subject: Specify a subject of the email that you want to send from the SendGrid account. Body: (Optional) Specify a message or content of the email that you want to send from your SendGrid account. You can add formatted content, images, and even custom jinja expressions to use dynamic values, in the Body field. Email Template: Select an email template to use to send the email. An existing email template is passed as an input for the email subject and body (content) allowing you to leverage an existing email template and build upon it, thereby, avoiding re-work and ensuring consistency. NOTE: This feature of using preexisting email templates for sending emails is only available in FortiSOAR™ v7.6.5 and later.
  Plain Text Body Content	(Optional) The body of the email in plain text, which you want to send using your SendGrid account.
  HTML Body Content	(Optional) The body of the email in HTML, which you want to send using your SendGrid account.
  Attachment IRIs	(Optional) The list of IRI ID(s) of the file(s), in CSV or list format, that you want to attach to the email using your SendGrid account. IRI IDs are used to access files from the 'Attachments' module in FortiSOAR.
  Inline Attachment IRIs	(Optional) The list of IRI ID(s) of the file(s), in CSV or list format, that you want to add inline to the email using your SendGrid account. IRI IDs are used to access files from the 'Attachments' module in FortiSOAR.
  Batch ID	An ID representing a batch of emails to be sent at the same time using your SendGrid account. Including a batch_id in your request allows you to include this email in that batch and also enables you to cancel or pause the delivery of that batch.
  Scheduled Timestamp	A UNIX timestamp allowing you to specify when you want this email to be delivered.

  Output

  The output contains a non-dictionary value.

  operation: Get Email Statistics

  Input parameters

  Parameter	Description
  Email Statistics By	Retrieves email statistics based on the selected input type from SendGrid. You can choose between Global Email Statistics, Country And State Province, Device Type, Client Type, Mailbox Provider, and Browser. If you choose 'Global Email Statistics', 'Device Type', or 'Client Type', then no other input parameter is required. If you choose 'Country And State Province', then you must specify the following parameter: Country: The country for which you want to retrieve the email statistics from SendGrid. Currently, support is for US and CA only. If you choose 'Mailbox Provider', then you must specify the following parameter: Mailbox Providers: The mailbox providers for which you want to retrieve the email statistics from SendGrid. You can include up to 10 mailbox providers. If you choose 'Browser', then you must specify the following parameter: Browsers: The browsers for which you want to retrieve the email statistics from SendGrid. You can include up to 10 different browsers.
  Start Date	The starting date from when you want to retrieve the email statistics from SendGrid. It must follow YYYY-MM-DD format. Note: Time is not considered
  End Date	The end date till when you want to retrieve the email statistics from SendGrid. By default, it is set to 'today', and it must follow YYYY-MM-DD format. Note: Time is not considered
  Aggregate Result By	The basis on which to group the email statistics retrieved from SendGrid. You can choose from day, week, or month.

  Output

  Output schema when you choose "Email Statistics By" as "Global Email Statistics":
  {
"date": "",
"stats": [
{
"metrics": {
"blocks": "",
"bounce_drops": "",
"bounces": "",
"clicks": "",
"deferred": "",
"delivered": "",
"invalid_emails": "",
"opens": "",
"processed": "",
"requests": "",
"spam_report_drops": "",
"spam_reports": "",
"unique_clicks": "",
"unique_opens": "",
"unsubscribe_drops": "",
"unsubscribes": ""
}
}
]
}

  Output schema when you choose "Email Statistics By" as "Country And State Province":
  {
"date": "",
"stats": [
{
"type": "",
"name": "",
"metrics": {
"clicks": "",
"opens": "",
"unique_clicks": "",
"unique_opens": ""
}
}
]
}

  If you choose "Device Type" or "Client Type" as the "Email Statistics By", then the output contains the following populated JSON schema:
  {
"date": "",
"stats": [
{
"type": "",
"name": "",
"metrics": {
"opens": "",
"unique_opens": ""
}
}
]
}

  Output schema when you choose "Email Statistics By" as "Mailbox Provider":
  {
"date": "",
"stats": [
{
"type": "",
"name": "",
"metrics": {
"blocks": "",
"bounces": "",
"clicks": "",
"deferred": "",
"delivered": "",
"drops": "",
"opens": "",
"processed": "",
"requests": "",
"spam_reports": "",
"unique_clicks": "",
"unique_opens": ""
}
}
]
}

  This is the default output schema:
  {
"date": "",
"stats": [
{
"metrics": {
"blocks": "",
"bounce_drops": "",
"bounces": "",
"clicks": "",
"deferred": "",
"delivered": "",
"invalid_emails": "",
"opens": "",
"processed": "",
"requests": "",
"spam_report_drops": "",
"spam_reports": "",
"unique_clicks": "",
"unique_opens": "",
"unsubscribe_drops": "",
"unsubscribes": ""
}
}
]
}

  operation: Search Emails

  Input parameters

  Parameter	Description
  Query	The query syntax that you want to use to filter your email activity in SendGrid. For example, subject="This is a subject test", from_email="testing@sendgrid.net", etc. For more information on parameters that you can use in a query and filtering email messages, see https://docs.sendgrid.com/api-reference/e-mail-activity/filter-all-messages.
  Limit	(Optional) The maximum number of items that this operation should return in a single search.

  Output

  The output contains the following populated JSON schema:
  {
"messages": [
{
"from_email": "",
"msg_id": "",
"subject": "",
"to_email": "",
"status": "",
"opens_count": "",
"clicks_count": "",
"last_event_time": ""
}
]
}

  operation: Get Contact List

  Input parameters

  None.

  Output

  The output contains the following populated JSON schema:
  {
"result": [
{
"name": "",
"id": "",
"contact_count": "",
"_metadata": {
"self": ""
}
}
],
"_metadata": {
"self": ""
}
}

  operation: Get Alerts

  Input parameters

  None.

  Output

  The output contains the following populated JSON schema:
  {
"id": "",
"type": "",
"percentage": "",
"email_to": "",
"created_at": "",
"updated_at": ""
}

  operation: Create Batch ID

  Input parameters

  None.

  Output

  The output contains the following populated JSON schema:
  {
"batch_id": ""
}

  operation: Get Scheduled Send

  Input parameters

  Parameter	Description
  Batch ID	The batch id whose canceled or paused scheduled send information you want to retrieve from SendGrid.

  Output

  The output contains a non-dictionary value.

  operation: Update Scheduled Send

  Input parameters

  Parameter	Description
  Batch ID	The batch ID whose scheduled send (mail) you want to cancel or pause.
  Status	The action (status) that you want to perform on the scheduled send. You can choose between Pause or Cancel.

  Output

  The output contains a non-dictionary value.

  operation: Delete Scheduled Send

  Input parameters

  Parameter	Description
  Batch ID	The batch ID whose scheduled send (mail) you want to delete.

  Output

  The output contains a non-dictionary value.

  Included playbooks

  The Sample - SendGrid - 1.1.0 playbook collection comes bundled with the SendGrid connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the SendGrid connector.

  • Create Batch ID
  • Delete Scheduled Send
  • Get Alerts
  • Get Contact List
  • Get Email Statistics
  • Get Scheduled Send
  • Search Emails
  • Send Email
  • Update Scheduled Send

  Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.