Skip to main content
Mailgun is an email delivery service for sending, receiving and tracking transactional and bulk email through an API or SMTP. This connector reads your sending domains and their settings, the event log of your messages (accepted, delivered, failed, opened, clicked, unsubscribed, complained), daily sending metrics per domain and per tag, the suppression lists (bounces, unsubscribes, complaints and allowlist), mailing lists and their members, stored templates and their versions, tags, inbound routes, IP addresses and pools, subaccounts, users and webhooks.
The connector only reads data. It never sends messages and never changes domains, lists, templates or suppressions.

Configuring Mailgun as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Mailgun option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

In Mailgun, open Account settings and then API security. Create or copy a Private API key. If your account uses roles for API keys, a key with the Analyst (read-only) role reads most tables; the Users table may need a higher role. A Domain Sending key cannot read data. The following configurations are available:
  • Private API Key: Your Mailgun Private API key.
  • Region: The region your Mailgun account and domains were created in: US or EU. You can see it in the Mailgun dashboard; EU accounts use api.eu.mailgun.net.
  • Start Date: Events and daily metrics are read from this date on. Mailgun keeps event logs for 30 days at most (less on some plans) and daily metrics for one year, so an older date only brings what Mailgun still keeps. The other tables are read in full on every sync.
  • Domains (advanced): The sending domains to sync, separated by commas, exactly as listed in Mailgun (for example mg.example.com). Leave it empty to sync every domain of your account. The events and metrics are filtered to these domains too.
If the API key is not allowed to read a table, or the table depends on a feature your plan does not include (subaccounts, account-level templates, dedicated IPs, account webhooks), that table is skipped and the sync log names it. The other tables keep syncing. Deselect the table to stop the warning.
Once you’re done, click Next.

2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
    • Incremental: every time the extraction happens, we’ll get only the new data, which is good if, for example, you want to keep every record ever fetched.
    • Full table: every time the extraction happens, we’ll get the current state of the data, which is good if, for example, you don’t want to have deleted data in your catalog.
Keep Events, Daily Metrics and Daily Tag Metrics as INCREMENTAL. Mailgun keeps only the last 30 days of events and one year of daily metrics, so a full table sync (or an Additional Full Sync) replaces these tables with what Mailgun still keeps and the older rows are lost.
Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Because Mailgun keeps events for a limited time, sync at least once a week (daily is recommended) so no event expires before it is read. Optionally, you can define some additional settings:
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Determine when to execute an Additional Full Sync. Do not use it for Events, Daily Metrics or Daily Tag Metrics (see the warning above).
Once you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

Good to know

  • Dates are in UTC.
  • The first load of Events can be long. On accounts that send a lot, the first sync reads up to 30 days of events and is only saved when it completes; the sync log tells you when it may take an hour or more. A later Start Date makes it shorter. Later syncs save their progress day by day.
  • Shorter event retention. If your plan keeps event logs for fewer than 30 days, the first sync of Events starts from the period Mailgun still keeps and the log says which older events are no longer available. Later syncs run normally.
  • Recent events arrive with the next sync. Mailgun records events out of order and considers the last half hour not final, so each sync reads events up to 30 minutes before it started, and starts one hour before the last event read to catch late ones.
  • Today’s metrics are partial. Daily metrics of the current day are updated by the next syncs, which read the last three days again.
  • Only your main account is read. Data of subaccounts (their domains, events and metrics) is not included; the Subaccounts table lists them.
  • Nested values are JSON text. Columns such as delivery_status, message, client_info or vars hold the original JSON.
  • The SMTP password and API keys are never loaded.

Streams and Fields

Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description.

Fields by stream

Primary key: name · Sync: Full table
  • name - Fully qualified domain name registered with Mailgun
  • id - Unique identifier of the domain
  • state - Verification state of the domain (active, unverified or disabled)
  • type - Classification of the domain: custom or sandbox
  • created_at - Date and time the domain was created (UTC)
  • is_disabled - Whether the domain is currently disabled
  • disabled - Why and until when the domain is disabled (JSON object with code, note, permanently, reason, until), when it is
  • require_tls - Whether Mailgun only sends messages of this domain over a TLS connection
  • skip_verification - Whether Mailgun skips certificate and hostname verification on TLS connections
  • smtp_login - SMTP login of the domain, when one was set (the password is never loaded)
  • spam_action - Action taken when a message is flagged as spam: disabled, tag or block
  • subaccount_id - ID of the subaccount the domain belongs to, when it belongs to one
  • tracking_host - Custom tracking host used for open and click tracking, when configured
  • use_automatic_sender_security - Whether Mailgun manages DKIM keys and DNS records automatically
  • webhooks_redact_pii - Whether personal data is redacted from the webhooks posted for this domain
  • web_prefix - Subdomain prefix used for open and click tracking
  • web_scheme - Protocol scheme used for tracking (http or https)
  • wildcard - Whether the domain can receive email for any subdomain
  • encrypt_incoming_message - Whether incoming messages to this domain are encrypted
  • message_ttl - Time-to-live in seconds for retrieving incoming and outgoing messages
  • archive_to - URL a copy of each delivered message is posted to, when configured
