Agent Skill · Sinch

sinch-mailgun-optimize

Monitors email deliverability via Mailgun Optimize (InboxReady) API. Use when the user wants to test inbox placement with seed lists, monitor IP or domain blocklists, track spam traps, check email health scores, review DMARC reports, or pull Google Postmaster or Microsoft SNDS data. Also use when emails are going to spam, sender reputation is dropping, inbox rate is declining, a domain needs warmup monitoring, an IP needs blocklist removal, or the user wants to set up email deliverability monitoring.

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

Skill body

Mailgun Optimize (InboxReady)

Overview

Mailgun Optimize (by Sinch), formerly InboxReady, is a deliverability suite: inbox placement testing via seed lists, IP and domain blocklist monitoring, spam trap tracking, email health scoring, DMARC reporting, Google Postmaster Tools integration, and Microsoft SNDS data.

Agent Instructions

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

  1. Region — US or EU? Region determines the base URL.
  2. Language — any language, or curl. This API is REST-only; there is no SDK wrapper.
  3. Before generating code, check for existing .env files or environment variables for MAILGUN_API_KEY.

Product gotchas to apply unconditionally:

Refer to the API Reference or OpenAPI Spec linked in Links for request/response schemas.

Security: See the Security section below for url fetching policy 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 Optimize uses HTTP Basic Auth — username api, password your Mailgun Private API key:

--user "api:$MAILGUN_API_KEY"

See sinch-authentication for full auth setup.

Base URLs

Region Base URL
US https://api.mailgun.net/
EU https://api.eu.mailgun.net/

First API Call

curl -X GET \
  "https://api.mailgun.net/v1/inboxready/domains" \
  --user "api:$MAILGUN_API_KEY"

Key Concepts

Common Workflows

Inbox Placement Test

  1. Create a seed list — POST /v4/inbox/seedlists
  2. Create a test — POST /v4/inbox/tests with html body content or template_name
  3. The response includes a result_id
  4. Poll for results — GET /v4/inbox/results/{result_id}

Deliverability Audit

When a user reports deliverability issues, investigate in this order:

  1. Check IP blocklists — GET /v1/inboxready/ip_addresses/{ip}
    • If blocklisted → prioritize delisting with the blocklist provider before other steps
  2. Check domain blocklists — GET /v1/monitoring/domains/{domain}/blocklists
    • If blocklisted → submit delisting request; investigate compromised sending or poor list hygiene
  3. Review spam trap hits — GET /v2/spamtraps
    • Pristine traps → purchased/scraped list; stop sending to that segment
    • Recycled traps → list hygiene issue; run email validation, remove inactive addresses
  4. Pull health score — GET /v1/maverick-score/total
    • Low score → correlate with findings above to identify root cause
  5. Check Google Postmaster reputation — GET /v1/reputationanalytics/gpt/domains/{domain}
    • Spam rate > 0.3% → review content and list acquisition practices
  6. Review DMARC compliance — GET /v1/dmarc/domains/{domain}

New Domain Onboarding

Set up full deliverability monitoring for a new sending domain:

  1. Register the domain — POST /v1/inboxready/domains?domain=example.com
  2. Verify the domain — PUT /v1/inboxready/domains/verify?domain=example.com
  3. Register sending IPs — POST /v1/inboxready/ip_addresses with the IP address
  4. Configure alerts — POST /v1/alerts/settings/events for blocklist and reputation changes
  5. Set up DMARC — get DNS records via GET /v1/dmarc/records/{domain}, configure DNS, then verify data in GET /v1/dmarc/domains/{domain}
  6. Link Google Postmaster — verify domain with Google, then confirm data in GET /v1/reputationanalytics/gpt/domains/{domain}

Set Up Monitoring Alerts

Create alert settings via POST /v1/alerts/settings/events. Update with PUT or remove with DELETE on /v1/alerts/settings/events/{id}.

Gotchas and Best Practices

  1. Google Postmaster requires Google verification — The domain must be verified with Google before Mailgun can pull Postmaster data. See Google Postmaster reference.
  2. Spam trap mitigation — Never try to identify specific trap addresses. Clean the entire list with email validation and implement double opt-in.
  3. Blocklist delisting — When blocklisted, check the specific blocklist provider’s website for their delisting process. Mailgun monitors but does not auto-delist.
  4. DMARC DNS prerequisite — DMARC report data requires a DMARC DNS record on the domain. See DMARC reference for setup flow.

Security

Skill frontmatter

metadata: {"author" => "Sinch", "version" => "1.0.4", "category" => "Email", "tags" => "email, mailgun, deliverability, inbox-placement, blocklist, dmarc, spam-traps", "uses" => ["sinch-authentication"]}