Webhooks

This API allows you to create, access, and delete webhooks programmatically.

Supported webhooks, and their documentation, are listed below:

Webhook Name Documentation
bounce Tracking Bounces
deliver Tracking Deliveries
drop Tracking Failures
spam Tracking Spam Complaints
unsubscribe Tracking Unsubscribes
click Tracking Clicks
open Tracking Opens
GET /domains/<domain>/webhooks

Returns a list of webhooks set for the specified domain.

Parameter Description
domain Name of the domain
GET /domains/<domain>/webhooks/<webhookname>

Returns details about a the webhook specified in the URL.

Parameter Description
domain Name of the domain
id Name of the webhook. (See above for supported webhooks)
POST /domains/<domain>/webhooks

Creates a new webhook.

Note

When adding a Click or Open webhook, ensure that you also have tracking enabled.

Parameter Description
domain Name of the domain
id Name of the webhook. (See above for supported webhooks)
url URL for the webhook event.
PUT /domains/<domain>/webhooks/<webhookname>

Updates an existing webhook.

Parameter Description
domain Name of the domain
id Name of the webhook. (See above for supported webhooks)
url URL for the webhook event.
DELETE /domains/<domain>/webhooks/<webhookname>

Deletes an existing webhook.

Note

Mailgun imposes a rate limit for the Webhook API endpoint. Users may issue no more than 300 requests per minute, per account. See the resultant rate limit response below.

Parameter Description
domain Name of the domain
id Name of the webhook. (See above for supported webhooks)

Examples

Return a list of webhooks set for the specified domain.

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;

import javax.ws.rs.core.Form;
import javax.ws.rs.core.MediaType;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

public class MGSample {

    // ...

    public static ClientResponse GetWebhooks() {

        Client client = ClientBuilder.newClient();
        client.register(HttpAuthenticationFeature.basic(
            "api",
            "YOUR_API_KEY"
        ));

        WebTarget mgRoot = client.target("https://api.mailgun.net/v3");

        return mgRoot
            .path("/domains/{domain}/webhooks")
            .resolveTemplate("domain", "YOUR_DOMAIN_NAME")
            .request()
            .buildGet()
            .invoke(ClientResponse.class);
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->get("domains/$domain/webhooks");
def get_bounces():
    return requests.get(
        "https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks",
        auth=("api", "YOUR_API_KEY"))
def get_webhooks
  RestClient.get "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetWebhooksChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetWebhooks ().Content.ToString ());
    }

    public static IRestResponse GetWebhooks ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "domains/{domain}/webhooks";
        return client.Execute (request);
    }

}
func GetWebhooks(domain, apiKey string) (map[string]string, error) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.GetWebhooks()
}

Sample response:

{
  "webhooks": {
    "open": {
      "url": "http://postbin.heroku.com/860bcd65"
    },
    "click": {
      "url": "http://postbin.heroku.com/860bcd65"
    }
  }
}

Return a webhook for a specific event for the defined domain.

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/click
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;

import javax.ws.rs.core.Form;
import javax.ws.rs.core.MediaType;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

public class MGSample {

    // ...

    public static ClientResponse GetWebhook() {

        Client client = ClientBuilder.newClient();
        client.register(HttpAuthenticationFeature.basic(
            "api",
            "YOUR_API_KEY"
        ));

        WebTarget mgRoot = client.target("https://api.mailgun.net/v3");

        return mgRoot
            .path("/domains/{domain}/webhooks/click")
            .resolveTemplate("domain", "YOUR_DOMAIN_NAME")
            .request()
            .buildGet()
            .invoke(ClientResponse.class);
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->get("$domain/webhooks/click");
def get_domain():
    return requests.get(
        "https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/click",
        auth=("api", "YOUR_API_KEY"))
def get_domain
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/click"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetWebhookChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (GetWebhook ().Content.ToString ());
    }

    public static IRestResponse GetWebhook ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "/domains/{domain}/webhooks/click";
        return client.Execute (request);
    }

}
func GetWebhook(domain, apiKey string) (string, error) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.GetWebhookByType("deliver")
}

Sample response:

{
  "webhook": {
    "url": "http://google.com"
  }
}

Create a new webhook.

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks \
    -F id='click' \
    -F url='http://bin.example.com/8de4a9c4'
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;

import javax.ws.rs.core.Form;
import javax.ws.rs.core.MediaType;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

public class MGSample {

    // ...

    public static ClientResponse AddUnsubscribeAll() {

        Client client = ClientBuilder.newClient();
        client.register(HttpAuthenticationFeature.basic(
            "api",
            "YOUR_API_KEY"
        ));

        WebTarget mgRoot = client.target("https://api.mailgun.net/v3");

        Form reqData = new Form();
        reqData.param("id", "click");
        reqData.param("url", "http://bin.example.com/8de4a9c4");

        return mgRoot
            .path("/domains/{domain}/webhooks")
            .resolveTemplate("domain", "YOUR_DOMAIN_NAME")
            .request(MediaType.APPLICATION_FORM_URLENCODED)
            .buildPost(Entity.entity(reqData, MediaType.APPLICATION_FORM_URLENCODED))
            .invoke(ClientResponse.class);
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->post("domains/$domain/webhooks", array(
    'id'  => 'click',
    'url' => 'http://bin.example.com/8de4a9c4'
));
def add_webhook():
    return requests.post(
        "https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks",
        auth=("api", "YOUR_API_KEY"),
        data={'id':'click', 'url':'http://bin.example.com/8de4a9c4'})
def add_webhook
  RestClient.post("https://api:YOUR_API_KEY"\
                  "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks",
                  :id => 'click',
                  :url => 'http://bin.example.com/8de4a9c4')
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class AddWebhookChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (AddWebhook ().Content.ToString ());
    }

