SendGrid integration

SendGrid is a cloud-based email delivery platform for transactional and marketing emails. This integration lets your WeWeb backend send emails using SendGrid’s Mail Send API.

Use cases

• Send transactional emails from backend workflows (sign-up confirmations, passwordless links, receipts)
• Personalize messages with dynamic variables and HTML or plain text
• Include attachments and categorize emails for analytics
• Use CC/BCC and Reply-To for flexible recipient management

Setup

1. In SendGrid, create an API key.
2. In WeWeb, add your SendGrid API key to the Editor, Staging, and Production modes (as needed).
3. Verify a sender or your domain — SendGrid blocks sending until the From address is verified. You must complete either Single Sender Verification (one email, good for testing) or Domain Authentication (your domain, required for production). See How to verify your domain below.
4. Test by sending a simple email to yourself using the verified sender or a verified-domain address to confirm authentication and payload format.

Sending test emails

Before verifying your domain, you can send test emails using Single Sender Verification:

1. Go to SendGrid's dashboard: Settings > Sender Authentication
2. Click Create Single Sender under Single Sender Verification
3. Enter your personal email address and fill in the required details
4. Check your email inbox and click the verification link
5. Use this verified email address in the From Email field when sending test emails

With Single Sender Verification, you can send emails from the verified address, though recipients may see "via sendgrid.net" in their email client. For production, verify your domain using Domain Authentication for better deliverability.

How to verify your domain

SendGrid requires sender verification before you can send. Without it, sends are blocked (e.g. 403 or "sender not verified"). You have two options:

• Single Sender Verification — Verify one email address (e.g. your own). Use this for testing; see Sending test emails above.
• Domain Authentication — Verify your domain so you can send from any address at that domain (e.g. noreply@yourdomain.com). Required for production and to avoid "via sendgrid.net".

Verify your domain (Domain Authentication)

1. In SendGrid, go to Settings → Sender Authentication.
2. Under Domain Authentication, click Authenticate Your Domain (or Get Started).
3. Choose your DNS host (where your domain’s DNS is managed, e.g. GoDaddy, Cloudflare, your registrar).
4. Enter the domain you want to send from (e.g. yourdomain.com). SendGrid may offer a subdomain option (e.g. em123.yourdomain.com) for link branding.
5. SendGrid will show DNS records (CNAMEs and sometimes TXT) to add. Copy each Host and Value (or Data).
6. In your DNS host’s dashboard, add each record as a CNAME or TXT as instructed. Do not change the values; paste them exactly.
7. Wait for DNS propagation (from a few minutes to 48 hours). In SendGrid, use Verify to check. When verification succeeds, the domain shows as verified.
8. In WeWeb, use a From Email whose domain matches the verified domain (e.g. hello@yourdomain.com). You can then send from that address.

If verification fails, double-check that the records were added at the correct host (e.g. for yourdomain.com the records often go on the root or the subdomain SendGrid gives you) and that there are no typos. For the full process and troubleshooting, see SendGrid’s docs: Authenticate your domain.

We have not created the following video, but it provides guidance on verifying your domain:

Sending dynamic values in HTML content

You can make your emails personalized and dynamic by binding values into your HTML content. This allows you to include user names, order numbers, custom links, and any other data from your app.

How to add dynamic values

1. Click on the HTML Content field in the Send Email action
2. Click the plug icon beside the field to open the binding window
3. In the binding window, you can:
   • Reference variables by typing their name (e.g., userName, orderTotal)
   • Access user data with currentUser.name, currentUser.email
   • Use workflow variables or action results from previous steps
   • Write JavaScript expressions for more complex logic

Example with dynamic values

Here's an example of HTML content with dynamic values bound:

<h2>Hello ${userName}!</h2>
<p>Thank you for your order #${orderId}.</p>
<p>Your total is ${orderTotal}.</p>
<a href="${confirmationLink}">View your order</a>

In the binding window, you would write this as a template literal or concatenated string:

`<h2>Hello ${variables.userName}!</h2>
<p>Thank you for your order #${variables.orderId}.</p>
<p>Your total is $${variables.orderTotal}.</p>
<a href="${variables.confirmationLink}">View your order</a>`

USING TEMPLATE LITERALS

