How to Integrate Retool with SendGrid

Start by creating a dedicated API key for your Retool integration in SendGrid. Log into app.sendgrid.com, navigate to Settings → API Keys, and click Create API Key. Give it a name like 'Retool Integration' so you can identify it later. Select Restricted Access and configure the specific permissions your Retool apps will need: - Mail Send: Full Access (required to send emails) - Suppressions: Full Access (required to read and manage bounces/blocks) - Marketing → Contacts: Full Access (required to manage contact lists) - Stats: Read Access (required for email analytics queries) Avoid granting Full Access at the top level — restrict to only what your Retool dashboard actually uses, following the principle of least privilege. Copy the generated key immediately, as SendGrid only shows it once. Now open Retool and navigate to the Resources tab. Click Add Resource and search for or scroll to 'SendGrid'. Click SendGrid to open the configuration form: - Name: enter a clear name like 'SendGrid Production' - API Key: paste the key you just created Click Save Changes. The SendGrid resource is now available in the query editor for any Retool app in your organization. If you have both a test SendGrid account and a production one (separate SendGrid accounts with separate API keys), create a second resource for the test environment.

Open a Retool app (or create a new one) and click + New in the query editor to create a new query. Select your SendGrid resource and set the Action Type to Send Email. The query editor reveals a form with the email sending parameters: - To: the recipient email address — reference a component or query field like {{ customerTable.selectedRow.email }} - From: your verified SendGrid sender email address (must be verified in SendGrid Dashboard → Settings → Sender Authentication) - Subject: the email subject line, which can include dynamic values: 'Your order {{ ordersQuery.selectedRow.order_id }} has been shipped' - Body (HTML): the HTML email body. Use a Retool text area component to let users customize the message, referenced as {{ emailBodyInput.value }} - Body (Plain Text): plain text fallback version Set the query's Trigger to Manual mode so it only fires when explicitly triggered, not on page load or when inputs change. Drag a Button component onto the canvas. In the Inspector, go to Interaction → Add Event Handler, set Action to 'Trigger query', and select your send email query. Enable the 'Confirm before running' toggle and set the confirmation message to 'Send email to {{ customerTable.selectedRow.email }}?' — this prevents accidental sends. Test by entering a real recipient email address (your own, during testing) and clicking the button. Check your inbox to verify the email arrived with the correct subject, body, and from address. Check the query run log in Retool's bottom panel to see the SendGrid API response.

For operational emails that need consistent branding and formatting — password resets, shipping confirmations, invoice summaries — use SendGrid Dynamic Templates rather than building HTML in the query editor. Dynamic Templates let your design team maintain the visual design in SendGrid's template editor while Retool operators fill in the data variables. First, create a Dynamic Template in the SendGrid Dashboard under Email API → Dynamic Templates. Design the template using the SendGrid Design Editor or code editor. In the template body, use Handlebars syntax for variable placeholders: {{ customer_name }}, {{ order_id }}, {{ tracking_url }}. Note the Template ID shown at the top of the template (format: d-xxxxxxxx). In Retool, create a new query using your SendGrid resource. Set Action Type to Send Email. In the form, you'll see a Template ID field — enter the template ID from SendGrid. Below it, a Dynamic Template Data section appears (as a JSON input). Enter the variable values that map to your template's Handlebars placeholders: Set Trigger to Manual and wire the query to a button with a confirmation dialog. When the button is clicked, Retool sends the API request with the template ID and variable data, and SendGrid renders the final email by substituting the variables into the template HTML before delivery.

1// Dynamic Template Data JSON — enter this in the query editor's Template Data field
2// Variables must match the Handlebars placeholders in your SendGrid template exactly
3{
4  "customer_name": "{{ customerTable.selectedRow.first_name }} {{ customerTable.selectedRow.last_name }}",
5  "order_id": "{{ customerTable.selectedRow.order_id }}",
6  "order_date": "{{ new Date(customerTable.selectedRow.created_at).toLocaleDateString() }}",
7  "total_amount": "${{ (customerTable.selectedRow.total_cents / 100).toFixed(2) }}",
8  "tracking_url": "{{ customerTable.selectedRow.tracking_url || 'Not yet available' }}",
9  "support_email": "support@yourcompany.com"
10}