    public static IRestResponse AddWebhook ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3/");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "domains/YOUR_DOMAIN_NAME/webhooks";
        request.AddParameter ("id", "click");
        request.AddParameter ("url", "http://bin.example.com/8de4a9c4");
        request.Method = Method.POST;
        return client.Execute (request);
    }

}
func CreateWebhook(domain, apiKey string) error {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.CreateWebhook("deliver", "http://www.example.com")
}

Sample response:

{
  "message": "Webhook has been created",
  "webhook": {
    "url": "http://bin.mailgun.net/8de4a9c4"
  }
}

Update an existing webhook.

curl -s --user 'api:YOUR_API_KEY' -X PUT \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/click \
    -F url='http://google.com'
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;

import javax.ws.rs.core.Form;
import javax.ws.rs.core.MediaType;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

public class MGSample {

    // ...

    public static ClientResponse UpdateWebhook() {

        Client client = ClientBuilder.newClient();
        client.register(HttpAuthenticationFeature.basic(
            "api",
            "YOUR_API_KEY"
        ));

        WebTarget mgRoot = client.target("https://api.mailgun.net/v3");

        Form reqData = new Form();
        reqData.param("url", "http://bin.example.com/8de4a9c4");

        return mgRoot
            .path("/domains/{domain}/webhooks/{webhook_id}")
            .resolveTemplate("domain", "YOUR_DOMAIN_NAME")
            .resolveTemplate("webhook_id", "click")
            .request(MediaType.APPLICATION_FORM_URLENCODED)
            .buildPut(Entity.entity(reqData, MediaType.APPLICATION_FORM_URLENCODED))
            .invoke(ClientResponse.class);
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$listAddress = 'YOUR_DOMAIN_NAME';
$memberAddress = 'bob@example.com';

# Issue the call to the client.
$result = $mgClient->put("$domain/webhooks/click", array(
    'url' => 'http://google.com'
));
def update_member():
    return requests.put(
        ("https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/click"),
        auth=('api', 'YOUR_API_KEY'),
        data={'url': 'http://google.com'})
def update_member
  RestClient.put("https://api:YOUR_API_KEY" \
                 "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/click" \
                 "/bar@example.com",
                 :url => 'http://google.com')
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class UpdateWebhookChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (UpdateWebhook ().Content.ToString ());
    }

    public static IRestResponse UpdateWebhook ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "/domains/YOUR_DOMAIN_NAME/webhooks/click";
        request.AddParameter ("url", "http://google.com");
        request.Method = Method.PUT;
        return client.Execute (request);
    }

}
func UpdateWebhook(domain, apiKey string) error {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.UpdateWebhook("deliver", "http://api.example.com")
}

Sample response:

{
  "message": "Webhook has been updated",
  "webhook": {
    "url": "http://google.com"
  }
}

Delete a webhook.

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/click
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;

import javax.ws.rs.core.Form;
import javax.ws.rs.core.MediaType;

import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;

public class MGSample {

    // ...

    public static ClientResponse DeleteWebhook() {

        Client client = ClientBuilder.newClient();
        client.register(HttpAuthenticationFeature.basic(
            "api",
            "YOUR_API_KEY"
        ));

        WebTarget mgRoot = client.target("https://api.mailgun.net/v3");

        return mgRoot
            .path("/domains/{domain}/webhooks/{webhook_id}")
            .resolveTemplate("domain", "YOUR_DOMAIN_NAME")
            .resolveTemplate("webhook_id", "WEBHOOK_ID")
            .request(MediaType.APPLICATION_FORM_URLENCODED)
            .buildDelete()
            .invoke(ClientResponse.class);
    }
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = new Mailgun('YOUR_API_KEY');
$domain = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->delete("$domain/webhooks/click");
def delete_domain():
    return requests.delete(
        "https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/click",
        auth=("api", "YOUR_API_KEY"))
def delete_domain
  RestClient.delete "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/click"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class DeleteWebhookChunk
{

    public static void Main (string[] args)
    {
        Console.WriteLine (DeleteWebhook ().Content.ToString ());
    }

    public static IRestResponse DeleteWebhook ()
    {
        RestClient client = new RestClient ();
        client.BaseUrl = new Uri ("https://api.mailgun.net/v3");
        client.Authenticator =
            new HttpBasicAuthenticator ("api",
                                        "YOUR_API_KEY");
        RestRequest request = new RestRequest ();
        request.Resource = "/domains/{name}/webhooks/click";
        request.AddUrlSegment ("name", "YOUR_DOMAIN_NAME");
        request.Method = Method.DELETE;
        return client.Execute (request);
    }

}
func DeleteWebhook(t *testing.T) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.DeleteWebhook("deliver")
}

Sample response:

{
  "message": "Webhook has been deleted",
  "webhook": {
    "url": "http://postbin.heroku.com/860bcd65"
  }
}

Rate Limit Response:

{
        "retry-seconds": 60,
}