How to Integrate Retool with Mailgun

Log into your Mailgun Dashboard at app.mailgun.com. Navigate to Settings (gear icon in the left sidebar) → API Keys. You will see two types of keys: 1. Private API Key — starts with key-XXXXXXXX. This is the key to use for Retool. It has full access to send emails, access logs, and manage suppressions. 2. HTTP Webhook Signing Key — used for verifying webhook payloads. Do NOT use this for API authentication. 3. Public Validation Key — used for client-side email validation. Do NOT use this for backend API access. Copy the Private API Key value. Store it immediately in Retool Settings → Configuration Variables as MAILGUN_API_KEY marked as secret. Next, determine your Mailgun region. If you signed up through the standard mailgun.com signup and your account dashboard URL is app.mailgun.com, your region is US and you use: https://api.mailgun.net/v3 If you signed up specifically for the EU region (your dashboard might show eu.mailgun.com), use: https://api.eu.mailgun.net/v3 Also note your primary sending domain name (e.g., mg.yourcompany.com or mail.yourcompany.com) — this is required in many Mailgun API endpoint paths. Find it in Mailgun Dashboard → Sending → Domains.

In Retool, navigate to the Resources tab and click Add Resource. Select REST API. Name: Mailgun API Base URL: https://api.mailgun.net/v3 (for US region) or https://api.eu.mailgun.net/v3 (for EU region) Authentication: Select Basic Auth. - Username: api (literally the word 'api' — this is a fixed value, not your email address) - Password: {{ retoolContext.configVars.MAILGUN_API_KEY }} (or paste your key directly) This is different from Mailchimp's 'anystring' — Mailgun specifically requires 'api' as the username. Using any other username (even your email address) causes authentication to fail. Headers: - Key: Content-Type | Value: application/x-www-form-urlencoded (for POST requests like sending email — use application/json for GET queries) Click Create Resource. Test the connection by creating a query with method GET and path /domains — this should return a JSON object with a list of your verified Mailgun domains. If it returns a 401 Unauthorized, double-check that Username is exactly 'api' and the Password is your Private API Key (not the validation key). Note: Many Mailgun endpoints include the domain name in the path — for example /YOUR_DOMAIN/events. You'll reference your domain in query paths using a Retool variable, not in the base URL.

Mailgun's Events API is the core of delivery monitoring. Create a query named getEvents. Set the method to GET and path to /{{ select_domain.value }}/events. Key query parameters: - begin: {{ new Date(dateRange.start).toUTCString() }} — start of event window (RFC 2822 format or Unix timestamp) - end: {{ new Date(dateRange.end).toUTCString() }} — end of event window - ascending: no (newest events first) - limit: 100 — events per page (max 300) - event: {{ select_event_type.value || '' }} — filter by event type: 'delivered', 'bounced', 'failed', 'complained', 'unsubscribed', 'opened', 'clicked' - recipient: {{ textInput_email.value || '' }} — filter by recipient address - subject: {{ textInput_subject.value || '' }} — filter by subject line The response includes an items array of event objects and a paging object with cursor URLs for pagination. Each event object contains event type, timestamp, message (with headers including subject and message-id), recipient, and delivery-status (for failed/bounced events with error codes and descriptions). Create a transformer to flatten the nested message headers and delivery status into displayable columns. Extract the Subject and From headers from the deeply nested message.headers object.

1// Transformer for Mailgun events
2const events = data.items || [];
3return events.map(e => {
4  const headers = e.message?.headers || {};
5  const deliveryStatus = e['delivery-status'] || {};
6  return {
7    event: e.event,
8    timestamp: e.timestamp ? new Date(e.timestamp * 1000).toLocaleString() : '',
9    recipient: e.recipient || '',
10    sender: headers['from'] || '',
11    subject: headers['subject'] || '(no subject)',
12    message_id: headers['message-id'] || '',
13    status_code: deliveryStatus.code || '',
14    status_message: deliveryStatus.message || '',
15    error_description: deliveryStatus.description || '',
16    geolocation: e.geolocation ? `${e.geolocation.city || ''}, ${e.geolocation.country || ''}`.replace(/^,\s*|,\s*$/g, '') : '',
17    user_agent: e['user-agent'] || ''
18  };
19});

