Mailgun

Transactional email. Send messages, manage sending domains and templates, read delivery events, and handle bounces.

Measured routing accuracy

74 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 37 cases written by hand and 37 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

api_key

Submit the key with ConnectionsService rather than putting it in a request; it is sealed at rest and never returned.

Tools

37 action tools. The catalog-wide slug is mailgun.<tool>, which is what search_tools returns and call_tool takes.

mailgun.list_domains

List the sending domains configured on this Mailgun account, paginated. Use when the user asks what domains, sending domains, or verified domains exist in Mailgun, rather than looking up one specific domain.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/domains.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what domains are hooked up to send mail", "show every sending domain on the account", "browse the domains we've registered", "see which hostnames are set up to email from".

mailgun.get_domain

Get one Mailgun sending domain's full details by name: its verification state, DKIM/SPF setup, and the DNS records it still needs. Use when the user names a specific domain rather than browsing all of them, or asks why a domain won't verify.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/domains/{{params.domain}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "check the dns setup for our sending domain", "pull up details on one hostname we send from", "why won't this domain verify".

mailgun.create_domain

Register a new sending domain in Mailgun. Use when the user wants to add, connect, or set up a new domain to send email from, not verify or configure a domain that already exists. Returns the DNS records the domain must add before it can send.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/domains.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "hook up a new hostname to send email from", "register a fresh domain for outbound mail", "set up a new place to send from", "connect another domain to the account".

mailgun.delete_domain

Permanently delete a Mailgun sending domain, stopping it from sending or receiving any mail. Use when the user wants to remove, decommission, or delete a domain entirely, not disable one temporarily. Irreversible; the domain's own DNS records must be removed separately at the registrar.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes domains.write. Calls DELETE /v3/domains/{{params.domain}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "decommission a sending domain for good", "remove a hostname from the account entirely", "shut down a domain we no longer use".

mailgun.verify_domain

Re-check a Mailgun domain's DNS records and refresh its verification state. Use when the user just added the required DNS records and wants Mailgun to confirm the domain, or asks why a domain is still showing unverified.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PUT /v3/domains/{{params.domain}}/verify.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "recheck the dns records for this hostname", "confirm the domain now that records are in place", "re-run the verification check".

mailgun.update_domain_connection_settings

Change a Mailgun domain's delivery connection settings: whether to require TLS on outbound delivery and whether to skip certificate verification on the receiving server. Use when the user wants to enforce or relax TLS for a domain's outgoing mail, not its DNS or spam handling.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PUT /v3/domains/{{params.domain}}/connection.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "force tls on outbound delivery for this domain", "toggle strict certificate checking for sends", "change how strict the delivery connection is".

mailgun.send_message

Send a transactional email through Mailgun from a verified sending domain, either as raw text/HTML or rendered from a saved template. Use when the user wants to send, deliver, or email a message right now. This is the core send action, distinct from managing domains, templates, or suppressions.

Class write (writes, no confirmation needed). Scopes messages.write. Calls POST /v3/{{params.domain}}/messages.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fire off a transactional email right now", "deliver a message to this recipient", "email someone from our domain", "push out a notification email", "render a template and mail it to someone".

mailgun.list_events

List Mailgun delivery events for a domain: accepted, delivered, failed, opened, clicked, unsubscribed, or complained, filterable by event type, recipient, and time range. Use when the user asks what happened to a message, wants delivery logs, or wants recent activity for a domain.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/{{params.domain}}/events.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what happened to this message", "pull the delivery logs for this domain", "show recent activity like opens and clicks", "check why a send failed".

mailgun.validate_email

Check whether a single email address is valid and deliverable before sending to it. Use when the user wants to verify, check, or clean an address, or asks whether it is real, disposable, or a role account like "info@" or "support@". This checks one address, distinct from domain verification.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v4/address/validate.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "is this address even real", "check if this inbox actually exists before sending", "clean this email before adding it anywhere", "is this a throwaway or role account".

mailgun.list_bounces

List the email addresses Mailgun has suppressed for bouncing on a domain, paginated. Use when the user asks which addresses are bouncing or blocked as bounces, rather than looking up one specific address.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/{{params.domain}}/bounces.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "which addresses are bouncing right now", "show me who's blocked as undeliverable", "browse the bounced addresses on this domain".

mailgun.get_bounce

Check whether one email address is on a Mailgun domain's bounce suppression list, and why. Use when the user names a specific address rather than browsing the full bounce list.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/{{params.domain}}/bounces/{{params.address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "why did this address bounce", "check if this recipient is stuck on the bounce list", "pull the failure reason for one recipient".

mailgun.create_bounce

Manually add an email address to a Mailgun domain's bounce suppression list, blocking future sends to it. Use when the user wants to proactively suppress or block an address, not remove one that already bounced on its own.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/{{params.domain}}/bounces.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "block this address from ever getting mail", "proactively suppress a bad recipient", "add this inbox to the do-not-send list".

mailgun.delete_bounce

Remove one email address from a Mailgun domain's bounce suppression list, allowing mail to it again. Use when the user wants to un-suppress, unblock, or retry an address that was incorrectly or is no longer bouncing.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v3/{{params.domain}}/bounces/{{params.address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "let mail through to this address again", "clear the bounce flag on this recipient", "retry sending to a previously bounced inbox".

mailgun.list_unsubscribes

List the email addresses that have unsubscribed from a Mailgun domain, paginated. Use when the user asks who has opted out or unsubscribed, rather than looking up one specific address.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/{{params.domain}}/unsubscribes.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who has opted out of our mail", "show everyone who unsubscribed", "browse the opt-out list for this domain".

mailgun.get_unsubscribe

Check whether one email address has unsubscribed from a Mailgun domain, and from which tag. Use when the user names a specific address rather than browsing the full unsubscribe list.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/{{params.domain}}/unsubscribes/{{params.address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did this person opt out", "check if this recipient unsubscribed already", "which tag did this address opt out of".

mailgun.create_unsubscribe

Manually mark an email address as unsubscribed from a Mailgun domain, so it stops receiving mail tagged that way. Use when the user wants to opt someone out proactively, for example honoring an opt-out request made outside Mailgun's own unsubscribe link.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/{{params.domain}}/unsubscribes.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "honor an opt-out someone requested by phone", "mark this person as opted out manually", "stop sending to someone who asked outside the usual link".

mailgun.delete_unsubscribe

Remove an email address from a Mailgun domain's unsubscribe list, so it can receive mail again. Use when the user wants to resubscribe or reinstate an address that had previously opted out.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v3/{{params.domain}}/unsubscribes/{{params.address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "let this person receive our mail again", "reinstate someone who had opted out", "undo an unsubscribe for this recipient".

mailgun.list_complaints

List the email addresses that have marked mail from a Mailgun domain as spam, paginated. Use when the user asks who complained or reported spam, rather than looking up one specific address.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/{{params.domain}}/complaints.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who reported our mail as spam", "show everyone who flagged us as junk", "browse spam reports for this domain".

mailgun.get_complaint

Check whether one email address has filed a spam complaint against a Mailgun domain. Use when the user names a specific address rather than browsing the full complaint list.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/{{params.domain}}/complaints/{{params.address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "did this recipient mark us as spam", "check for a spam flag on this address", "has this person filed a junk report".

mailgun.create_complaint

Manually add an email address to a Mailgun domain's spam complaint list, suppressing future sends to it. Use when the user wants to record a complaint that was reported outside Mailgun's own feedback loop.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/{{params.domain}}/complaints.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "log a spam report that came in some other way", "record that someone flagged this as junk", "note down a junk report we heard about by phone".

mailgun.delete_complaint

Remove an email address from a Mailgun domain's spam complaint list, allowing mail to it again. Use when the user believes a complaint was filed in error and wants to reinstate the address.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). No scopes beyond the connection's defaults. Calls DELETE /v3/{{params.domain}}/complaints/{{params.address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "this complaint was filed by mistake, clear it", "reinstate an address wrongly marked as spam", "this junk report doesn't belong here, take it off".

mailgun.list_mailing_lists

List the mailing lists on this Mailgun account, paginated. Use when the user asks what mailing lists or distribution lists exist, rather than looking up one specific list.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/lists.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what distribution lists do we have", "show every subscriber list on the account", "browse our mailgun groups".

mailgun.get_mailing_list

Get one Mailgun mailing list's details by address: its name, description, member count, and who can post to it. Use when the user names a specific list rather than browsing all of them.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/lists/{{params.list_address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull up info on our announcement list", "check who can post to this distribution list", "how many subscribers does this group have".

mailgun.create_mailing_list

Create a new Mailgun mailing list. Use when the user wants to start a new distribution list or subscriber list on Mailgun, not add a person to a list that already exists. Requires the list's own posting address.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/lists.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "start a new distribution list", "set up a group people can subscribe to", "build a fresh announcement list".

mailgun.update_mailing_list

Update an existing Mailgun mailing list's name, description, or who can post to it. Use when the user wants to edit a list's settings, not add or remove a member.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PUT /v3/lists/{{params.list_address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "change who's allowed to post to this list", "edit the description on this distribution list", "rename this announcement group".

mailgun.delete_mailing_list

Permanently delete a Mailgun mailing list and every member on it. Use when the user wants to remove, delete, or shut down an entire mailing list, not unsubscribe one person. Irreversible.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes lists.write. Calls DELETE /v3/lists/{{params.list_address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "shut down this whole distribution list", "get rid of a group and everyone in it", "tear down a list we don't need anymore".

mailgun.add_list_member

Add one new subscriber to a Mailgun mailing list, or update one that already exists there. Use when the user wants to subscribe, sign up, or add a single person's email to a list. For adding many people at once use add_list_members_bulk instead.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/lists/{{params.list_address}}/members.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "sign someone up for this distribution list", "get one person subscribed to the group", "put this email on the announcement list".

mailgun.get_list_member

Get one Mailgun mailing list subscriber's record by list and address: their name, custom variables, and subscription status. Use when the user names a specific person already on the list.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/lists/{{params.list_address}}/members/{{params.member_address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "pull up one subscriber's record", "check this person's status on the group", "what merge variables do we have on file for them".

mailgun.list_list_members

List the subscribers on a Mailgun mailing list, paginated, optionally filtered to only active or only unsubscribed members. Use for browsing or exporting a list's membership rather than looking up one specific subscriber.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/lists/{{params.list_address}}/members/pages.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "who's subscribed to this distribution list", "export the roster of this group", "see everyone on the announcement list".

mailgun.update_list_member

Update a Mailgun mailing list subscriber's name, custom variables, or subscription status. Use when the user wants to edit, resubscribe, or unsubscribe an existing member, not add a new person.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PUT /v3/lists/{{params.list_address}}/members/{{params.member_address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "fix this subscriber's info on the list", "resubscribe someone who had opted out of the group", "change the merge variables stored for this person".

mailgun.delete_list_member

Permanently remove one subscriber from a Mailgun mailing list. Use when the user wants to unsubscribe, remove, or delete a single person from a list. Irreversible; re-adding them requires their email address again.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes lists.write. Calls DELETE /v3/lists/{{params.list_address}}/members/{{params.member_address}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "take this person off the distribution list", "remove one subscriber from the group", "drop them off the announcement roster for good".

mailgun.add_list_members_bulk

Add or update many subscribers on a Mailgun mailing list in one call. Use when the user wants to import, upload, or bulk-add a batch of people to a list, not add one person at a time with add_list_member.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/lists/{{params.list_address}}/members.json.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "import a batch of subscribers at once", "upload a csv of people into the group", "bulk add a bunch of new members".

mailgun.list_templates

List the reusable transactional email templates saved for a Mailgun domain, paginated. Use when the user asks what templates exist, rather than looking up one specific template.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/{{params.domain}}/templates.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "what reusable email designs do we have saved", "show every transactional template", "browse our saved message layouts".

mailgun.get_template

Get one Mailgun template's details by name, including its active version's content. Use when the user names a specific template rather than browsing all of them, or wants to review what it currently says.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/{{params.domain}}/templates/{{params.name}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "show me the content of this saved template", "pull up what this email design currently says", "which version of this layout is active right now".

mailgun.create_template

Save a new reusable transactional email template in Mailgun from HTML or plain text. Use when the user wants to create a template for use in send_message, not set the body of one specific message.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/{{params.domain}}/templates.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "save this html as a reusable message design", "store a new transactional layout for later", "build a new reusable notification design from scratch".

mailgun.create_template_version

Add a new version to an existing Mailgun template. Use when the user wants to update, revise, or edit a template's content rather than create a brand-new template. Set active to true to make this the version send_message uses by default.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/{{params.domain}}/templates/{{params.name}}/versions.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "publish a new revision of this template", "update the content on an existing design", "make this the new active version of the layout".

mailgun.delete_template

Permanently delete a Mailgun template and all of its versions. Use when the user wants to remove a saved template entirely; messages already sent from it are unaffected. Irreversible.

Class destructive (held by the mutation gate until the call's own arguments carry "confirm": true). Scopes templates.write. Calls DELETE /v3/{{params.domain}}/templates/{{params.name}}.

Arguments:

Result fields (the payload is trimmed to these before it reaches the model):

Also retrieved by: "remove a saved design we don't use anymore", "get rid of an old message layout for good", "clear out a stale notification design entirely".