SendGrid Integration with SmythOS

Need to send reliable, scalable email from your agents? Connect SendGrid to SmythOS and empower your agents to send transactional and marketing emails programmatically.

TL;DR

Securely link your SendGrid account to SmythOS using an API key. Then, use our components to send beautiful, dynamic emails using templates and Handlebars data, or send simple, static emails for quick notifications.

List of SendGrid Components

Quickly compare SendGrid components by what they do and their key I/O. Click any component name to jump directly to its detailed guide.

Component	Action	What it Does	Inputs	Key Outputs	Use Case
Send Dynamic Email	Write	Sends an email using a pre-built SendGrid Dynamic Transactional Template.	required from, to, template_id, JSON_template_handlebars	Response	Sending personalized welcome emails or order confirmations.
Send Static Email	Write	Sends a simple email with a subject and content defined directly in the agent.	required from, to, subject, content	Response	Sending quick system alerts or basic notifications.

INFO

Why Integrate SendGrid with Your Agent?

SendGrid is a best-in-class email delivery platform. Integrating it with SmythOS allows you to build robust communication workflows and reliably deliver emails at scale.

• Automate Transactional Emails: Create agents that automatically send password resets, account verifications, order confirmations, and shipping notifications.
• Personalized Marketing Campaigns: Use agents to pull customer data from a CRM or database, and then send each customer a personalized promotional email using a dynamic SendGrid template.
• Reliable Alerting System: When an agent detects a critical system error or an important business event, it can use SendGrid to send a reliable email alert to the on-call team, ensuring deliverability.
• Streamline Communication: Centralize all your application's email-sending logic within SmythOS agents, making it easy to manage, update, and monitor your transactional email flows.

Prerequisites

Before you begin, please ensure you have the following:

• An active SmythOS account. (Sign up here).
• A SendGrid account.
• A SendGrid API Key.
• A verified sender identity (domain or email address) in your SendGrid account.

Getting Started With SendGrid

The connection between SmythOS and SendGrid is configured using a secure API Key.

Step 1: Get Your SendGrid API Key

1. Log in to your SendGrid account.
2. Navigate to Settings > API Keys in the left-hand menu.
3. Click Create API Key.
4. Give your key a name (e.g., "SmythOS Agent Key") and select Full Access or restricted permissions as needed. For sending email, Mail Send permissions are required.
5. Click Create & View.
6. Copy the API key immediately. It will not be shown again for security reasons.

Step 2: Store Your API Key in SmythOS Vault

Your API Key is a sensitive credential. Use the SmythOS Vault to store it securely.

1. In your SmythOS dashboard, navigate to the Vault.
2. Create a new secret and paste your SendGrid API Key as the value. Give it a memorable name, like sendgrid_api_key.
3. For more details, see the Vault Documentation.

Step 3: Configure a SendGrid Component

1. In your SmythOS agent graph, drag and drop any SendGrid component.
2. Click the component to open its Settings panel.
3. In the API Key field, select the secret you saved in the Vault (e.g., sendgrid_api_key).
4. Your connection is now configured for that component.

Heads-up

You must add the API Key from the Vault to each SendGrid component you use. This ensures all your API calls are properly authenticated.

Which SendGrid Component Should I Use?

If you need to…	Target	Use this Component	Why this one?
Send a beautifully designed, personalized email (e.g., a receipt)	A template_id and dynamic data	Send Dynamic Email	Leverages powerful Handlebars templates for personalization and consistent branding.
Send a quick, simple text notification (e.g., a system alert)	subject and content text	Send Static Email	The fastest way to send a basic email without needing to pre-configure a template.

Component Details

This section provides detailed information for each SendGrid component.

Send Dynamic Email

Sends an email using a Dynamic Transactional Template from your SendGrid account, populated with data you provide.

INFO

This component requires an API Key for authentication, as detailed in the Getting Started section.

Inputs

Field	Type	Required	Notes
from	string	Yes	The sender's email address. Must be a verified sender in SendGrid.
to	string	Yes	The recipient's email address.
template_id	string	Yes	The ID of the Dynamic Transactional Template from your SendGrid account.
JSON_template_handlebars	JSON	Yes	A JSON object containing the dynamic data to populate your Handlebars template.

Outputs

Field	Type	Description
Response	object	A successful send returns an empty body with a 202 Accepted status code. The response object will be empty on success.
Headers	object	The HTTP headers from the API response, useful for getting the x-message-id.

Use Case