Primary key: domain · Sync: Full table
  • domain - Name of the Mailgun sending domain the record belongs to
  • open_active - Whether open tracking is enabled
  • open_place_at_the_top - Whether the open tracking pixel is placed at the top of the email
  • click_active - Whether click tracking is enabled
  • unsubscribe_active - Whether unsubscribe tracking is enabled
  • unsubscribe_html_footer - HTML footer added for the unsubscribe link
  • unsubscribe_text_footer - Text footer added for the unsubscribe link
  • web_scheme - Web scheme used by the tracking links (http or https)
Primary key: domain, event_type · Sync: Full table
  • domain - Name of the Mailgun sending domain the record belongs to
  • event_type - Event that triggers the webhook (accepted, delivered, opened, clicked, unsubscribed, complained, temporary_fail, permanent_fail)
  • urls - URLs Mailgun posts the event to
Primary key: id, timestamp · Sync: Incremental (by timestamp)
  • id - Unique identifier of the event
  • timestamp - Date and time the event happened (UTC), used as the incremental replication key
  • event - Event type: accepted, delivered, failed, rejected, opened, clicked, unsubscribed, complained, stored, email_validation…
  • log_level - Severity class of the event: info, warn or error
  • severity - For failed events: temporary (will be retried) or permanent
  • reason - Reason Mailgun gives for a failure or rejection
  • method - How the message was submitted (HTTP or SMTP)
  • domain - Sending domain of the message
  • recipient - Email address of the recipient the event refers to
  • recipient_domain - Domain of the recipient’s email address
  • recipient_provider - Inbox provider of the recipient, when known (e.g. Gmail)
  • message_id - Message-ID header of the message
  • subject - Subject of the message
  • message_from - From header of the message
  • message_to - To header of the message
  • message_size - Size of the message in bytes
  • delivery_status_code - SMTP status code received from the recipient’s server, for delivery and failure events
  • delivery_status_message - SMTP message received from the recipient’s server
  • delivery_status_description - Description of the delivery status
  • bounce_type - Bounce classification of a failure, when Mailgun gives one
  • delivery_attempt_no - Delivery attempt number of the event
  • delivery_session_seconds - Duration of the SMTP session with the recipient’s server, in seconds
  • tags - Tags set on the message
  • url - Clicked URL, for click events
  • ip - IP address of the recipient that opened or clicked, for engagement events
  • originating_ip - IP address the message was submitted from
  • api_key_id - ID of the API key the message was sent with
  • delivered_at - When the message was delivered, as Mailgun reports it (delivery events)
  • primary_dkim - Domain of the primary DKIM signature of the message
  • i_delivery_optimizer - Delivery optimizer applied to the message, when any
  • account_id - ID of the Mailgun account (or subaccount) the event belongs to
  • parent_account_id - ID of the parent account, for subaccount events
  • account - Account of the event (JSON object with id and parent-id)
  • campaigns - Campaigns the message belongs to (JSON array of objects with id and name)
  • user_variables - Custom variables attached to the message when it was sent (JSON)
  • delivery_status - Full delivery status reported for the event (JSON object: code, message, attempt number, MX host, TLS…)
  • envelope - SMTP envelope of the message (JSON object: sender, targets, transport, sending IP, IP pool)
  • message - Message details (JSON object: headers, attachments, recipients, size, scheduled time)
  • flags - Flags of the event (JSON object: authenticated, routed, test mode, delayed bounce…)
  • geolocation - Location of the recipient for engagement events (JSON object: country, region, city, timezone)
  • client_info - Client used by the recipient for engagement events (JSON object: client name, OS, device type, user agent, bot)
  • storage - Where Mailgun stored the message, for stored and delivered events (JSON object: region, key, url)
  • template - Template the message was rendered from (JSON object: name, version, is-text)
  • routes - Inbound route that matched the message (JSON object)
  • mailing_list - Mailing list the message was sent to (JSON object: address, list-id, sid)
