Required dependencies

npm install axios base-64 url-join
npm install --save-dev typescript @types/node

No native build steps, pod installs, or Android linking are required. This is a pure Node.js/browser library.

Project setup

1. Copy the source/ directory into your project, for example at src/mailgun/.

2. Ensure your tsconfig.json targets ES2020 or later and has module resolution set to node16 or bundler:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "Node16",
    "moduleResolution": "node16",
    "esModuleInterop": true,
    "strict": true,
    "paths": {
      "mailgun-sdk/*": ["./src/mailgun/*"]
    }
  }
}

3. Set the following environment variables (.env or your secrets manager):

MAILGUN_API_KEY=your-private-api-key
MAILGUN_DOMAIN=mg.yourdomain.com
# Optional: for EU infrastructure
MAILGUN_API_URL=https://api.eu.mailgun.net

4. Import and instantiate the client (see examples below). The FormData constructor argument accepts the built-in global FormData (Node 18+) or the form-data npm package.

5. All .js extension imports inside the source files are intentional for ESM compatibility. If you use CommonJS ("module": "CommonJS"), you may need a bundler step or adjust the import paths.

Public API

Mailgun (default export from source/index.ts)

import Mailgun from './src/mailgun/index.js';

class Mailgun {
  constructor(FormData: InputFormData);
  client(options: MailgunClientOptions): IMailgunClient;
  static get default(): typeof Mailgun;
}

The root factory class. Instantiate once per process with a FormData implementation, then call .client() with your API credentials. The static get default accessor enables import('mailgun.js').then(m => new m.default(FormData)) dynamic import patterns.

MailgunClientOptions (from source/Types/index.ts)

interface MailgunClientOptions {
  username: string;   // always 'api'
  key: string;        // your Mailgun private API key
  url?: string;       // defaults to https://api.mailgun.net; use EU URL if needed
  timeout?: number;
  proxy?: { protocol: string; host: string; port: number };
}

Passed to mailgun.client(options). Use url: 'https://api.eu.mailgun.net' for EU-region sending domains. Proxy config is useful for browser environments routing through a backend proxy.

IMailgunClient (from source/Interfaces/MailgunClient/index.ts)

interface IMailgunClient {
  messages:    /* MessagesClient */;
  domains:     /* DomainsClient */;
  events:      /* EventsClient */;
  suppressions:/* SuppressionsClient */;
  webhooks:    /* WebhooksClient */;
  lists:       /* MailingListsClient */;
  validate:    /* ValidateClient */;
  stats:       /* StatsClient */;
  metrics:     /* MetricsClient */;
  logs:        /* LogsClient */;
  // ...additional sub-clients
}

The unified client returned by mailgun.client(). Each property is a namespaced sub-client. Call methods directly: mg.messages.create(domain, data), mg.suppressions.list(domain, model), etc.

Enums (from source/Enums/index.ts)

import { Resolution, SuppressionModels, WebhooksIds, YesNo } from './src/mailgun/Enums/index.js';

Resolution.HOUR   // 'hour'
Resolution.DAY    // 'day'
Resolution.MONTH  // 'month'

SuppressionModels.BOUNCES      // 'bounces'
SuppressionModels.COMPLAINTS   // 'complaints'
SuppressionModels.UNSUBSCRIBES // 'unsubscribes'
SuppressionModels.WHITELISTS   // 'whitelists'

WebhooksIds.CLICKED        // 'clicked'
WebhooksIds.PERMANENT_FAIL // 'permanent_fail'

Use these enums instead of raw strings to avoid typos in API calls and to get IDE autocomplete.

Working examples

Scenario - Send a transactional email

Basic message delivery to a single recipient using the messages sub-client.

import Mailgun from './src/mailgun/index.js';

const mailgun = new Mailgun(FormData);
const mg = mailgun.client({
  username: 'api',
  key: process.env.MAILGUN_API_KEY!,
  url: process.env.MAILGUN_API_URL, // omit for US
});

async function sendEmail() {
  const domain = process.env.MAILGUN_DOMAIN!;
  const result = await mg.messages.create(domain, {
    from: `Sender <mailgun@${domain}>`,
    to: ['recipient@example.com'],
    subject: 'Hello from Mailgun SDK',
    text: 'This is a test message.',
    html: '<p>This is a <b>test</b> message.</p>',
  });
  console.log('Message queued:', result.id);
}

sendEmail().catch(console.error);

Scenario - List and delete bounced addresses

Retrieve the bounce suppression list and remove a specific address.

import Mailgun from './src/mailgun/index.js';
import { SuppressionModels } from './src/mailgun/Enums/index.js';

const mg = new Mailgun(FormData).client({
  username: 'api',
  key: process.env.MAILGUN_API_KEY!,
});

async function manageBounces() {
  const domain = process.env.MAILGUN_DOMAIN!;

  // List bounces
  const bounces = await mg.suppressions.list(domain, SuppressionModels.BOUNCES);
  console.log('Bounced addresses:', bounces.items);

  // Delete a specific bounce
  const address = 'bad@example.com';
  await mg.suppressions.destroy(domain, SuppressionModels.BOUNCES, address);
  console.log(`Removed ${address} from bounce list`);
}

manageBounces().catch(console.error);

Scenario - Query events with pagination

Poll the events API for delivered messages within a time window.

import Mailgun from './src/mailgun/index.js';
import { Resolution } from './src/mailgun/Enums/index.js';

const mg = new Mailgun(FormData).client({
  username: 'api',
  key: process.env.MAILGUN_API_KEY!,
});

