Mailgun Setup

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkDeclared1 observation
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Run the store script to securely collect the API key:

callbackUrl = data.callbackUrl || data.url || data.callback_url;

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/skills/mailgun-setupThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Set up and send emails via a user-provided Mailgun account (BYO email provider)

---
name: mailgun-setup
description: Set up and send emails via a user-provided Mailgun account (BYO email provider)
compatibility: "Designed for Vellum personal assistants"
metadata:
  icon: assets/icon.svg
  emoji: "📬"
  vellum:
    category: "email"
    display-name: "Mailgun Email Setup"
    user-invocable: true
---

## Overview

Send emails through the user's own Mailgun account. The user provides their Mailgun API key and domain, and you send via their infrastructure.

## Setup

### Step 0: Check Existing Configuration

Before starting, check whether Mailgun is already configured:

```bash
bun skills/mailgun-setup/scripts/check-config.ts
```

The script outputs JSON: `{ "configured": boolean, "hasApiKey": boolean, "hasWebhookKey": boolean, "details": string }`.

- If `configured` is `true` — Mailgun is already set up. Offer to verify the connection or reconfigure.
- If `configured` is `false` — continue to Step 1.

### Step 1: Store the API Key

Run the store script to securely collect the API key:

```bash
bun skills/mailgun-setup/scripts/store-api-key.ts
```

The script opens a secure credential prompt, stores the key, and exits. If it exits 0, the key is stored. Exit code **130** means the user cancelled the prompt — nothing was stored; that's a valid choice, not an error, so ask whether they'd like to try again rather than treating it as a failure. Any other non-zero exit is a real failure. **Never ask for the key in chat.**

**Note:** Mailgun uses HTTP Basic Auth with username `api` and the API key as the password. The credential proxy cannot construct Basic Auth headers automatically. Instead, use `curl -u "api:$KEY"` in bash commands — retrieve the key from the vault at runtime. See the sending examples below.

### Step 2: Detect the Domain

After storing the API key, **automatically detect the user's domain** — don't ask them for it. Retrieve the API key from the vault and call the Mailgun Domains API:

```bash
curl -s --user "api:$MAILGUN_API_KEY" \
  https://api.mailgun.net/v4/domains?state=active
```

The response contains an `items` array of domain objects with `name` and `state` fields. Pick the first domain with `"state": "active"`. If no active domains are found, try the EU endpoint (`https://api.eu.mailgun.net/v4/domains?state=active`). If still none, tell the user they need to verify a domain in their Mailgun dashboard first.

Use `hi@<domain>` as the default sender address. Remember the domain and region (US/EU) for future sends.

### Step 3: Verify the Connection

Confirm the API key works by checking the domain response returned in Step 2. A successful response (HTTP 200) with domain data confirms the connection.

### Step 4: Webhook Setup (for receiving email)

If the user also wants to **receive** emails via Mailgun, run the webhook setup script:

```bash
bun skills/mailgun-setup/scripts/setup-webhook.ts --domain "<verified domain>" [--region eu]
```

This script:

1. Registers a callback URL via the webhooks system
2. Creates an inbound route in Mailgun via their API
3. Prompts the user for their webhook signing key (found in the Mailgun dashboard: **Settings > API Security > HTTP Webhook Signing Key**)

If the script fails because no public base URL is configured (self-hosted only), load the `public-ingress` skill to walk the user through setting one up, then retry.

### Step 5: Report Success

Summarize with the completed checklist:

"Setup complete!
✅ API key configured
✅ Domain detected: `<domain>` (region: US/EU)
✅ Connection verified
{webhook_line}

Default sender: hi@`<domain>`"

For `{webhook_line}`:

- If webhook was set up: `✅ Inbound route and webhook signing key configured`
- If skipped: `⬜ Webhook — run setup again to enable inbound email`

## Sending Email

Use `bash` with `curl` to call the Mailgun API. Pass the API key via `-u` for Basic Auth:

```bash
curl -s --user "api:$MAILGUN_API_KEY" \
  https://api.mailgun.net/v3/DOMAIN/messages \
  -F from="Name <[email protected]>" \
  -F to="[email protected]" \
  -F subject="Hello" \
  -F text="Plain text body" \
  -F html="<p>HTML body</p>"
```

Replace `DOMAIN` with the user's Mailgun sending domain.

### API Parameters

| Parameter       | Type   | Required | Description                                   |
| --------------- | ------ | -------- | --------------------------------------------- |
| `from`          | string | ✅       | Sender address (`"Name <email>"` format)      |
| `to`            | string | ✅       | Recipient(s), comma-separated for multiple    |
| `subject`       | string | ✅       | Email subject                                 |
| `text`          | string |          | Plain text body                               |
| `html`          | string |          | HTML body                                     |
| `cc`            | string |          | CC recipients, comma-separated                |
| `bcc`           | string |          | BCC recipients, comma-separated               |
| `h:Reply-To`    | string |          | Reply-to address                              |
| `h:In-Reply-To` | string |          | Message-ID of parent (for threading)          |
| `h:References`  | string |          | Space-separated chain of ancestor Message-IDs |

### Threading (replies)

To reply in a thread, include custom headers:

```bash
curl -s --user "api:$MAILGUN_API_KEY" \
  https://api.mailgun.net/v3/DOMAIN/messages \
  -F from="[email protected]" \
  -F to="[email protected]" \
  -F subject="Re: Original subject" \
  -F text="Reply body" \
  -F "h:In-Reply-To=<original-message-id>" \
  -F "h:References=<original-message-id>"
```

### Response

Success returns `{ "id": "<message-id>", "message": "Queued. Thank you." }` with HTTP 200.

Errors return `{ "message": "error description" }` with 4xx/5xx status.

### Regions

Mailgun has US and EU regions:

- **US (default):** `https://api.mailgun.net/v3/DOMAIN/messages`
- **EU:** `https://api.eu.mailgun.net/v3/DOMAIN/messages`

Ask the user which regi

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/vellum-ai/vellum-assistant
git -C vellum-assistant checkout 19bc86343b63

Works in

1. 2026-10-14
   !CAUTION B 89 / 100

   first audit · source 19bc86343b63

Questions about Mailgun Setup

• github.com/vellum-ai/vellum-assistant/tree/main/skills/mailgun-s — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology