Messaging & email

SendGrid

Overview

SendGrid is a cloud-based email delivery platform that enables your Emergent app to send transactional and marketing emails reliably. Common use cases include password resets, order confirmations, notifications, and automated email campaigns.

This guide shows you how to integrate SendGrid with your Emergent app using environment variables and the SendGrid API.

Note

SendGrid offers a free tier with 100 emails per day, which is sufficient for testing and small applications. Production apps typically require a paid plan.

Prerequisites

Before you begin, you'll need:

  • A SendGrid account (sign up)
  • An active Emergent project
  • Basic familiarity with environment variables

Setting up SendGrid

1

Create a SendGrid API key

  1. Log in to your SendGrid dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Choose Restricted Access and enable Mail Send permissions (recommended for security)
  5. Name your key (e.g., 
    emergent-production
    )
  6. Copy the generated API key immediately - it won't be shown again
2

Verify a sender identity

SendGrid requires you to verify the email address or domain you'll send from:

  1. Go to Settings → Sender Authentication
  2. For testing: verify a Single Sender email address
  3. For production: set up Domain Authentication to improve deliverability

Check your inbox for the verification email and follow the link.

3

Add the API key to your Emergent app

In the Emergent chat, add your SendGrid API key as an environment variable:

Add environment variable 

SENDGRID_API_KEY
with value 
SG.xxxxx...

Mark this variable as secret to prevent it from appearing in logs or client-side code.

4

Configure sender details

Store your verified sender email as an environment variable for easy reuse:

Add environment variable 

SENDGRID_FROM_EMAIL
with value 
noreply@yourdomain.com

Optionally add 

SENDGRID_FROM_NAME
for a friendly sender name.

Sending emails from your app

Once configured, you can send emails using the SendGrid Node.js SDK or REST API. Here's how to implement common email scenarios:

Transactional emails

(The agent writes and wires up this code for you.)

(The agent writes and wires up this code for you.)

Using templates

SendGrid's Dynamic Templates let you design emails visually and populate them with data:

(The agent writes and wires up this code for you.)

Tip

Create templates in the SendGrid dashboard under Email API → Dynamic Templates. Copy the template ID (starts with 

d-
) and pass it in your code.

Testing email delivery

Test mode

During development, consider these strategies to avoid sending real emails:

SendGrid's sandbox mode validates requests without sending actual emails:

(The agent writes and wires up this code for you.)

Monitoring delivery

Track email activity in the SendGrid dashboard:

  1. Go to Activity to see recent sends, bounces, and opens
  2. Check Suppressions for bounced or unsubscribed addresses
  3. Review Statistics for delivery rates and engagement metrics

Warning

High bounce rates can damage your sender reputation. Regularly clean your email list and honor unsubscribe requests.

Common patterns in Emergent apps

Scheduled notifications

Use SendGrid's 

sendAt
parameter to schedule emails for a future time (up to 72 hours):

(The agent writes and wires up this code for you.)

Batch sending

Send the same email to multiple recipients efficiently:

(The agent writes and wires up this code for you.)

Info

For large batches (1000+ recipients), consider using SendGrid's batch ID feature to cancel or pause sends if needed.

Troubleshooting

  • Verify your sender identity in the SendGrid dashboard
  • Check the Activity feed for delivery status and errors
  • Ensure 
    SENDGRID_API_KEY
    is set correctly and has Mail Send permissions
  • Look for emails in spam/junk folders (improve this with domain authentication)

Your API key likely lacks the necessary permissions. Create a new key with Mail Send enabled under Restricted Access.

Free accounts are limited to 100 emails per day. Upgrade your SendGrid plan or implement retry logic with exponential backoff for production apps.

Include an unsubscribe link in marketing emails to comply with regulations:

(The agent writes and wires up this code for you.)

SendGrid automatically adds an unsubscribe footer when enabled.

Best practices

Use templates

Design emails visually in SendGrid and keep HTML out of your codebase. Templates are easier to update and A/B test.

Authenticate your domain

Set up SPF, DKIM, and DMARC records to improve deliverability and avoid the spam folder.

Handle errors gracefully

Wrap 

sgMail.send()
in try-catch blocks and log failures for investigation. Don't block user workflows on email delivery.

Monitor suppressions

Regularly check bounced and unsubscribed addresses. Remove them from your database to maintain a healthy sender reputation.

Was this page helpful?

Related pages