When binding HTML content with multiple dynamic values, use template literals (backticks `) in the formula window. This makes it easier to include variables directly in your HTML using ${variableName} syntax.

Sending attachments

You can attach files to your emails. In WeWeb, the attachment content can be:

• A File value (for example from a file upload component)
• A base64 string
• A data URI (for example data:application/pdf;base64,...)

How to add attachments

1. In the Attachments field, add a new attachment
2. Set Filename to the name you want recipients to see (e.g., invoice.pdf)
3. Set File Content to your file content (File, base64, or data URI)
4. Set MIME Type to match your file type (see supported MIME types below)
5. Set Disposition to:
   • Attachment if you want the file to appear as a downloadable attachment
   • Inline if you want to embed the file in the email content (useful for images)

Supported MIME types

SendGrid supports the following MIME types for attachments:

Documents:

• application/pdf - PDF Document
• application/msword - Word Document (.doc)
• application/vnd.openxmlformats-officedocument.wordprocessingml.document - Word Document (.docx)
• application/vnd.ms-excel - Excel Spreadsheet (.xls)
• application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - Excel Spreadsheet (.xlsx)
• application/vnd.ms-powerpoint - PowerPoint (.ppt)
• application/vnd.openxmlformats-officedocument.presentationml.presentation - PowerPoint (.pptx)

Archives and Data:

• application/zip - ZIP Archive
• application/json - JSON
• application/xml - XML

Text Files:

• text/plain - Text File
• text/csv - CSV
• text/html - HTML

Images:

• image/png - PNG Image
• image/jpeg - JPEG Image
• image/gif - GIF Image
• image/svg+xml - SVG Image
• image/webp - WebP Image

Getting base64-encoded files

You can get base64-encoded file content from:

• File upload component in WeWeb
• API responses that return file data
• Variables where you've stored base64-encoded content

Multiple attachments

To send multiple files, click the + button in the Attachments array to add more attachment items. Each attachment needs its own filename, content, MIME type, and disposition.

EMAIL SIZE LIMIT

SendGrid has a maximum email size of 30MB including all attachments. If you need to send larger files, consider using links to cloud storage instead of attaching the files directly.

Common pitfalls (setup & usage)

Unverified sender or domain

If your sender or domain is not verified, SendGrid may reject the request. For testing, use Single Sender Verification (Settings > Sender Authentication > Create Single Sender) to verify a single email address. For production, authenticate your domain in SendGrid (Settings > Sender Authentication > Authenticate Your Domain).

Invalid email addresses

If any address in From Email, To Email(s), CC Recipients, BCC Recipients, or Reply To is invalid, the request will fail with a 400 error. Start tests with a single known-good recipient.

Missing content

In the Send Email action, choose a content type and provide the matching content:

• If you send Text, set Text Content.
• If you send HTML, set HTML Content (and optionally Fallback Text Content).

Attachments too large

SendGrid has a maximum email size of 30MB including all attachments. Oversized attachments can trigger 413 Payload Too Large. If you need to send larger files, consider using links to cloud storage instead of attaching the files directly.

All Actions

This integration currently provides one action powered by SendGrid’s Mail Send API.

Action	Description
Send Email	Send a transactional email via SendGrid

Action details

Send Email

Send a transactional email via SendGrid.

Inputs

Display Key	Example Input	Description	Restrictions
From Email	{"email":"sender@yourdomain.com","name":"Sender"}	Sender’s email address and optional name	Email must belong to a verified sender or authenticated domain
To Email(s)	[{"email":"user@example.com","name":"User"}]	Recipient email address(es) with optional names	At least one recipient required; valid emails
Subject	"Hello World"	Email subject line	Recommended limit: ≤ 998 characters
Content Type	Text	Whether you send a text-only email or an HTML email	Text or HTML
Text Content	"Hello world!"	Plain text content of the email	Required when Content Type is Text
HTML Content	<p>Hello <strong>Jane</strong></p>	HTML content of the email	Required when Content Type is HTML; valid HTML
Fallback Text Content Optional	"Hello Jane"	Plain text fallback when Content Type is HTML	Recommended for deliverability and accessibility
Attachments Optional	See structure below	Files to include with the email	Total request size limits apply
Reply To Optional	{"email":"support@example.com","name":"Support"}	Reply-to email address and optional name	Must be a valid email
CC Recipients Optional	[{"email":"cc@example.com","name":"CC"}]	Carbon copy recipients	Array of valid emails
BCC Recipients Optional	[{"email":"bcc@example.com","name":"BCC"}]	Blind carbon copy recipients	Array of valid emails
Categories Optional	["receipts","welcome"]	Categories for analytics/organization	Array of strings

CONTENT TYPE

Choose Text to send only text content. Choose HTML to send HTML content (and optionally a plain-text fallback).

Attachments structure

Field	Example input	Description	Restrictions
filename	"invoice.pdf"	File name as it should appear to recipients	—
content	"base64-encoded-file"	File content (File, base64, or data URI)	Required when attaching a file
type	"application/pdf"	MIME type of the file	See supported MIME types
disposition	"attachment"	How the attachment is displayed	Allowed values: attachment, inline

Example output

{
  "statusCode": 202,
  "headers": {
    "server": "nginx",
    "date": "Tue, 01 Oct 2024 12:00:00 GMT"
  },
  "body": ""
}

Documentation of API endpoint that powers action: SendGrid API – Mail Send (POST /v3/mail/send)

Error handling

Error code and type	Reason
401 Unauthorized	Invalid or missing API key.
400 Bad Request	Invalid parameters or payload (e.g., missing required fields, malformed content, invalid addresses).
403 Forbidden	Sender/domain not verified or insufficient permissions; request blocked.
404 Not Found	Incorrect endpoint or resource path.
405 Method Not Allowed	HTTP method not supported for this endpoint.
413 Payload Too Large	Email (including attachments) exceeds size limits.
429 Too Many Requests	Rate limiting encountered; reduce concurrency and retry with backoff.
500 Internal Server Error	Provider-side error; retry with backoff.

FAQs

Why do I get a 403 error when sending?

SendGrid restricts sending if your sender identity or domain isn't verified. For testing, use Single Sender Verification (Settings > Sender Authentication > Create Single Sender) to verify a single email address without domain authentication. For production, authenticate your domain in the SendGrid dashboard for better deliverability.

Should I send HTML or Text?

If you need styling, use HTML Content (and ideally set Fallback Text Content too). For quick tests or simple emails, Text Content is sufficient.

How do I add attachments?

Provide each attachment with filename, content (File, base64, or data URI), type (MIME), and disposition (attachment or inline). Total email size including attachments cannot exceed 30MB.

What's the difference between Single Sender Verification and Domain Authentication?

Single Sender Verification verifies a single email address (like your personal email) and is great for testing. Emails may show "via sendgrid.net" to recipients. Domain Authentication verifies your entire domain and is recommended for production use, providing better deliverability and removing the "via sendgrid.net" notice.