SendGrid

This guide explains how to integrate SendGrid with Product-Live Data Factory to send transactional emails using the HTTP task.

Overview

SendGrid (by Twilio) is a cloud-based email delivery service that provides a REST API for sending emails at scale. The Data Factory HTTP task can integrate with SendGrid to:

Send transactional emails - Order confirmations, shipping notifications, etc.
Send bulk emails - Marketing campaigns, newsletters
Use dynamic templates - Personalized content with Handlebars syntax
Track email events - Opens, clicks, bounces (via webhooks)

Prerequisites

A SendGrid account (sign up for free)
A verified sender identity (domain or single sender)
Product-Live account with access to the Data Factory platform

Step 1: Create a SendGrid Account

Go to SendGrid Sign Up
Create an account with your email
Complete the verification process
Access the SendGrid Dashboard

Step 2: Verify a Sender Identity

SendGrid requires sender verification before sending emails:

Option A: Single Sender Verification (Quick Start)

Go to Settings → Sender Authentication
Click Verify a Single Sender
Fill in sender details (name, email, address)
Click Create
Check your email and click the verification link

Option B: Domain Authentication (Recommended for Production)

Go to Settings → Sender Authentication
Click Authenticate Your Domain
Select your DNS host
Add the provided CNAME records to your DNS
Click Verify

Production Recommendation

For production use, always authenticate your domain. This improves deliverability and allows you to send from any address on that domain.

Step 3: Create an API Key

Go to Settings → API Keys
Click Create API Key
Enter a name (e.g., Product-Live Data Factory)
Choose permissions:
- Restricted Access (recommended) - Select only "Mail Send" → Full Access
- Full Access - All permissions (not recommended)
Click Create & View
Copy the API key immediately - it won't be shown again!

Important

Save your API key securely! SendGrid only displays it once. If you lose it, you'll need to create a new one.

Step 4: Configure Data Factory Variables

Create the following variables in your Data Factory project:

Variable Name	Description	Example
`sendgrid_api_key`	SendGrid API Key	`SG.xxxxxxxxxxxxxxxxxxxx`
`sendgrid_from_email`	Verified sender email	`noreply@yourdomain.com`
`sendgrid_from_name`	Sender display name	`Product-Live`

Security Best Practice

Mark the sendgrid_api_key variable as a secret in Data Factory to prevent it from being displayed in logs.

Step 5: Use in HTTP Task

Send a Simple Email

json

{
    "name": "protocol-http-perform",
    "taskReferenceName": "send-email-sendgrid",
    "type": "SUB_WORKFLOW",
    "inputParameters": {
        "scheme": "HTTPS",
        "method": "POST",
        "domain": "api.sendgrid.com",
        "path": "/v3/mail/send",
        "headers": {
            "Authorization": "Bearer ${workflow.variables.sendgrid_api_key}",
            "Content-Type": "application/json"
        },
        "body": {
            "type": "JSON",
            "json": {
                "personalizations": [
                    {
                        "to": [
                            {
                                "email": "recipient@example.com",
                                "name": "John Doe"
                            }
                        ],
                        "subject": "Your order has been shipped!"
                    }
                ],
                "from": {
                    "email": "${workflow.variables.sendgrid_from_email}",
                    "name": "${workflow.variables.sendgrid_from_name}"
                },
                "content": [
                    {
                        "type": "text/plain",
                        "value": "Hello John,\n\nYour order #12345 has been shipped.\n\nBest regards,\nProduct-Live Team"
                    }
                ]
            }
        },
        "connectionTimeOutMilliseconds": 10000
    }
}

Common SendGrid Operations

Send HTML Email

json

{
    "scheme": "HTTPS",
    "method": "POST",
    "domain": "api.sendgrid.com",
    "path": "/v3/mail/send",
    "headers": {
        "Authorization": "Bearer ${workflow.variables.sendgrid_api_key}",
        "Content-Type": "application/json"
    },
    "body": {
        "type": "JSON",
        "json": {
            "personalizations": [
                {
                    "to": [
                        {
                            "email": "recipient@example.com"
                        }
                    ],
                    "subject": "Your Weekly Report"
                }
            ],
            "from": {
                "email": "${workflow.variables.sendgrid_from_email}",
                "name": "${workflow.variables.sendgrid_from_name}"
            },
            "content": [
                {
                    "type": "text/plain",
                    "value": "Please view this email in an HTML-compatible client."
                },
                {
                    "type": "text/html",
                    "value": "<html><body><h1>Weekly Report</h1><p>Here is your weekly summary...</p></body></html>"
                }
            ]
        }
    }
}

Send to Multiple Recipients

json

{
    "body": {
        "type": "JSON",
        "json": {
            "personalizations": [
                {
                    "to": [
                        { "email": "user1@example.com", "name": "User One" },
                        { "email": "user2@example.com", "name": "User Two" }
                    ],
                    "cc": [
                        { "email": "manager@example.com" }
                    ],
                    "bcc": [
                        { "email": "archive@example.com" }
                    ],
                    "subject": "Team Update"
                }
            ],
            "from": {
                "email": "${workflow.variables.sendgrid_from_email}",
                "name": "${workflow.variables.sendgrid_from_name}"
            },
            "content": [
                {
                    "type": "text/plain",
                    "value": "Hello team, here's the latest update..."
                }
            ]
        }
    }
}