An agent handles new user sign-ups. It calls this component with the user's name and a welcome template_id to send a personalized onboarding email.

{
  "component": "sendgrid.sendDynamicEmail",
  "from": "welcome@example.com",
  "to": "new.user@example.com",
  "template_id": "d-1234567890abcdef1234567890abcdef",
  "JSON_template_handlebars": {
    "name": "Jane Doe",
    "account_level": "Premium"
  }
}

Template Data

The keys in your JSON_template_handlebars object must match the Handlebars variables (e.g., {{name}}) in your SendGrid template exactly.

Send Static Email

Sends a basic email with the content and subject defined directly in the inputs.

INFO

This component requires an API Key for authentication, as detailed in the Getting Started section.

Component-Specific Settings

• Content Type: Select text/plain for a plain text email or text/html to send HTML content.

Inputs

Field	Type	Required	Notes
from	string	Yes	The sender's email address (must be a verified sender).
to	string	Yes	The recipient's email address.
subject	string	Yes	The subject line of the email.
content	string	Yes	The body of the email (either plain text or HTML, based on the Content Type setting).

Outputs

Field	Type	Description
Response	object	A successful send returns an empty body with a 202 Accepted status code.
Headers	object	The HTTP headers from the API response.

Use Case

A monitoring agent detects that a server's disk space is low and uses this component to send a simple, plain text alert email to the IT administrators.

{
  "component": "sendgrid.sendStaticEmail",
  "from": "alerts@example.com",
  "to": "it-team@example.com",
  "subject": "CRITICAL: Server Disk Space Low",
  "content": "Server 'db-prod-01' has disk space below 10%. Please investigate immediately."
}

Best Practices & Advanced Tips

• Secure Your API Key: Always store your SendGrid API key in the SmythOS Vault. If a key is ever compromised, be sure to revoke it in your SendGrid account immediately.
• Use Dynamic Templates for Branding: For any user-facing email, it's best practice to use the Send Dynamic Email component. This allows you to maintain consistent branding and easily update email designs in SendGrid without changing your agent's logic.
• Verify Senders: Before you can send an email from an address (or domain), you must prove you own it by completing the Sender Authentication process in your SendGrid account.
• Monitor Your Email Activity: Use the SendGrid dashboard to monitor your email deliverability, open rates, and click rates to ensure your emails are reaching the inbox and engaging users.

Troubleshooting Common Issues

• Error: 401 Unauthorized

  • Cause: The API Key is incorrect, has been revoked, or does not have the required Mail Send permissions.
  • Solution: Verify that the API Key in your SmythOS Vault is correct and active. Check its permissions in your SendGrid account settings.

• Error: 403 Forbidden

  • Cause: A common cause is trying to send an email from an address that has not been verified as a Single Sender or part of an authenticated domain in your SendGrid account.
  • Solution: Go to your SendGrid settings and complete the Sender Authentication process for the from address.

• Emails Go to Spam

  • Cause: This is a complex deliverability issue often related to domain reputation, lack of proper authentication (like DKIM and SPF, which are part of Sender Authentication), or email content.
  • Solution: Ensure you have completed Sender Authentication in SendGrid. Avoid spammy-sounding subject lines and content.

• Dynamic Template Data Not Appearing

  • Cause: The keys in your JSON_template_handlebars input do not exactly match the variable names in your SendGrid template (e.g., {{name}} in the template vs. "username" in the JSON).
  • Solution: Carefully check that every key in your JSON payload matches the corresponding Handlebars variable in the template.

What's Next?

You are now ready to build powerful email automation workflows with the SmythOS SendGrid Integration!

Consider these ideas:

• Build an Agent That...

  • Manages a newsletter. The agent reads a list of subscribers from a database, fetches the latest blog post content, and sends a personalized weekly newsletter using a dynamic template.
  • Powers a password reset flow. When a user requests a reset, the agent generates a unique, single-use link and sends it to them using a secure SendGrid template.
  • Connects to your e-commerce platform. When an order ships, the agent sends a dynamic "Your Order is on its Way!" email, populating the template with the customer's name, order number, and tracking link.

• Explore Other Integrations:

  • Combine SendGrid with the Firebase Integration. When a new user is created in Firebase Auth, trigger an agent to send them a welcome email.
  • Use an LLM component to generate a personalized sales outreach message, then send it via the Send Static Email component.
  • Fetch data from a Google Sheet to power a mail merge, sending a dynamic email to each person listed in the sheet.