Email deliverability issues — bounces, spam complaints, and blocks — can damage your sender reputation if left unaddressed. Build a Retool monitoring panel that surfaces these problems by querying SendGrid's suppression lists. Create three separate queries using your SendGrid resource: 1. Get Bounces (Action Type: Get Bounces or List Bounces) — retrieves all email addresses that have hard or soft bounced 2. Get Spam Reports — retrieves addresses that marked your emails as spam 3. Get Blocks — retrieves addresses that were blocked by receiving mail servers Set all three queries to Auto trigger on page load. Drag three Table components onto the canvas, one for each suppression type. In each table's Data source field, set it to the corresponding query's data output. Add a Date Range filter at the top of the page. Wire the start and end date values to all three queries' parameters to filter suppressions by the time period of interest. Add a text summary at the top showing totals: 'Bounces: {{ bouncesQuery.data.length }} | Spam Reports: {{ spamQuery.data.length }} | Blocks: {{ blocksQuery.data.length }}'. For each table, add a row action button: 'Remove from suppression list'. Wire this button to a Delete Suppression query that passes the selected email address and suppression type. Add a confirmation dialog: 'Remove {{ table1.selectedRow.email }} from bounce suppression?' After deletion, add an On Success event handler to re-run the fetch query so the table updates immediately.

1// JavaScript transformer to unify and format suppression data
2// Use this if combining all suppression types into a single table view
3const bounces = bouncesQuery.data || [];
4const spamReports = spamReportsQuery.data || [];
5const blocks = blocksQuery.data || [];
6
7const formatEntry = (entry, type) => ({
8  email: entry.email,
9  type: type,
10  reason: entry.reason || entry.description || '',
11  created: entry.created
12    ? new Date(entry.created * 1000).toLocaleDateString()
13    : 'Unknown'
14});
15
16return [
17  ...bounces.map(e => formatEntry(e, 'Bounce')),
18  ...spamReports.map(e => formatEntry(e, 'Spam Report')),
19  ...blocks.map(e => formatEntry(e, 'Block'))
20].sort((a, b) => b.created - a.created);

For marketing and growth teams that manage SendGrid marketing lists, Retool can provide a more flexible interface for adding, removing, and auditing contacts than SendGrid's own Marketing Campaigns UI, especially when contact data needs to be cross-referenced with your internal database. Create a query using Action Type Get All Lists to fetch your SendGrid marketing lists. Wire the result to a Select component on the canvas so the user can choose which list to work with. Create a second query using Get Contacts (or Search Contacts) — configure the List ID parameter to reference {{ listSelector.value }}. Set this query to run automatically when the list selector changes, so the contact table updates whenever the user switches lists. To add contacts to a list, create an Add Contacts query. In the query body, pass the contacts array referencing selected rows from your database: {{ selectedDatabaseContacts.data.map(c => ({ email: c.email, first_name: c.first_name, last_name: c.last_name })) }}. Wire this to an 'Add to List' button that only enables when rows are selected in your database contacts table. Important: SendGrid's Add Contacts operation is asynchronous — it returns a job ID, not immediate confirmation. To handle this, create a follow-up query using Get Contact Import Status that polls with the returned job ID. Alternatively, simply show a 'Contacts queued for import' message via a Show Notification event handler, making it clear to the user that there may be a brief delay before contacts appear in SendGrid.

1// JavaScript transformer to prepare contacts for SendGrid bulk add
2// Use this to reshape your internal database contact records
3// into the format SendGrid's Add Contacts API expects
4const internalContacts = databaseContactsQuery.data || [];
5
6return internalContacts
7  .filter(contact => contact.email && contact.email.includes('@')) // basic email validation
8  .map(contact => ({
9    email: contact.email.toLowerCase().trim(),
10    first_name: contact.first_name || '',
11    last_name: contact.last_name || '',
12    custom_fields: {
13      // Map your internal fields to SendGrid custom field IDs
14      // Custom field IDs are found in SendGrid → Marketing → Custom Fields
15      e1_T: contact.account_tier || '', // example custom field
16      e2_D: contact.signup_date || ''   // example date custom field
17    }
18  }));