Send with Categories and Custom Arguments

Categories help organize and track emails in SendGrid. Custom arguments are key-value pairs that can be used for tracking and filtering:

json

{
    "body": {
        "type": "JSON",
        "json": {
            "personalizations": [
                {
                    "to": [
                        { "email": "recipient@example.com" }
                    ],
                    "subject": "Order Confirmation",
                    "custom_args": {
                        "order_id": "12345",
                        "customer_id": "67890",
                        "campaign": "summer-sale"
                    }
                }
            ],
            "from": {
                "email": "${workflow.variables.sendgrid_from_email}",
                "name": "${workflow.variables.sendgrid_from_name}"
            },
            "categories": ["order-confirmation", "transactional", "product-live"],
            "content": [
                {
                    "type": "text/plain",
                    "value": "Thank you for your order!"
                }
            ]
        }
    }
}

Using Categories and Custom Args

Categories: Use for filtering emails in SendGrid Activity Feed and analytics
Custom Args: Available in webhook events for tracking and segmentation
Both are useful for debugging and monitoring email delivery

Use Dynamic Template

SendGrid dynamic templates allow you to create reusable email templates with variables:

json

{
    "body": {
        "type": "JSON",
        "json": {
            "personalizations": [
                {
                    "to": [
                        { "email": "customer@example.com" }
                    ],
                    "dynamic_template_data": {
                        "first_name": "John",
                        "order_number": "12345",
                        "order_total": "€99.99",
                        "shipping_address": "123 Main St, Paris, France",
                        "items": [
                            { "name": "Product A", "quantity": 2, "price": "€49.99" },
                            { "name": "Product B", "quantity": 1, "price": "€49.99" }
                        ]
                    }
                }
            ],
            "from": {
                "email": "${workflow.variables.sendgrid_from_email}",
                "name": "${workflow.variables.sendgrid_from_name}"
            },
            "template_id": "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }
    }
}

Creating Dynamic Templates

Go to Email API -> Dynamic Templates in SendGrid
Click Create a Dynamic Template
Add a version and use the Design or Code editor
Use Handlebars syntax: {{first_name}}, {{#each items}}...{{/each}}
Copy the Template ID (starts with d-)

Send with Attachments

json

{
    "body": {
        "type": "JSON",
        "json": {
            "personalizations": [
                {
                    "to": [
                        { "email": "recipient@example.com" }
                    ],
                    "subject": "Your Invoice"
                }
            ],
            "from": {
                "email": "${workflow.variables.sendgrid_from_email}"
            },
            "content": [
                {
                    "type": "text/plain",
                    "value": "Please find your invoice attached."
                }
            ],
            "attachments": [
                {
                    "content": "${base64_encoded_file_content}",
                    "filename": "invoice.pdf",
                    "type": "application/pdf",
                    "disposition": "attachment"
                }
            ]
        }
    }
}

Attachment Limitations

Maximum total message size: 20MB (including headers and body)
Attachments must be Base64 encoded
For large files, consider using a cloud storage link instead

Schedule Email for Later

json

{
    "body": {
        "type": "JSON",
        "json": {
            "personalizations": [
                {
                    "to": [
                        { "email": "recipient@example.com" }
                    ],
                    "subject": "Scheduled Newsletter"
                }
            ],
            "from": {
                "email": "${workflow.variables.sendgrid_from_email}"
            },
            "content": [
                {
                    "type": "text/plain",
                    "value": "This email was scheduled to be sent at a specific time."
                }
            ],
            "send_at": 1704067200
        }
    }
}

Scheduling

The send_at field accepts a Unix timestamp (seconds since epoch). You can schedule emails up to 72 hours in advance.

Response Handling

Successful Send (202 Accepted)

A successful email send returns HTTP 202 with no body. The email is queued for delivery.

json

{
    "expectedOutputSchema": {
        "type": "object",
        "properties": {
            "statusCode": {
                "type": "integer",
                "const": 202
            }
        }
    }
}

Error Response

Errors return a JSON body with details:

json

{
    "errors": [
        {
            "message": "The from address does not match a verified Sender Identity.",
            "field": "from.email",
            "help": "http://sendgrid.com/docs/for-developers/sending-email/sender-identity/"
        }
    ]
}

SendGrid API Endpoints

Endpoint	Method	Description
`/v3/mail/send`	POST	Send an email
`/v3/templates`	GET	List dynamic templates
`/v3/suppression/bounces`	GET	Get bounced emails
`/v3/suppression/unsubscribes`	GET	Get unsubscribed emails
`/v3/stats`	GET	Get email statistics

EU Data Residency

For GDPR compliance, SendGrid offers EU data residency. Use the EU endpoint:

Region	Endpoint
Global	`api.sendgrid.com`
EU	`api.eu.sendgrid.com`

json

{
    "domain": "api.eu.sendgrid.com",
    "path": "/v3/mail/send"
}

Troubleshooting

Error: "The from address does not match a verified Sender Identity"

Verify your sender identity in SendGrid settings
For domain authentication, check DNS records are correctly configured
Wait up to 48 hours for DNS propagation

Error: "Authorization Required" (401)

Check your API key is correct
Ensure the Authorization header format is Bearer YOUR_API_KEY
Verify the API key has "Mail Send" permissions

Error: "Bad Request" (400)

Check the JSON structure matches SendGrid's requirements
Ensure personalizations array is present with at least one recipient
Verify from email is present and verified

Error: "Forbidden" (403)

Your account may be suspended or have sending restrictions
Check your SendGrid dashboard for account status
Contact SendGrid support if needed

Emails Not Arriving

Check spam/junk folders
Verify sender authentication (SPF, DKIM, DMARC)
Review SendGrid Activity Feed for delivery status
Check suppression lists (bounces, unsubscribes)

Rate Limits

Plan	Emails per Day	Emails per Month
Free	100	100
Essentials	-	50,000+
Pro	-	100,000+

Rate Limiting

SendGrid uses sliding window rate limiting. If you hit limits, implement exponential backoff in your workflow using the retry feature.

Security Best Practices

Use API Key restrictions - Only grant "Mail Send" permission
Store API key as secret - Never expose in logs or version control
Verify sender domains - Better deliverability and security
Enable 2FA - Protect your SendGrid account
Monitor activity - Review SendGrid Activity Feed regularly
Use IP Access Management - Restrict API access to known IPs
Implement webhooks - Track bounces and unsubscribes automatically

HTTP Task Reference
Send Email Task - Built-in email task (SMTP)
Notification Integrations Overview
Data Factory Variables
SendGrid API Documentation
SendGrid Dynamic Templates

Rules engine

Third-Party Integrations

Cloud Storage

Notifications

SendGrid

Overview

Prerequisites

Step 1: Create a SendGrid Account

Step 2: Verify a Sender Identity

Option A: Single Sender Verification (Quick Start)

Option B: Domain Authentication (Recommended for Production)

Step 3: Create an API Key

Step 4: Configure Data Factory Variables

Step 5: Use in HTTP Task

Send a Simple Email

Common SendGrid Operations

Send HTML Email

Send to Multiple Recipients

Send with Categories and Custom Arguments

Use Dynamic Template

Send with Attachments

Schedule Email for Later

Response Handling

Successful Send (202 Accepted)

Error Response

SendGrid API Endpoints

EU Data Residency

Troubleshooting

Error: "The from address does not match a verified Sender Identity"

Error: "Authorization Required" (401)

Error: "Bad Request" (400)

Error: "Forbidden" (403)

Emails Not Arriving

Rate Limits

Security Best Practices

Cloud Storage

Notifications

SendGrid ​

Overview ​

Prerequisites ​

Step 1: Create a SendGrid Account ​

Step 2: Verify a Sender Identity ​

Option A: Single Sender Verification (Quick Start) ​

Option B: Domain Authentication (Recommended for Production) ​

Step 3: Create an API Key ​

Step 4: Configure Data Factory Variables ​

Step 5: Use in HTTP Task ​

Send a Simple Email ​

Common SendGrid Operations ​

Send HTML Email ​

Send to Multiple Recipients ​

Send with Categories and Custom Arguments ​

Use Dynamic Template ​

Send with Attachments ​

Schedule Email for Later ​

Response Handling ​

Successful Send (202 Accepted) ​

Error Response ​

SendGrid API Endpoints ​

EU Data Residency ​

Troubleshooting ​

Error: "The from address does not match a verified Sender Identity" ​

Error: "Authorization Required" (401) ​

Error: "Bad Request" (400) ​

Error: "Forbidden" (403) ​

Emails Not Arriving ​

Rate Limits ​

Security Best Practices ​

Related Documentation ​

SendGrid

Overview

Prerequisites

Step 1: Create a SendGrid Account

Step 2: Verify a Sender Identity

Option A: Single Sender Verification (Quick Start)

Option B: Domain Authentication (Recommended for Production)

Step 3: Create an API Key

Step 4: Configure Data Factory Variables

Step 5: Use in HTTP Task

Send a Simple Email

Common SendGrid Operations

Send HTML Email

Send to Multiple Recipients

Send with Categories and Custom Arguments

Use Dynamic Template

Send with Attachments

Schedule Email for Later

Response Handling

Successful Send (202 Accepted)

Error Response

SendGrid API Endpoints

EU Data Residency

Troubleshooting

Error: "The from address does not match a verified Sender Identity"

Error: "Authorization Required" (401)

Error: "Bad Request" (400)

Error: "Forbidden" (403)

Emails Not Arriving

Rate Limits

Security Best Practices

Related Documentation