async function fetchDeliveredEvents() {
  const domain = process.env.MAILGUN_DOMAIN!;

  const page = await mg.events.get(domain, {
    event: 'delivered',
    limit: 25,
  });

  for (const event of page.items) {
    console.log(event.timestamp, event.recipient);
  }

  // Navigate to the next page if available
  if (page.pages?.next?.url) {
    const next = await mg.events.get(domain, { page: 'next' });
    console.log('Next page count:', next.items.length);
  }
}

fetchDeliveredEvents().catch(console.error);

File walkthrough

• source/index.ts - Exports the Mailgun class; the only entry point buyers need to import.
• source/definitions.ts - Internal constant definitions and shared primitives referenced throughout the codebase.
• source/Enums/index.ts - Barrel that exports all SDK enums (Resolution, SuppressionModels, WebhooksIds, YesNo).
• source/Interfaces/ - Barrel re-exports of all TypeScript interfaces organized by domain (Common, Domains, Messages, Events, Suppressions, etc.).
• source/Types/ - Type aliases such as InputFormData and MailgunClientOptions consumed by the public API.
• source/Classes/MailgunClient.ts - Instantiates and wires together all sub-clients; returned by mailgun.client().
• source/Classes/Messages.ts - Implements messages.create() for sending email.
• source/Classes/Events.ts - Implements events.get() for event log queries.
• source/Classes/Webhooks.ts - CRUD for Mailgun webhook registrations.
• source/Classes/Routes.ts - Manages inbound routing rules.
• source/Classes/IPs.ts - Dedicated IP management.
• source/Classes/IPPools.ts - IP pool grouping and assignment.
• source/Classes/Subaccounts.ts - Subaccount creation and management.
• source/Classes/Domains/ - Full domain lifecycle: creation, credentials, SMTP keys, tracking settings, templates, and tags.
• source/Classes/Suppressions/ - Per-model suppression handlers for bounces, complaints, unsubscribes, and whitelists.
• source/Classes/MailingLists/ - Mailing list and member CRUD.
• source/Classes/Stats/ - Statistics retrieval (StatsClient) and result container (StatsContainer).
• source/Classes/Tags/ - Tag listing, updating, and deletion.
• source/Classes/Validations/ - Single address validation (validate) and bulk validation (multipleValidation).
• source/Classes/InboxPlacements/ - Inbox placement tests, seed list management, provider filters, results, and sharing.
• source/Classes/Metrics/ - Account/domain metrics queries.
• source/Classes/Logs/ - Log record retrieval.
• source/Classes/DKIM/ - DKIM key rotation and management.
• source/Classes/BounceClassification/ - Bounce classification code lookup.
• source/Classes/common/Request.ts - Core HTTP request wrapper using Axios.
• source/Classes/common/FormDataBuilder.ts - Builds multipart FormData for attachments and API payloads.
• source/Classes/common/NavigationThruPages.ts - Pagination helper used by list endpoints.
• source/Classes/common/AttachmentsHandler.ts - Normalizes attachment inputs before upload.
• source/Classes/common/Error.ts - Custom SDK error class with status code and body.
• source/Classes/common/RequestProviders/AxiosProvider.ts - Axios adapter wiring timeouts, proxies, and auth.

Common pitfalls and fixes

• EU domain rejected with 404: Always pass url: 'https://api.eu.mailgun.net' to mailgun.client() when your sending domain is registered in the EU region.
• FormData is not defined in Node.js < 18: Either upgrade to Node 18+ (which provides global FormData) or install form-data and pass it: new Mailgun(require('form-data')).
• ESM .js extension import errors in CommonJS projects: The source uses explicit .js extensions for ESM compatibility. In a CJS project, run the source through a bundler (esbuild, webpack) or switch your project to "type": "module".
• TypeScript path alias resolution failing: Ensure moduleResolution is node16 or bundler; node (classic) does not resolve .js-extensioned ESM imports correctly.
• Axios peer version conflict: The source depends on axios directly. If your project pins a different major version, dedupe with npm dedupe or align versions to avoid duplicate Axios bundles.
• Attachment uploads silently empty: Always pass Buffer or Readable stream objects as attachment data, not plain file paths; the AttachmentsHandler does not resolve filesystem paths automatically.

Vibe-coding prompt template

I have the Mailgun.js SDK source (mailgun.js v13) copied into `src/mailgun/`
in my Node.js TypeScript project. The integration guide is in `USAGE.md`.
The upstream package is `mailgun.js` on npm.

Please help me integrate this SDK step by step:

1. Read `USAGE.md` and `src/mailgun/index.ts` to understand the public API.
2. Install the required runtime dependencies: axios, base-64, url-join.
3. Create a `src/services/email.ts` module that:
   - Instantiates `Mailgun` from `src/mailgun/index.ts` using the global FormData.
   - Reads MAILGUN_API_KEY, MAILGUN_DOMAIN, and optionally MAILGUN_API_URL from env.
   - Exports a `sendEmail(to, subject, html)` async function.
   - Exports a `listBounces()` async function using `SuppressionModels.BOUNCES`.
4. Wire the service into my existing Express route at `src/routes/email.ts`.
5. Show tsconfig changes needed for the .js extension imports.
6. Do not invent any methods not present in `src/mailgun/` or documented in `USAGE.md`.

License and credit

The upstream project is licensed under the MIT License (see source/LICENSE if present, or the mailgun.js repository). This block is derived from user@example.com published by Mailgun Technologies, Inc.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

Puppeteer Browser Automation and Testing Library

Automation, Utilities & Developer Tools

無料