SMTP query tutorial

Learn how to send email using an SMTP resource.

Retool 4.34.12 StableClassic apps

All plans

Classic apps

You're viewing documentation for classic apps, which use Retool's original app editor. The new app builder is the recommended way to build apps and where Retool focuses new development.

After setting up an SMTP integration with Retool, your SMTP resource is available to use in the query editor. An SMTP query sends a single email using the fields you configure below.

Create a query

Classic app

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

To create an SMTP query in a Retool app:

1. In the Retool app IDE, open the Code tab, then click + in the page or global scope.
2. Select Resource query.
3. Choose your SMTP resource.
4. Configure the email fields and save the query.

Workflow or agent

Workflows and agent custom tools use the same Resource query block to send email with SMTP.

1. Add a Resource query block to your workflow or custom tool's function canvas.
2. Choose your SMTP resource.
3. Configure the email fields and save the query.

Custom tools use the same block-based canvas as workflows, so the steps are identical in either context.

Query configuration fields

An SMTP query has a single action: send an email. Configure the following fields to compose the message.

From email

The sender address for the email, and optionally a display name.

Example

"Support team" support@example.com

Add reply-to

Enable this option to show a Reply-To field. Set it to an address that should receive replies, if different from the From email address.

Example

replies@example.com

To

The recipient address or addresses. Separate multiple addresses with commas.

Static example

customer@example.com

Dynamic example

{{ emailInput1.value }}

Add Cc/Bcc

Enable this option to show separate Cc and Bcc fields for additional recipients. Separate multiple addresses with commas in each field.

Example

Cc: manager@example.com, teamlead@example.com
Bcc: audit@example.com

Subject

The subject line of the email.

Example

{{ "Order confirmation #" + orderTable.selectedRow.data.id }}

Body

The content of the email. Use the Text, HTML, or Markdown toggle to choose the format, then write or generate the message in the code editor. Click Preview to see how an HTML or Markdown message renders before sending it.

plain text body

Example

Hi {{ customerTable.selectedRow.data.name }},

Your order has shipped and should arrive within 3-5 business days.

HTML body

Example

<p>Hi {{ customerTable.selectedRow.data.name }},</p>
<p>Your order has shipped and should arrive within 3-5 business days.</p>

markdown body

Example

Hi {{ customerTable.selectedRow.data.name }},

**Your order has shipped** and should arrive within 3-5 business days.

Attachment

Files to attach to the email. Set this field to a component that produces file objects, such as a File Button, File Dropzone, or File Input, or to the result of a query that returns file objects, such as a Retool Storage query.

Example

{{ fileInput1.value }}

In-Reply-To

The message ID of an existing email to reply to. Use this field to thread a new message under an existing email conversation instead of starting a new thread.

Example

{{ incomingMessage.data.messageId }}

Common use cases

The following examples demonstrate typical SMTP operations in Retool apps.

send a simple email

First, add a Button component to the app.

Next, create an SMTP query (sendEmailQuery) with the following fields.

Field	Value
From email	"Support team" support@example.com
To	{{ emailInput1.value }}
Subject	Thanks for reaching out
Body	Hi, we received your message and will respond shortly.

Then, add an event handler to the button's Click event that runs sendEmailQuery.

send an email with an attachment

First, add a File Input component to the app so users can upload a file.

Next, create an SMTP query and set its Attachment field to the File Input component.

Example

{{ fileInput1.value }}

Then, add an event handler to a form's Submit event that runs the query, sending the uploaded file along with the message.

send to multiple recipients

First, enable Add Cc/Bcc on an SMTP query to show the additional recipient fields.

Next, configure the recipient fields.

Field	Value
To	{{ table1.selectedRow.data.customerEmail }}
Cc	{{ table1.selectedRow.data.accountManagerEmail }}
Bcc	audit@example.com

The email sends to all three addresses, with Cc and Bcc recipients visible only according to standard email conventions.

send dynamic content from a form

First, add a Form component with fields for a recipient, subject, and message.

Next, create an SMTP query and reference the form's data in the relevant fields.

To

{{ form1.data.recipient }}

Subject

{{ form1.data.subject }}

Body

{{ form1.data.message }}

Then, add an event handler to the form's Submit event that runs the query and shows a success notification.

reply to an existing email thread

First, retrieve the original message and store its message ID, for example from a query that reads incoming mail.

Next, create an SMTP query and set the In-Reply-To field to the original message's ID.

Example

{{ getMessageQuery.data.messageId }}

Setting Subject to the same subject as the original message, prefixed with Re:, keeps the reply grouped with the original thread in most mail clients.

Best practices

Follow these best practices to keep SMTP queries fast, efficient, and safe.

Performance

• Avoid large attachments: Keep attachment sizes small where possible, since large attachments increase query execution time and can be rejected by some mail servers.
• Set appropriate timeouts: Configure query timeouts based on your SMTP server's expected response time to prevent hung requests.
• Batch notifications carefully: When sending to many recipients, use Bcc or iterate over a list rather than triggering many individual queries in quick succession, to avoid rate limiting from your mail provider.

Data integrity

• Validate email addresses: Validate recipient addresses in a form or transformer before running the query to prevent failed sends and bounces.
• Handle errors gracefully: Configure error notifications and fallback behavior for failed queries so users know if a message didn't send.
• Verify sender addresses: Confirm the From email address is authorized to send through your SMTP server to avoid rejected or flagged messages.
• Log query activity: Enable query logging to track which emails were sent, when, and to whom, for auditing and debugging.