Mailgun integration

What it does

The Mailgun integration lets your agency drive a client's email program from inside a workflow. Connect a client's Mailgun API key once and your workflows can send transactional or marketing email through the v3 Messages endpoint, keep mailing lists and their members in sync with the client's source of truth, page through bounce-suppression lists, and react in real time when Mailgun posts a delivery or engagement event to the configured webhook URL.

Connect a Mailgun account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose Mailgun and click Connect.
3. In a new tab, open the Mailgun API keys page signed in as the client (or as your agency, if the client has delegated key creation to you).
4. Click Add new key, name it for the workspace, and select either a Sending key scoped to one domain or an Account key scoped to the whole account. Sending keys work for every action below as long as the connected sending domain matches.
5. Copy the key value, paste it into TaskJuice as the API key, and set the username to api. This is the literal Mailgun username for every HTTP Basic call.
6. Choose your region. Use us for accounts hosted at api.mailgun.net or eu for accounts hosted at api.eu.mailgun.net.
7. Enter the sending domain you have verified with Mailgun (for example mg.youragency.com). The Send Mail, List Events, and Get Bounces actions are scoped to this domain.

To rotate or revoke the key, return to the Mailgun API keys page, delete the entry, create a new key, and update the TaskJuice connection.

Triggers

• mailgun/delivery-event fires when Mailgun posts a delivery-lifecycle event (accepted, delivered, failed, rejected). One POST carries one event, and the workflow receives the signature envelope plus the full event-data payload as a single activation.
• mailgun/engagement-event fires when Mailgun posts an engagement event (opened, clicked, unsubscribed, complained, list_member_uploaded). One POST per event, same envelope shape.

Each trigger publishes an inbound URL. Paste it into Mailgun under Sending, Webhooks for the connected sending domain, and set the X-TaskJuice-Inbound-Secret header on the webhook URL to a shared secret you also paste into the TaskJuice trigger. TaskJuice verifies that header on every inbound POST before activating the workflow.

Actions

• mailgun/send-mail sends a transactional or marketing email through the v3 Messages endpoint for the connected sending domain, with optional Mailgun tags, tracking flags, and scheduled delivery time.
• mailgun/list-events pages through Mailgun's events store for the connected sending domain, optionally filtered by time window and event type, using the paging.next URL.
• mailgun/list-mailing-lists pages through every Mailgun mailing list in the account.
• mailgun/create-mailing-list creates a new Mailgun mailing list with an address, display name, description, and access level.
• mailgun/add-list-member adds or upserts a subscriber on a Mailgun mailing list.
• mailgun/remove-list-member removes a subscriber from a Mailgun mailing list by email address.
• mailgun/get-bounces pages through the current bounce-suppression list for the connected sending domain.

Known limitations

• The integration uses Mailgun's v3 REST API with the connected key. Per-account rate limits, daily send caps, and feature entitlements are governed by the client's Mailgun plan, not by TaskJuice. When Mailgun returns a 429, the action surfaces as a retryable rate-limit error and honors the recommended backoff.
• Inbound webhook verification uses a shared secret on a custom header set on the Mailgun webhook URL. Mailgun's first-party HMAC-SHA256 signature, which signs timestamp + token and places the digest in the request body, is not used by the declarative inbound verifier (it expects header-based signatures); treat the inbound URL plus the shared header as the secret and rotate it alongside the API key.
• The connected sending domain is fixed on the connection itself. To send from a second domain, create a second Mailgun connection scoped to that domain.
• The Mail Send action returns Mailgun's queue identifier in the id field. Use it, or a v: variable on the outbound message, to correlate downstream engagement events with the originating workflow run.
• Mailgun's region routing is account-level. EU accounts must use the eu region; US accounts must use us. A mismatch surfaces as a 401 from Mailgun.