In this guide, I’ll show you how to create and design a simple Retool contact form that allows your app/project users to send you an email by clicking the submit button.
Before configuring the Retool query, make sure you have:
- Mailtrap Account: If you haven’t already, sign up for a free Mailtrap account since we’ll use Mailtrap’s Email API and the Email Testing inbox we’ll use in this article.
- Basic Retool knowledge: Although Retool doesn’t require any coding skills, knowing how to use its editor (e.g., adding elements, etc) is a plus. But even if you’re brand new to Retool, I’ve covered all of the steps in great detail, so don’t worry.
Disclaimer: Every bit of the workflow in this article has been prepared by a developer and thoroughly tested before publication.
Create and configure a Retool form
To create and configure a Retool form, follow these steps:
Step 1. Create the form foundation
To get started, log in to your Retool workspace, click on Create, and then click App.
Then, in the Retool editor, drag a Form component from the component library on the sidebar on the left onto the canvas and give it a descriptive title (e.g. “Send Email Form”).
Step 2. Drag and drop the components
This form will act as a container for input fields, which you can add by clicking on Add components or by drag-and-dropping them from the left-side menu. On the right side, you can enter your desired details like placeholders, input names, etc.
For this demo, I’ve used the following components:
- Email for the “To” address.
- Text Input for the email subject line simply labeled as “Subject”.
- Text Area (multiline Text Input) for the Message Body, labeled as “Message” and set its key (e.g., message). This will be the plain text body (we will handle the HTML body separately later).
Step 3. Add validation rules
Once you’ve added the desired fields inside the form, you can mark the required fields in the ‘Validation rules’ on the right settings to prevent users from submitting the form without values.
Note: When you’re dragging the components onto the form, make sure that you’re matching the whole width of the box. Otherwise it will end up being smaller than you want it to be. See what I mean in the screenshot below:
Send emails with email API
To make our form send emails, let’s tie the Submit button to a sending action that leverages Mailtrap Email API on form submission.
Step 1. Connect the Submit button to an event
So, click on the Form, and on the right-side inspector panel, find the Event handlers tab, set the ‘Event’ to Submit and ‘Action’ to Control query.
Now, when the user clicks Submit (after passing validation), it will trigger a query of our choice.
Step 2. Create a new query
In the query selector, click on Create a new query.
Next, we’ll create a new query in Retool to call the Mailtrap API. In the opened left sidebar panel, give it a name (e.g., sendMailtrapEmail), and select REST API as a query type in the Resource part.
Step 3. Set up the Mailtrap API request
Since the query we’ve set up will perform the POST request to Mailtrap when the form is submitted, you need to add your Mailtrap API URL, which is https://send.api.mailtrap.io/api/send.
Next, add dd three headers required by Mailtrap:
- Content-Type: application/json → tells the API we are sending JSON data.
- Accept: application/json → we expect JSON response.
- Api-Token:
<your_mailtrap_api_token>→ this is your Mailtrap API authentication token.- Tip: You can find your Api-Token by logging into your Mailtrap account and navigating to Sending Domains → Transactional/Bulk Stream → Integration → API.
So far, your configuration should look like this:
Step 4. Configure the request body
Finally, let’s set up Body, which is JSON by default. The interface of setting up the body is divided in 2 columns: a key, and a value.
You will need to setup the following key/value pairs:
<strong>from</strong>:include an object value containing email and name properties. email property should match your email domain.
{
"email": "no-reply@your-domain",
"name": "Domain Name"
}<strong>to</strong>:include an array of objects. Each object contains email and name properties accordingly.
[
{
"email": "{{email1.value}}"
}
]- subject: include a string for your email subject.
New message from {{email1.value}}. Subject - {{textInput1.value}}- text: include a string for the plain text content of your email.
We have received your message ({{textArea1.value}})You can also use {{element.value}} syntax to extract values from the inputs of the previously created form. For example, for this demo, I’ve used {{email1.value}}, {{textInput1.value}}, etc., which you can see in the screenshot below. Without these, the form would just send nothing instead of live user input.
Step 5. Send a plain text email
At this point, our Retool app has a form UI and a query ready. So, let’s try to send a plain text email after having everything configured.
While you can manually run your form, Retool allows you to interact with it right within the editor even without running the app:
After submitting the form, an email should be sent successfully, which you can verify in your Mailtrap Email Logs tab.
Send HTML email
To adhere to the best industry practices, Mailtrap’s API lets you include an HTML version of the email in addition to plain text. This way, if a recipient of yours’ can’t render HTML, they’ll still be able to read your message.
Sending them is also super simple—you just need to add an html field in the JSON payload with the HTML content, like so:
Additionally, you can use any kind of HTML content that fits you best. For example, we can greet a user and notify him that we have successfully received his email and attach his message using {{textArea1.value}} dynamic value.
<h1>Hi from Mailtrap</h1>
<p>We received your <b>message:</b></p>
<br />
{{textArea1.value}}If you try to send an email again, you should now receive an HTML version of the email, as well as text version available as a fallback.
Send emails with attachments
To attach files such as images, PDFs, etc., let’s add a file selector to the form. In Retool, you can choose between File Button, File Dropzone, and File Input. All of them work for the attachment logic.
For this demo, we’ll use File Input.
Next, let’s update the body of the query for our API to include the new attachments property.
Using fileInput1.value[0], we can extract the selected file and add the values for according properties using name, base64Data, and type fields, just like so:
[
{
"filename": "{{fileInput1.value[0].name}}",
"content": "{{fileInput1.value[0].base64Data}}",
"type": "{{fileInput1.value[0].type}}",
"disposition": "attachment"
}
]And here’s what it should look like in the Retool UI:
Now, you can add any file from your drive by clicking on Browse!
Send emails to multiple recipients
To send emails to multiple recipients, simply include as many addresses as you want in the to array of your API’s body.
[
{
"email": "{{email1.value}}",
},
{
"email": "recipient2@example.com"
}
]Test emails and email sending
Okay, so, we’ve got our Retool form configured; it can HTML and plain text emails with attachments to multiple recipients, but how do we make sure our designs are rendered correctly across all email clients? How do we check if our domain is not blacklisted or that our emails are passing spam filters? 🏮
For all of the above and more, I use Mailtrap Email Testing, another inseparable part of Mailtrap Email Delivery Platform.
Mailtrap Email Testing provides me with a safe environment to inspect and debug emails in staging, dev, and QA environments. Additionally, I can use it to preview and analyze content for spam and validate HTML/CSS before sending emails to recipients in production!
To start testing emails in your Retool form, all you need to do is:
- Create a free Mailtrap account.
- Navigate to Email Testing and choose your inbox.
- Find the Api Token and API URL + Inbox ID.
- Then, copy these two as in the example below:
And that’s it! From now on, every email sent will only appear in the Email Testing inbox, where you can:
- Preview how your emails look in plain text or HTML on different devices.
- Inspect if your emails are rendered properly by different email clients (e.g., Gmail, Outlook, Yahoo, etc.)
- Get some useful tech details like SMTP transactions and email header info.
- Use the detailed list of spam points to fix my emails, avoid spam filters, and prevent email deliverability issues once your app moves to production.
Pro tip: To make it more flexible, you can even create a separate REST API query to handle email testing apart from the main email-sending logic!