Mailgun tracks three types of suppressions that prevent future delivery: bounces (permanent delivery failures), complaints (spam reports), and unsubscribes (opt-outs). Build separate queries for each type and combine them into a tabbed Retool UI. getBounces: GET /{{ select_domain.value }}/bounces - limit: 100 - Response: array of {address, code, error, created_at} getComplaints: GET /{{ select_domain.value }}/complaints - limit: 100 - Response: array of {address, created_at} getUnsubscribes: GET /{{ select_domain.value }}/unsubscribes - limit: 100 - tag: optional tag filter - Response: array of {address, tags, created_at} To remove a suppression (re-enable delivery to an address), create write queries: - deleteBounce: DELETE /{{ select_domain.value }}/bounces/{{ table_bounces.selectedRow?.data?.address }} - deleteComplaint: DELETE /{{ select_domain.value }}/complaints/{{ table_complaints.selectedRow?.data?.address }} - deleteUnsubscribe: DELETE /{{ select_domain.value }}/unsubscribes/{{ encodeURIComponent(table_unsubscribes.selectedRow?.data?.address || '') }} Set all DELETE queries to Manual trigger only. Wire them to a 'Remove Suppression' button with a confirmation modal. On Success, trigger the appropriate GET query to refresh the list. For customer support use cases, add a 'Search Any Suppression' query that searches across all three suppression types for a given email address using three parallel queries combined in a JavaScript query.

1// Combined suppression search across all types
2const email = textInput_search_email.value;
3if (!email) return [];
4
5// Run all three lookups in parallel
6const [bounces, complaints, unsubscribes] = await Promise.all([
7  getBounces.trigger({ additionalScope: { search_email: email } }),
8  getComplaints.trigger({ additionalScope: { search_email: email } }),
9  getUnsubscribes.trigger({ additionalScope: { search_email: email } })
10]);
11
12const results = [];
13(bounces?.items || []).forEach(b => results.push({ ...b, suppression_type: 'Bounce' }));
14(complaints?.items || []).forEach(c => results.push({ ...c, suppression_type: 'Complaint' }));
15(unsubscribes?.items || []).forEach(u => results.push({ ...u, suppression_type: 'Unsubscribe' }));
16
17return results;

Create aggregate delivery analytics using the Events API with event type filtering. To compute delivery rates, query total accepted events and compare with delivered events: For domain statistics, use Mailgun's Stats API: GET /{{ select_domain.value }}/stats/total with: - event: delivered,bounced,failed,complained (comma-separated) - start: {{ moment(dateRange.start).format('YYYY-MM-DD') }} - duration: {{ diffDays }}d — number of days to aggregate - resolution: day — aggregate by day (or 'hour' for intraday trends) The stats endpoint returns pre-aggregated counts per time bucket — much more efficient than fetching all individual events for rate calculations. Transform the stats response to compute daily delivery rate: delivered / (delivered + failed + bounced). Display this in a Line Chart component. For alerting: create a Retool Workflow that runs every hour and calls the stats endpoint for the last hour. If the bounce rate exceeds a threshold (e.g., 5%), trigger a Slack notification via the Slack Resource. Store the threshold as a Retool Configuration Variable so it can be adjusted without editing the Workflow. For complex multi-domain delivery monitoring with automated alerting, RapidDev's team can help design the Workflow architecture and notification routing logic.

1// Transformer for delivery rate trend chart
2const stats = data.stats || [];
3return {
4  dates: stats.map(s => new Date(s.time).toLocaleDateString()),
5  delivered: stats.map(s => s.delivered?.total || 0),
6  bounced: stats.map(s => s.bounced?.total || 0),
7  failed: stats.map(s => s.failed?.total || 0),
8  delivery_rate: stats.map(s => {
9    const delivered = s.delivered?.total || 0;
10    const total = delivered + (s.bounced?.total || 0) + (s.failed?.total || 0);
11    return total > 0 ? parseFloat(((delivered / total) * 100).toFixed(1)) : null;
12  })
13};