Skip to main content
Applies to: Cloud and 3.268.0-edge

Configure email triggers for Agents using Mailgun

Learn how to set up email triggers with Mailgun for Agents on Self-hosted deployments.

Retool Agents Availability
Cloud-hostedPublic beta
Self-hosted (3.268 Edge)Public beta
Self-hosted (3.196 Stable and later)

Self-hosted organizations can implement email triggers for Agents using Mailgun, a paid, third-party mail service.

If your Self-hosted environment is behind a VPN, and you want to trigger agents via email, make sure your api/agents/emailWebhook endpoint is accessible by Mailgun. Refer to Mailgun's Webhooks documentation for the domain that will need access to your webhook.

Setting up a Mailgun account and enabling the environment variables using the process described below allows you to send an email to your agent, which Mailgun forwards to your Self-hosted deployment as a webhook event, which then triggers the agent to run.

Requirements​

To implement email triggers, you need:

  • A verified Mailgun account.
  • A custom domain to use with Mailgun.
  • Ingress for Mailgun to send webhook notifications.
  • A webhook endpoint URL reachable by Mailgun. Tools such as ngrok can be used to accomplish this.

Set up Mailgun​

Complete the following steps to configure Mailgun:

  1. Add a new custom domain and verify it. Do not use the sandbox domain Mailgun creates automatically upon login.

  2. Create a new Receiving Route and toggle on Store and notify and enable Message Retention. Retool uses Mailgun's Messages API to look up the message, so it is important to enable Store and Notify and Message Retention, otherwise, the following error message will display: {"message":"Message retrieval disabled for domain"}. Message retention durations are limited by the Mailgun plan selected.

    Create a new Receiving Route in Mailgun.

  3. Create an endpoint URL and update any firewall configuration so that it is reachable by Mailgun. You can use tools such as Ngrok to create a URL. For example: https://<your_subdomain>.ngrok-free.app/api/agents/emailWebhook.

  4. In Mailgun, add a new Webhook and provide the webhook URL you created for your agent.

    Provide your webhook endpoint URL.

    The Webhooks page of the Mailgun dashboard.

Environment variables​

Set the following environment variables within your deployment's configuration file.

  • MAILGUN_WEBHOOK_API_KEY - The HTTP webhook signing key found in the Webhooks section of your Mailgun dashboard.
  • MAILGUN_API_KEY - The Mailgun API key found in the API Security section of your Mailgun dashboard. Refer to Mailgun's help page for more information.
  • AGENT_EMAIL_DOMAIN - The domain of your email address. For example, if your email is johndoe@retool.com then your email domain is retool.com.

Set up a custom tool for email​

The Send Email and Reply to Email tools are not supported for Self-hosted deployments. To send email or reply to an email on a Self-hosted deployment, create a custom tool to connect to an agent with an email resource like SMTP or Twilio.