Skip to main content

SMTP query tutorial

Learn how to send email using an SMTP resource.

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​

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.

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.

FieldValue
From email"Support team" support@example.com
To{{ emailInput1.value }}
SubjectThanks for reaching out
BodyHi, 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.

FieldValue
To{{ table1.selectedRow.data.customerEmail }}
Cc{{ table1.selectedRow.data.accountManagerEmail }}
Bccaudit@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.