Retool OpenAPI

Retool allows you to create an OpenAPI resource to connect to REST APIs using OpenAPI specifications. OpenAPI resources are integrations that allow you to securely connect to external services (e.g., Mailtrap) and automatically populate fields, such as, for example, query. This removes the need for manual configuration and improves accuracy.

In this guide, you'll learn how to connect Mailtrap's email delivery services to Retool using this approach, which allows you to:

• Send transactional emails: Automate internal processes like approval workflows, or trigger observability alerts when metrics drop below thresholds.

• Send bulk emails: Distribute newsletters or send legal/compliance notifications to your entire user base.

• Sync and manage contacts: Add users to onboarding lists or update contact fields to trigger automated email sequences.

• Manage suppressions: Review bounced/unsubscribed addresses and remove resolved emails to resume communication.

For the integration to work, you need to add and verify your email sending domain since Mailtrap allows you to send emails only from a verified domain.

How to configure a resource

In this section, we’ll show you how to configure Retool resources, which can be re-used in queries.

Step 1. Locate Mailtrap OpenAPI specifications

Mailtrap maintains its API definitions in a structured format. To implement this in Retool, you must use the YML specifications, which you can find under specs in mailtrap/mailtrap-openapi.

Once you choose your desired implementation, to ensure Retool can parse the schema correctly, be sure to click on Raw, so you can use the Raw URL of the YAML file.

Then, simply copy the URL:

Step 2. Configure a Resource in Retool

Navigate to the Resources tab in Retool and create a new OpenAPI resource.

There, you will need to configure the following settings:

Once you insert the required details, make sure to click Create resource. Also note that you will also be able to re-use this Resource across your projects.

Hint: To make sure you’ve entered everything correctly before using the Resource in your Queries, click on Test connection. If the connection works, you should get the following message:

How to configure queries

In the following section, we will show you some queries you can run with the OpenAPI resources connected to Mailtrap and possible use cases.

Transactional email sending

To send transactional emails, use the email-sending-transactional.openapi.yml. Transactional emails are executed via the POST /send endpoint.

Use cases:

Internal process automation

Trigger approval emails for vacation requests, hardware purchase requests, internal discount approvals, etc.

Observability alerts

Query implementation example: Select the POST /send endpoint, use the following structure of the request body, and add dynamic variables into the payload using {{ }} syntax where necessary:

Response:

Example code you can copy for the request body:

{
  "from": {"email": "[email protected]"},
  "to": [{"email": "{{ user_email }}"}],
  "subject": "Vacation Request Approved",
  "text": "The request for ID {{ request_id }} has been finalized."
}

Bulk email sending

To send bulk emails, use the email-sending-bulk.openapi.yml. POST /bulk/send endpoint is optimized for delivery of promotional or marketing emails to multiple recipients simultaneously through the Bulk stream.

Use cases:

Legal and compliance notifications

Send mandatory updates regarding Terms of Service (ToS) changes, Privacy Policy updates to the entire user database, etc.

Newsletter distribution

Query implementation example: Choose the POST /bulk/send endpoint and use a request body.

Response:

Example code you can use for the request body:

{
  "from": {"email": "[email protected]"},
  "to": [{"email": "[email protected]"}, {"email": "[email protected]"}],
  "bcc": [{"email": "[email protected]"}],
  "subject": "Monthly Newsletter",
  "html": "<h1>Privacy Policy Update</h1>",
  "category": "newsletter"
}

Contact synchronization and updates

To sync contacts from external databases or CRMs with Mailtrap or create, update, and manage contact lists, use the contacts.openapi.yml.

If used in combination with Mailtrap Automation feature, you can set up the query for:

User onboarding

Once a new customer is added to a specific "Onboarding" contact list, the onboarding email sequence will be sent automatically.

Lifecycle triggers

Query implementation example: Use the PATCH method with path parameters for account_id and contact_identifier to update specific metadata fields without overwriting the entire contact object.

Response:

Suppression list management

To get a list of your suppressions or delete certain emails from your suppression list use the account-management.openapi.yml. It uses the GET /suppressions and DELETE /suppressions/{id} endpoints with which you can maintain email deliverability standards.

Primary use cases:

Contacts review

Review the list of bounced or unsubscribed addresses to protect IP reputation.

List cleanup

Query implementation example: If you were to use the query to get a list of emails in your suppressions list, use GET /accounts/{account_id}/account_accesses, and specify your Mailtrap account ID.

Response:

Keep in mind that we take into account the suppressions for both transactional and bulk email sending.