Primary key: domain, date · Sync: Incremental (by date)
  • date - Day the metrics refer to (start of the day, UTC), used as the incremental replication key
  • domain - Sending domain the metrics refer to
  • accepted_incoming_count - Incoming messages accepted by Mailgun
  • accepted_outgoing_count - Outgoing messages accepted by Mailgun
  • accepted_count - Messages accepted by Mailgun (incoming and outgoing)
  • delivered_smtp_count - Messages delivered over SMTP
  • delivered_http_count - Messages delivered over HTTP (to a webhook or route)
  • delivered_optimized_count - Messages delivered by the delivery optimizer
  • delivered_count - Messages delivered
  • processed_count - Messages processed
  • sent_count - Messages sent
  • opened_count - Opens (every open counts)
  • clicked_count - Clicks (every click counts)
  • unique_opened_count - Unique opens (first open of each recipient)
  • unique_clicked_count - Unique clicks (first click of each recipient)
  • unsubscribed_count - Unsubscribes
  • complained_count - Spam complaints
  • failed_count - Failed deliveries (temporary and permanent)
  • temporary_failed_count - Temporary failures (will be retried)
  • permanent_failed_count - Permanent failures
  • temporary_failed_esp_block_count - Temporary failures caused by an inbox provider block
  • permanent_failed_esp_block_count - Permanent failures caused by an inbox provider block
  • webhook_count - Webhook deliveries
  • rate_limit_count - Messages delayed by rate limits
  • permanent_failed_optimized_count - Permanent failures by the delivery optimizer
  • permanent_failed_old_count - Permanent failures because the message got too old to retry
  • bounced_count - Bounces (hard and soft)
  • hard_bounces_count - Hard bounces
  • soft_bounces_count - Soft bounces
  • delayed_bounce_count - Delayed bounces
  • suppressed_bounces_count - Messages not sent because the recipient is on the bounce list
  • suppressed_unsubscribed_count - Messages not sent because the recipient is on the unsubscribe list
  • suppressed_complaints_count - Messages not sent because the recipient is on the complaint list
  • delivered_first_attempt_count - Messages delivered on the first attempt
  • delayed_first_attempt_count - Messages delayed on the first attempt
  • delivered_two_plus_attempts_count - Messages delivered after two or more attempts
  • delivered_rate - Delivered rate (fraction of 1)
  • opened_rate - Open rate (fraction of 1)
  • clicked_rate - Click rate (fraction of 1)
  • unique_opened_rate - Unique open rate (fraction of 1)
  • unsubscribed_rate - Unsubscribe rate (fraction of 1)
  • complained_rate - Complaint rate (fraction of 1)
  • bounce_rate - Bounce rate (fraction of 1)
  • permanent_fail_rate - Permanent failure rate (fraction of 1)
  • temporary_fail_rate - Temporary failure rate (fraction of 1)
  • delayed_rate - Delayed rate (fraction of 1)
  • delayed_first_attempt_rate - Rate of messages delayed on the first attempt (fraction of 1)
