.png)
Mailgun Integration Guide
Connect Mailgun’s email APIs and event notifications with enterprise applications through authenticated workflows, message orchestration, and delivery-status synchronization.
Mailgun integration options at a glance
Mailgun’s primary integration surface is its REST API for sending messages and managing domains, events, suppressions, routes, templates, and related email resources. Mailgun also supports webhook-style notifications for selected delivery and engagement events, including delivered, failed, opened, clicked, unsubscribed, and complained events. Batch-style sending is available through multiple recipients and recipient variables, while attachments are submitted as multipart message content. API access uses HTTP Basic Authentication with an API key, and webhook signatures can be validated with a signing key. Martini can consume these APIs, receive signed event notifications, transform payloads, apply business rules, and coordinate downstream updates.
| Integration point | Supported by Mailgun? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Send messages and manage Domains, Events, Suppressions, Routes, Templates, mailing lists, and related email resources. | Martini can consume Mailgun REST endpoints, configure regional base URLs, map form-encoded or multipart requests, parse responses, and orchestrate downstream workflows. |
| Webhooks / outbound callbacks | Yes | Notify receiving systems about selected delivered, failed, opened, clicked, unsubscribed, complained, accepted, or stored events, depending on configuration. | Martini can expose an API endpoint or workflow trigger, validate Mailgun signing information, acknowledge the event, and route a normalized payload. |
| Bulk / async / batch APIs | Limited | Submit multiple recipients and recipient variables in a message request for batch-style personalized sending; this is not a general-purpose bulk export API. | Martini can construct recipient-variable payloads, apply volume and validation rules, and manage controlled retries and correlation data. |
| File / attachment APIs | Limited | Submit attachments as multipart content within a message request; attachments are not independent Mailgun file objects. | Martini can map attachment metadata and binary or file content into multipart Messages API requests. |
| Authentication | Yes | Authenticate API calls with HTTP Basic Authentication using api as the username and a Mailgun API key as the password; webhook signatures use a signing key. | Martini can store API and signing keys in secure environment configuration and apply authentication and signature-validation logic in workflows. |
| Database / analytics access | No | Mailgun does not expose direct customer database access; event and reporting data should be retrieved through APIs. | Martini can consume the Events API and persist normalized data in an approved database or downstream application instead of using database-level access. |
| Scheduled synchronization | Yes | Retrieve paginated Events or suppression data on a schedule and maintain a high-water mark for incremental processing. | Martini can schedule workflows, follow pagination, store checkpoints, compare states, and route changes to downstream systems. |
How Mailgun exposes data and business events
Mailgun REST APIs
Mailgun’s REST APIs provide the primary integration surface for sending Messages and managing Domains, Events, Suppressions, Routes, Templates, and related resources. Requests generally use HTTP Basic Authentication with an API key and may use form-encoded or multipart bodies.
Martini implementation pattern
Martini implementation pattern: a workflow or exposed Martini API validates the source payload, selects the Mailgun region and domain, constructs the appropriate request, calls the REST endpoint, parses the response, and stores Mailgun identifiers with business correlation data.
Implementation sequence
Mailgun webhooks
Mailgun supports webhook-style notifications for selected email lifecycle and engagement events, including delivery, failure, open, click, unsubscribe, and complaint events. Coverage depends on event configuration and is not a universal callback for every API operation.
Martini implementation pattern
Martini implementation pattern: expose a receiving API or workflow trigger, validate the Mailgun signature and timestamp, acknowledge accepted events promptly, preserve the original payload, and process downstream updates asynchronously when multiple systems are involved.
Implementation sequence
Mailgun Events API
The Events API provides an API-based way to retrieve delivery and engagement information for scheduled or recovery synchronization. Event and resource-list responses may be paginated.
Martini implementation pattern
Martini implementation pattern: schedule a workflow that retrieves events from the last stored checkpoint, follows Mailgun pagination links or documented paging parameters, maps events to a canonical status model, and advances the checkpoint only after successful processing.
Implementation sequence
Mailgun message attachments
Mailgun accepts attachments as multipart content within a Messages API submission. It does not expose attachments as a separate general-purpose file object API.
Martini implementation pattern
Martini implementation pattern: obtain approved file content, validate size and metadata according to the sending design, map the content into a multipart request, and handle uncertain submission outcomes without blindly duplicating delivery.
Implementation sequence
Common Mailgun integration patterns
Pattern 1: Orchestrate transactional email
When to use this pattern
Use this pattern when an order confirmation, password reset, invoice notification, or service alert must be submitted through Mailgun with consistent validation, templates, correlation, and response handling.
Integration direction
Example Mapping
| Mailgun Field | Canonical Field | Target Field |
|---|---|---|
| recipient | notification.recipient | to |
| template | notification.templateKey | template |
| template variables | notification.parameters | t:variables |
| business correlation ID | notification.correlationId | custom header or metadata |
Martini implementation pattern
Martini receives the business request through an API or workflow trigger, validates required fields, selects the authorized sending domain and template, maps variables, applies suppression and deduplication rules, submits the Messages API request, and persists the response. Known transient failures can be retried with backoff, while ambiguous timeouts require correlation-aware handling before resubmission.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- secure environment configuration
- error handling
Pattern 2: Synchronize Mailgun delivery events
When to use this pattern
Use this pattern when operational applications need delivery, failure, open, click, unsubscribe, or complaint status associated with a customer, order, case, or notification.
Integration direction
Example Mapping
| Mailgun Field | Canonical Field | Target Field |
|---|---|---|
| event | email.lifecycleEvent | delivery status |
| message.id | email.providerMessageId | Mailgun message ID |
| recipient | contact.email | Contact email |
| timestamp | email.eventAt | event timestamp |
Martini implementation pattern
Martini receives signed Mailgun webhooks or retrieves events incrementally, normalizes event-specific optional fields, matches the message identifier or correlation metadata to a business object, and updates downstream systems idempotently. Permanent failures and complaints can be routed to remediation workflows, while the original payload is retained for audit and troubleshooting.
Martini capabilities used
- API endpoints
- workflow triggers
- webhook consumption
- data mapping
- conditional routing
- error handling
Pattern 3: Synchronize suppressions
When to use this pattern
Use this pattern when Mailgun bounce, unsubscribe, and complaint state must be reconciled with customer preferences or contact data maintained in another system.
Integration direction
Example Mapping
| Mailgun Field | Canonical Field | Target Field |
|---|---|---|
| address | contact.email | Contact email |
| suppression type | contact.emailStatus | subscription or suppression status |
| createdAt | preference.updatedAt | last changed timestamp |
| source | preference.source | source |
Martini implementation pattern
A scheduled Martini workflow retrieves paginated suppression data, compares it with the target preference model, applies ownership and consent rules, and writes only approved changes. The workflow stores a checkpoint or comparison state, prevents future sends for suppressed addresses, and avoids automatically reactivating an address without an approved process.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination handling
- data mapping
- business rules
- idempotent processing
Pattern 4: Expose a centralized notification API
When to use this pattern
Use this pattern when multiple applications should submit standardized notification requests without embedding Mailgun-specific authentication, templates, domains, multipart handling, or retry logic.
Integration direction
Example Mapping
| Mailgun Field | Canonical Field | Target Field |
|---|---|---|
| notification type | notification.type | template |
| customer email | recipient.email | to |
| order details | notification.data | template variables |
| request ID | notification.requestId | correlation metadata |
Martini implementation pattern
Martini exposes a controlled API that validates and canonicalizes requests from applications such as Shopify, applies sender and template selection rules, calls Mailgun, and returns a normalized submission status. Reusable workflow logic handles secrets, deduplication, response persistence, and event reconciliation without requiring each caller to understand Mailgun’s request format.
Martini capabilities used
- API exposure
- workflows
- data mapping
- validation
- business rules
- reusable integration assets
- error handling
Applications commonly integrated with Mailgun
Mailgun can be integrated with business applications that need transactional email delivery, notification orchestration, or delivery-status feedback. The following are practical enterprise architecture patterns; the specific Mailgun relationship is not implied to be a native product integration.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Send customer notifications and synchronize delivery, bounce, complaint, and unsubscribe events with Leads, Contacts, and Cases. | Salesforce → Martini → Mailgun | Martini receives a Salesforce business event or scheduled request, validates recipients and message data, selects the Mailgun domain or template, submits the message, and routes signed Mailgun events back to Salesforce using message and correlation identifiers. |
| ServiceNow | Send incident, request, and approval notifications while recording delivery failures or engagement events against Tickets and Users. | ServiceNow → Martini → Mailgun | A Martini workflow consumes ServiceNow events or API data, maps notification fields to a Mailgun message request, persists the submission identifier, and updates ServiceNow when Mailgun reports delivery or failure events. |
| Shopify | Send order, fulfillment, account, and customer notification emails using Shopify order and customer data. | Shopify → Martini → Mailgun | Martini receives Shopify order or customer changes through the available Shopify integration mechanisms, maps the event to a Mailgun template and recipient-variable payload, and applies deduplication before sending. |
| NetSuite | Send transaction and operational notifications for Sales Orders, Invoices, Customers, and fulfillment workflows. | NetSuite → Martini → Mailgun | Martini orchestrates NetSuite-triggered or scheduled notification workflows, transforms transaction data into Mailgun template variables, submits multipart messages when needed, and records Mailgun responses for audit. |
| Jira | Send issue, project, and workflow notifications and optionally record delivery outcomes for operational reporting. | Jira → Martini → Mailgun | Martini receives Jira event data, validates the notification policy, calls the Mailgun Messages API, and normalizes delivery or complaint events for Jira-related reporting or downstream storage. |
| Workday | Deliver employee or business-process notifications and synchronize notification outcomes with HR workflows. | Workday → Martini → Mailgun | A Martini workflow consumes approved Workday notification data, applies sender-domain and recipient rules, maps the payload to Mailgun, and returns status information to the originating HR process. |
| Zendesk | Send ticket and customer communication notifications and process Mailgun delivery or complaint events. | Zendesk → Martini → Mailgun | Martini maps Zendesk ticket or customer context to a Mailgun message, stores correlation metadata, and uses Mailgun webhook events to update support records or route failed communications. |
| HubSpot | Coordinate transactional email delivery with Contacts and customer lifecycle data while keeping suppression status aligned. | HubSpot → Martini → Mailgun | Martini separates transactional sending from marketing responsibilities, synchronizes approved suppression changes, submits Mailgun messages, and maps delivery events to HubSpot contact activity where appropriate. |
How to build a Mailgun integration in Martini
Objective
Configure Mailgun’s regional API endpoint, authorized sending domain, API key, and webhook signing key without embedding secrets in workflow logic.
Instructions in Martini
- Use HTTP Basic Authentication with api as the username and the Mailgun API key as the password
- Store API and signing keys in secure environment configuration
- Keep the US or EU region and sending domain configurable
- Use the least-privileged key appropriate to the operation
Objective
Select an API request, source application event, Mailgun webhook, or scheduled workflow trigger based on the synchronization requirement.
Instructions in Martini
- Use an exposed Martini API for centralized notification requests
- Use a webhook workflow for selected Mailgun lifecycle events
- Use a scheduler for Events or Suppressions synchronization
- Separate webhook acknowledgement from downstream processing when appropriate
Objective
Obtain Mailgun messages, events, suppressions, domains, templates, or routes through the confirmed REST mechanisms.
Instructions in Martini
- Call the relevant Mailgun REST endpoint
- Follow pagination links or documented paging parameters
- Preserve the original webhook payload for audit
- Store a high-water mark for scheduled retrieval
Objective
Coordinate validation, Mailgun calls, downstream updates, persistence, and alternate paths in a maintainable Martini workflow.
Instructions in Martini
- Validate required sender, recipient, domain, and content fields
- Apply suppression, consent, and notification policy rules
- Route delivery failures and complaints to remediation paths
- Persist provider identifiers and business correlation data
Objective
Convert application-specific notification and event data into Mailgun request structures or canonical downstream status models.
Instructions in Martini
- Map templates and recipient variables explicitly
- Construct form-encoded or multipart message requests
- Normalize event types and optional fields
- Handle HTML, text, headers, and attachments as separate mapping concerns
Objective
Submit or persist the result while making retries, duplicates, uncertain submissions, and operational monitoring explicit.
Instructions in Martini
- Retry known transient failures with controlled backoff
- Do not blindly retry a message after an ambiguous timeout
- Make webhook and downstream updates idempotent
- Monitor workflow logs and retain correlation identifiers
Common Mailgun data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Domains | Represent configured sending domains, DNS verification, tracking settings, and domain-level credentials. | Salesforce, ServiceNow, configuration databases, operational dashboards | Martini retrieves or manages domain data through authenticated REST calls and keeps region, environment, and domain configuration externalized. |
| Messages | Represent outbound email submissions containing recipients, headers, body content, templates, variables, and attachments. | Salesforce, Shopify, NetSuite, Jira, Workday, Zendesk, HubSpot | Martini validates and maps business data into form-encoded or multipart Messages API requests, then stores Mailgun and business correlation identifiers. |
| Events | Represent accepted, delivered, temporary failure, permanent failure, opened, clicked, unsubscribed, and complained email lifecycle events. | Salesforce, ServiceNow, databases, operational reporting systems | Martini receives signed webhooks or retrieves events incrementally, normalizes optional fields, deduplicates events, and routes status updates. |
| Suppressions | Represent addresses associated with bounces, unsubscribes, and complaints that should not receive certain messages. | Salesforce, HubSpot, customer data platforms, preference stores | Martini synchronizes suppression state, applies send-prevention rules, records source and timestamps, and avoids unapproved reactivation. |
| Routes | Represent rules for processing incoming messages and forwarding, storing, or otherwise handling them. | Mail processing services, databases, internal APIs | Martini can call route-management endpoints and apply environment-specific configuration and validation rules. |
| Templates | Represent reusable email content referenced during message submission. | Salesforce, Shopify, NetSuite, internal notification services | Martini selects environment-specific templates, maps required variables explicitly, and submits the template reference with the message request. |
Authentication and security considerations
Authentication and security
Mailgun API calls use HTTP Basic Authentication with api as the username and a Mailgun API key as the password. Mailgun supports account-level private keys, domain sending keys, and signing keys, subject to account configuration.
- Store API keys and webhook signing keys in Martini secure environment configuration.
- Use the least-privileged key appropriate to sending or administration.
- Keep the US or EU API region and authorized sending domain configurable.
- Verify webhook signatures and timestamps before processing event data.
- Protect recipient, message, and suppression data throughout workflow processing.
Operational considerations for Mailgun integrations
Operational considerations
Mailgun limits can vary by endpoint, account, plan, and traffic profile. Workflows should handle HTTP 429 responses with controlled backoff and should not blindly retry a message after an ambiguous timeout.
- Follow pagination links or documented paging parameters for Events and resource lists.
- Use high-water marks or event identifiers for incremental synchronization.
- Make message submission and webhook processing idempotent.
- Validate required sender, recipient, template, and domain fields before calling Mailgun.
- Treat event fields as potentially optional and isolate Mailgun-specific mappings from canonical models.
- Retain original webhook payloads, provider identifiers, and correlation data for audit and troubleshooting.
- Test US and EU region configuration, authorized domains, templates, suppression rules, multipart attachments, and failure paths before production deployment.
Why use Martini instead of scripts or point-to-point integrations?
Coordinate integration logic centrally
Scripts and point-to-point integrations often duplicate Mailgun authentication, template mapping, retry behavior, event normalization, and suppression rules across applications. Martini provides a maintainable workflow and API layer for coordinating these concerns.
- Expose a consistent notification API to business applications.
- Consume Mailgun REST APIs and signed webhook events through reusable workflows.
- Map and transform application data without coupling every caller to Mailgun request formats.
- Apply centralized validation, suppression, deduplication, routing, and retry rules.
- Persist correlation identifiers and operational results for monitoring and audit.
- Extend workflows with custom logic when provider-specific behavior requires more flexibility.
Frequently asked questions
Mailgun can be integrated through its REST APIs for Messages, Domains, Events, Suppressions, Routes, Templates, and related resources. It also supports selected webhook notifications for email lifecycle and engagement events, while message attachments are submitted as multipart content. Authentication uses HTTP Basic Authentication with an API key, and webhook signatures can be validated with a signing key.
Yes. Martini can consume Mailgun REST APIs, submit authenticated message and management requests, receive selected Mailgun webhook events through an exposed API or workflow trigger, validate signatures, transform payloads, and synchronize results with downstream applications.
No. A dedicated Mailgun connector is not required. Martini can integrate using Mailgun’s native REST APIs, webhook notifications, multipart message requests, API-key authentication, and webhook signing mechanisms.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Mailgun. Integrations are subject to the provisioned capacity of the Martini environment. Separate costs may apply from Mailgun, infrastructure providers, or other third-party systems depending on subscription, usage, and deployment model.
Use the REST APIs as the primary method for sending messages and managing Mailgun resources. Use webhooks for selected lifecycle and engagement events, the Events API for incremental retrieval or recovery synchronization, and multipart Messages API requests when attachments are required. Mailgun does not provide a confirmed GraphQL or SOAP integration surface.
Yes, Mailgun supports webhook-style notifications for selected events such as delivered, temporary or permanent failure, opened, clicked, unsubscribed, and complained. They are event-specific rather than universal callbacks for every Mailgun operation. Martini can verify signatures, acknowledge notifications, deduplicate them, and route normalized events.
Real-time or near-real-time synchronization can use Mailgun webhooks, while scheduled synchronization can use the Events API or relevant resource endpoints. Martini can follow pagination, maintain a timestamp or event checkpoint, map provider objects to canonical models, and make downstream updates idempotently.
Martini can classify HTTP and workflow failures, apply controlled backoff for safe transient retries, and route permanent failures for remediation. Message submissions require special care because a timeout may occur after Mailgun accepts a message; application-level deduplication and stored correlation data help reduce duplicate delivery. Webhook processing should also be idempotent.
Related Martini documentation
API Workflows
Mapping Security
Connect Mailgun with Martini
Use Martini to orchestrate Mailgun email delivery, event processing, suppression synchronization, and enterprise application workflows through secure APIs and reusable integration logic.