Agent Skill · Sinch

sinch-mailgun-validate

Build with Mailgun Validate API for email verification and list hygiene. Use when validating email addresses, checking email deliverability, running bulk validation jobs, previewing list health, or cleaning an email list.

View SKILL.md on GitHub → Source repository Provider profile
Provider: Sinch Path in repo: skills/sinch-mailgun-validate/SKILL.md

Skill body

Mailgun Validate

Overview

Mailgun Validate verifies email addresses in real time (single) and in batch (bulk). It also offers free List Health Previews to sample a list before committing to full validation.

Agent Instructions

Before generating code, gather from the user (skip any item already specified in the prompt or context):

  1. Approach — SDK or direct API calls (curl/fetch/requests)?
  2. Language — for SDK: Node.js, Python, Java, PHP, Ruby, or Go. For direct API: any language, or curl.

When the user chooses SDK, refer to the relevant SDK reference linked in Links.

When the user chooses direct API calls, refer to the API reference linked in Links for request/response schemas.

Security: See the Security section below for url fetching policy, handling inbound bulk results, and credential handling.

Getting Started

Agent Credentials handling

Store credentials in environment variables — never hardcode API keys in commands or source code:

export MAILGUN_API_KEY="your-private-api-key"

Authentication

Ensure that authentication headers are properly set when making API calls. Mailgun Validate uses HTTP Basic Auth — username api, password your Mailgun Private API key:

--user "api:$MAILGUN_API_KEY"

See sinch-authentication for full auth setup.

Language Package Install
Node.js mailgun.js npm install mailgun.js
Java com.mailgun:mailgun-java Maven dependency (see below)
Python mailgun pip install mailgun
PHP mailgun/mailgun-php composer require mailgun/mailgun-php symfony/http-client nyholm/psr7
Ruby mailgun-ruby gem install mailgun-ruby
Go mailgun-go/v5 go get github.com/mailgun/mailgun-go/v5

Java Maven dependency

Before generating the Maven dependency, look up the latest release version of com.mailgun:mailgun-java on Maven Central and use that version.

<dependency>
    <groupId>com.mailgun</groupId>
    <artifactId>mailgun-java</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

Base URLs: api.mailgun.net (US) · api.eu.mailgun.net (EU). Always match the region of your Mailgun account.

Canonical example — validate one address:

curl -X GET \
  "https://api.mailgun.net/v4/address/validate?address=recipient@example.com" \
  -s --user "api:$MAILGUN_API_KEY"

Response:

{
  "address": "recipient@example.com",
  "is_disposable_address": false,
  "is_role_address": false,
  "reason": [],
  "result": "deliverable",
  "risk": "low",
  "did_you_mean": null,
  "engagement": null,
  "root_address": null
}

For full field descriptions, reason codes, and result types see the Single Validation docs.

Key Concepts

Single Address Validation

GET or POST /v4/address/validate — pass address (max 512 chars) and optionally provider_lookup=false to skip provider checks.

Key response fields to branch on:

Rate limited — back off and retry on 429.

List Health Preview

Free, non-destructive sample assessment. Returns deliverability/risk ratios as percentages.

Full reference: List Health Preview

Bulk Validation

Full validation of an uploaded CSV/gzip file (max 25 MB).

Full reference: Bulk Validation

Workflows

Deciding which approach to use

  1. Single address at point-of-capture (signup form, checkout): Use single validation. Check result and risk. Block or warn on do_not_send, high risk, or is_disposable_address.
  2. Existing list, unknown quality: Run a free List Health Preview first. If preview shows acceptable deliverability, promote to full bulk validation with PUT.
  3. Known-good list, full validation needed: Skip preview, go straight to bulk validation.

Bulk validation checklist

Interpreting results

result and risk are independent axes:

Engagement data (contract customers get High Engager, Engager, Bot, Complainer, Disengaged, No data; self-service get boolean engaging/is_bot): Engagement docs

Gotchas

  1. Preview before bulk — Previews are free. Always preview first to avoid wasting credits on a bad list.
  2. Result ≠ risk — Both must be checked. A deliverable + high risk address should still be suppressed.
  3. Catch-all domains — catch_all means the mailbox may not exist. Treat as medium risk.
  4. Disposable/role addresses — Block disposables at signup. Avoid marketing sends to role addresses.
  5. Region consistency — US and EU data do not cross. Match the region of your Mailgun Send account.
  6. did_you_mean — Surface typo suggestions to end users at signup time.

Security

Skill frontmatter

metadata: {"author" => "Sinch", "version" => "1.0.5", "category" => "Email", "tags" => "email, mailgun, validation, verification, list-hygiene, bulk-validation", "uses" => ["sinch-authentication"]}