Primary key: tag, date · Sync: Incremental (by date)
  • date - Day the metrics refer to (start of the day, UTC), used as the incremental replication key
  • tag - Message tag the metrics refer to
  • accepted_incoming_count - Incoming messages accepted by Mailgun
  • accepted_outgoing_count - Outgoing messages accepted by Mailgun
  • accepted_count - Messages accepted by Mailgun (incoming and outgoing)
  • delivered_smtp_count - Messages delivered over SMTP
  • delivered_http_count - Messages delivered over HTTP (to a webhook or route)
  • delivered_optimized_count - Messages delivered by the delivery optimizer
  • delivered_count - Messages delivered
  • processed_count - Messages processed
  • sent_count - Messages sent
  • opened_count - Opens (every open counts)
  • clicked_count - Clicks (every click counts)
  • unique_opened_count - Unique opens (first open of each recipient)
  • unique_clicked_count - Unique clicks (first click of each recipient)
  • unsubscribed_count - Unsubscribes
  • complained_count - Spam complaints
  • failed_count - Failed deliveries (temporary and permanent)
  • temporary_failed_count - Temporary failures (will be retried)
  • permanent_failed_count - Permanent failures
  • temporary_failed_esp_block_count - Temporary failures caused by an inbox provider block
  • permanent_failed_esp_block_count - Permanent failures caused by an inbox provider block
  • webhook_count - Webhook deliveries
  • rate_limit_count - Messages delayed by rate limits
  • permanent_failed_optimized_count - Permanent failures by the delivery optimizer
  • permanent_failed_old_count - Permanent failures because the message got too old to retry
  • bounced_count - Bounces (hard and soft)
  • hard_bounces_count - Hard bounces
  • soft_bounces_count - Soft bounces
  • delayed_bounce_count - Delayed bounces
  • suppressed_bounces_count - Messages not sent because the recipient is on the bounce list
  • suppressed_unsubscribed_count - Messages not sent because the recipient is on the unsubscribe list
  • suppressed_complaints_count - Messages not sent because the recipient is on the complaint list
  • delivered_first_attempt_count - Messages delivered on the first attempt
  • delayed_first_attempt_count - Messages delayed on the first attempt
  • delivered_two_plus_attempts_count - Messages delivered after two or more attempts
  • delivered_rate - Delivered rate (fraction of 1)
  • opened_rate - Open rate (fraction of 1)
  • clicked_rate - Click rate (fraction of 1)
  • unique_opened_rate - Unique open rate (fraction of 1)
  • unsubscribed_rate - Unsubscribe rate (fraction of 1)
  • complained_rate - Complaint rate (fraction of 1)
  • bounce_rate - Bounce rate (fraction of 1)
  • permanent_fail_rate - Permanent failure rate (fraction of 1)
  • temporary_fail_rate - Temporary failure rate (fraction of 1)
  • delayed_rate - Delayed rate (fraction of 1)
  • delayed_first_attempt_rate - Rate of messages delayed on the first attempt (fraction of 1)
Primary key: tag · Sync: Full table
  • tag - The tag, as set on the messages
  • description - Description of the tag
  • first_seen - Date and time the tag was first used (UTC)
  • last_seen - Date and time the tag was last used (UTC)
  • account_id - ID of the account the tag belongs to
  • parent_account_id - ID of the parent account, for subaccount tags
  • account_name - Name of the account the tag belongs to
Primary key: domain, address · Sync: Full table
  • domain - Name of the Mailgun sending domain the record belongs to
  • address - Email address that bounced
  • code - SMTP error code of the bounce
  • error - SMTP error message of the bounce
  • created_at - Date and time the address was added to the bounce list (UTC)
Primary key: domain, address · Sync: Full table
  • domain - Name of the Mailgun sending domain the record belongs to
  • address - Email address that unsubscribed
  • tags - Tags the address unsubscribed from (a ’*’ means from every message of the domain)
  • created_at - Date and time the address was added to the unsubscribe list (UTC)
Primary key: domain, address · Sync: Full table
  • domain - Name of the Mailgun sending domain the record belongs to
  • address - Email address that marked a message as spam
  • created_at - Date and time the address was added to the complaint list (UTC)
Primary key: domain, value · Sync: Full table
  • domain - Name of the Mailgun sending domain the record belongs to
  • value - The allowlisted email address or domain
  • type - Type of the entry: address or domain
  • reason - Reason given when the entry was created
  • created_at - Date and time the entry was created (UTC)
Primary key: address · Sync: Full table
  • address - Email address of the mailing list (its identifier)
  • name - Name of the mailing list
  • description - Description of the mailing list
  • access_level - Who can post to the list: readonly, members or everyone
  • reply_preference - Where replies go: list or sender
  • created_at - Date and time the list was created (UTC)
  • members_count - Number of members of the list when it was read
Primary key: list_address, address · Sync: Full table
  • list_address - Email address of the mailing list the member belongs to
  • address - Email address of the member
  • name - Name of the member
  • subscribed - Whether the member is subscribed to the list
  • vars - Custom variables of the member (JSON object)
Primary key: domain, name · Sync: Full table
  • domain - Name of the Mailgun sending domain the record belongs to
  • name - Name of the template (its identifier)
  • id - Unique identifier of the template
  • description - Description of the template
  • created_at - Date and time the template was created (UTC)
  • created_by - Who created the template
Primary key: domain, template_name, tag · Sync: Full table
  • domain - Name of the Mailgun sending domain the record belongs to
  • template_name - Name of the template the version belongs to
  • tag - Tag of the version, unique within the template
  • id - Unique identifier of the version
  • active - Whether this is the template’s active version (the one used when sending)
  • engine - Rendering engine of the version (e.g. handlebars)
  • comment - Comment of the version
  • created_at - Date and time the version was created (UTC)
  • template - Content of the version (HTML or text), when Mailgun returns it in the list
  • mjml - MJML source of the version, when it has one
  • headers - Headers stored with the version (JSON object, header name to value)
