Mailgun integration

What it does

The Mailgun integration lets your agency run a client's email program from inside a workflow. Send one-off or templated email, keep mailing lists and suppression lists in sync with the client's CRM, and start workflows the moment Mailgun accepts, delivers, bounces, or tracks an email, or receives one. Webhook triggers are registered on the client's Mailgun account for you, so there is nothing to paste into Mailgun.

Connect a Mailgun account

1. In Mailgun, open Account Settings, then API keys, and click Create key. Give it the Developer role and copy the key. Mailgun shows it only once.
2. In TaskJuice, open Connections, choose Mailgun, and click Connect.
3. Enter api as the username and paste the key.
4. Enter the API host for the account's region: api.mailgun.net for US accounts, or api.eu.mailgun.net for EU accounts.
5. Enter the sending domain your actions should use, for example mg.youragency.com.

Use an account key, not a domain Sending key. Sending keys can only send email, so webhooks, routes, lists and suppressions would fail with them. To rotate the key, create a new one in Mailgun, update the connection, then delete the old key.

Triggers

You do not register these yourself. When you publish a workflow, TaskJuice registers an account-level webhook for each event your workflows use, covering every sending domain on the account. Mailgun can take up to 10 minutes to start sending after a change.

Turning a workflow off or deleting it stops deliveries reaching it but leaves the registration in place at Mailgun. It is marked dormant and cleaned up automatically later. Removing the Mailgun connection deletes the registrations right away, and you can also delete them yourself in Mailgun under Webhooks.

The event arrives under event-data. Use the Custom data field on Send Mail to attach your own IDs to a message. Mailgun returns them on every event for that message as event-data.user-variables, so you can match events back to your records.

For New Inbound Email, enter the address to watch, for example support@mg.youragency.com. Publishing creates a Mailgun route that stores mail sent to that address and notifies the workflow. Your other routes keep working. The route is cleaned up the same way as the webhooks above. The address must be on a domain whose MX records point at Mailgun. The message arrives as flat fields such as sender, subject, body-plain and stripped-text. Attachments arrive as download links in attachments, and message-url fetches the whole message. Mailgun keeps stored messages for 3 days. Use a lowercase address made of letters, digits, dots, hyphens and underscores.

Actions

Sending

• Send Mail: send an email you write, or a stored Mailgun template with variables. Supports Cc, Bcc, Reply-To, one attachment, tags, open and click tracking, scheduled delivery, per-recipient variables for batch sends, custom data, and test mode.

Mailing lists and members

• Create, Get, Update, Delete and List Mailing Lists.
• Add List Member, Add List Members in Bulk (up to 1,000 at a time), Get, Update, Remove and List List Members.

Suppressions (on the connected sending domain)

• Bounces: Get Bounces (list), Get Bounce, Add Bounce, Remove Bounce.
• Unsubscribes: List Unsubscribes, Get Unsubscribe, Add Unsubscribe, Remove Unsubscribe.
• Complaints: List Complaints, Get Complaint, Add Complaint, Remove Complaint.

Validation (needs a paid Mailgun plan)

• Validate Email Address, Start List Validation, Get List Validation Result, Start Bulk Email Validation (upload a CSV), Get Bulk Validation.

Templates, analytics and events

• List Templates, Get Template, Get Sending Metrics, List Events.

Domains and routes

• List Domains, Get Domain, Create Route, List Routes, Delete Route.

Known limitations

• Actions use the sending domain saved on the connection. To work with a second domain, add a second Mailgun connection.
• Email validation is a paid Mailgun feature. On the Free plan the validation actions return a "paid accounts only" error.
• Mailgun's Free plan allows one inbound route, so it supports one New Inbound Email address at a time. A second one reports that the account's route limit is reached.
• Mailgun allows at most three webhook URLs per event type on an account. If the account already uses all three for an event, publishing a workflow that needs it reports that the webhook limit is reached. Remove an unused webhook in Mailgun, then republish.
• Inbound attachments are links, not files. Download them within Mailgun's 3-day storage window.
• Sandbox domains can only send to authorized recipients you add in Mailgun.
• Mailgun rate limits and daily sending caps depend on the client's plan. A rate-limited call is retried automatically.