Primary key: name · Sync: Full table
  • name - Name of the template (its identifier)
  • id - Unique identifier of the template
  • description - Description of the template
  • created_at - Date and time the template was created (UTC)
  • created_by - Who created the template
Primary key: template_name, tag · Sync: Full table
  • template_name - Name of the template the version belongs to
  • tag - Tag of the version, unique within the template
  • id - Unique identifier of the version
  • active - Whether this is the template’s active version (the one used when sending)
  • engine - Rendering engine of the version (e.g. handlebars)
  • comment - Comment of the version
  • created_at - Date and time the version was created (UTC)
  • template - Content of the version (HTML or text), when Mailgun returns it in the list
  • mjml - MJML source of the version, when it has one
  • headers - Headers stored with the version (JSON object, header name to value)
Primary key: id · Sync: Full table
  • id - Unique identifier of the route
  • priority - Priority of the route; smaller numbers are handled first
  • description - Description of the route
  • expression - Filtering rule that selects the messages the route handles
  • actions - Actions executed when the expression matches (forward, store, stop)
  • created_at - Date and time the route was created (UTC)
Primary key: ip · Sync: Full table
  • ip - The IP address
  • dedicated - Whether the IP is dedicated to the account (when Mailgun reports it)
  • enabled - Whether the IP is enabled (when Mailgun reports it)
  • is_on_warmup - Whether the IP is in a warm-up schedule (when Mailgun reports it)
  • assignable_to_pool - Whether the IP can be assigned to a dedicated IP pool (only reported when the account has dedicated IP pools)
Primary key: pool_id · Sync: Full table
  • pool_id - Unique identifier of the dedicated IP pool
  • name - Short name of the pool
  • description - Description of the pool
  • ips - IP addresses in the pool
  • is_linked - Whether the pool is linked to any domain
  • is_inherited - Whether the pool is inherited from the parent account
  • metadata - Pool metadata (JSON object; assignments keyed by IP with the date each was linked)
Primary key: id · Sync: Full table
  • id - Unique identifier of the subaccount
  • name - Name of the subaccount
  • status - Status of the subaccount: open, disabled or closed
  • created_at - Date and time the subaccount was created (UTC)
  • updated_at - Date and time the subaccount was last updated (UTC)
  • features - Features enabled on the subaccount (JSON object)
Primary key: id · Sync: Full table
  • id - Unique identifier of the user
  • name - Full name of the user
  • email - Email address of the user
  • role - Role of the user on the account (basic/analyst, billing, support, developer, admin)
  • account_id - ID of the account the user belongs to
  • activated - Whether the user is activated
  • is_disabled - Whether the user is disabled
  • is_master - Whether the user is the account owner
  • tfa_enabled - Whether two-factor authentication is enabled for the user
  • tfa_active - Whether two-factor authentication is active for the user
  • tfa_created_at - Date and time two-factor authentication was activated (UTC)
  • password_updated_at - Date and time the user’s password was last changed (UTC)
  • migration_status - Status of the user’s migration to Sinch ID, when applicable
  • email_details - Parsed email address of the user (JSON object: address, is_valid, parts)
  • preferences - User preferences (JSON object: time zone, time format, programming language)
  • metadata - Optional metadata of the user (JSON object)
Primary key: webhook_id · Sync: Full table
  • webhook_id - Unique identifier of the webhook
  • description - Description of the webhook
  • url - URL the events are posted to
  • event_types - Event types that trigger the webhook
  • created_at - Date and time the webhook was created (UTC)
  • exclude_subaccounts - Whether the webhook applies only to this account’s domains and not to its subaccounts’

Implementation notes

  • Events come from the Mailgun Logs API (the older Events API is deprecated), read one day at a time and checked against the total Mailgun reports for each day.
  • Daily Metrics and Daily Tag Metrics come from the Mailgun Metrics API (the older Stats API is deprecated). Rates are fractions of 1 (0.83 = 83%).
  • Snapshot tables (every table except Events and the daily metrics) are read in full before they are loaded, so a failed sync never leaves a partial table.
  • Permissions: the API key must be a Private API key. Keys with roles: Analyst reads most tables; Users may need a higher role. Subaccounts, account-level templates, dedicated IP pools and account webhooks depend on your Mailgun plan.