Webhooks

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

Note

A previous version of the API is described here Webhooks (deprecated)

Supported webhooks, and their documentation, are listed below:

Webhook Name Documentation
clicked Tracking Clicks
complained Tracking Spam Complaints
delivered Tracking Deliveries
opened Tracking Opens
permanent_fail Tracking Failures
temporary_fail Tracking Failures
unsubscribed Tracking Unsubscribes
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 Clicked or Opened 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. May be repeated up to 3 times.
PUT /domains/<domain>/webhooks/<webhookname>

Updates an existing webhook.

Parameter Description
domain Name of the domain
webhookname Name of the webhook. (See above for supported webhooks)
url URL for the webhook event. May be repeated up to 3 times.
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
webhookname 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 com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getWebhooks() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v3/domains/" + YOUR_DOMAIN_NAME + "/webhooks")
            .basicAuth("api", API_KEY)
            .asJson();

           return request.getBody();
    }
}
# 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()
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get(`/domain/${DOMAIN}/webhooks`, function (error, body) {
  console.log(body);
});

Sample response:

{
  "webhooks": {
    "opened": {
      "urls": [
                "https://your_domain.com/v1/opened",
                "https://your_domain.com/v2/opened"
              ]
    },
    "clicked": {
      "urls": [ "https://your_domain.com/v1/clicked" ]
    }
  }
}

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/clicked
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode getWebhookEvent() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v3/domains/" + YOUR_DOMAIN_NAME + "/webhooks/clicked")
            .basicAuth("api", API_KEY)
            .asJson();

        return request.getBody();
    }
}
# 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/clicked");
def get_domain():
    return requests.get(
        "https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/clicked",
        auth=("api", "YOUR_API_KEY"))
def get_domain
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/clicked"\
                 {|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/clicked";
        return client.Execute (request);
    }

}
func GetWebhook(domain, apiKey string) (string, error) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.GetWebhookByType("clicked")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.get(`/domain/${DOMAIN}/webhooks/clicked`, function (error, body) {
  console.log(body);
});

Sample response:

{
  "webhook": {
    "urls": [ "https://your_domain.com/v1/clicked" ]
  }
}

Create a new webhook.

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks \
    -F id='clicked' \
    -F url='https://your_domain.com/v1/clicked'
    -F url='https://your_domain.com/v2/clicked'
    -F url='https://your_partner_domain.com/v1/clicked'
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode addWebhook() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v3/domains/" +
                                                       YOUR_DOMAIN_NAME +
                                                       "/webhooks")
                     .basicAuth("api", API_KEY)
                     .field("id","click")
                     .field("url", "https://your_domain.com/v1/clicked")
                     .field("url", "https://your_domain.com/v2/clicked")
                     .field("url", "https://your_partner_domain.com/v1/clicked")
             }).asJson();

        return request.getBody();
    }
}
# 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'  => 'clicked',
    'url' => array(
        'https://your_domain.com/v1/clicked',
        'https://your_domain.com/v2/clicked',
        'https://your_partner_domain.com/v1/clicked'
    )
));
def add_webhook():
    return requests.post(
        "https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks",
        auth=("api", "YOUR_API_KEY"),
        data={
          'id':'clicked',
          'url':[ 'https://your_domain.com/v1/clicked',
                  'https://your_domain.com/v2/clicked',
                  'https://your_partner_domain.com/v1/clicked'
          ]
        })
def add_webhook
  RestClient.post("https://api:YOUR_API_KEY"\
                  "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks",
                  :id => 'clicked',
                  :url => ['https://your_domain.com/v1/clicked',
                           'https://your_domain.com/v2/clicked',
                           'https://your_partner_domain.com/v1/clicked'])
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", "clicked");
        request.AddParameter ("url", "https://your_domain.com/v1/clicked")
        request.AddParameter ("url", "https://your_domain.com/v2/clicked")
        request.AddParameter ("url", "https://your_partner_domain.com/v1/clicked")
        request.Method = Method.POST;
        return client.Execute (request);
    }

}
func CreateWebhook(domain, apiKey string) error {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.CreateWebhook("clicked", "https://your_domain.com/v1/clicked")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });
var urls = ['https://your_domain.com/v1/clicked', 'https://your_domain.com/v2/clicked', 'https://your_parner_domain.com/v1/clicked']

mailgun.post(`/domain/${DOMAIN}/webhooks`, {"id": 'clicked', "url": urls}, function (error, body) {
  console.log(body);
});

Sample response:

{
  "message": "Webhook has been created",
  "webhook": {
    "urls": [
              "https://your_domain.com/v1/clicked",
              "https://your_domain.com/v2/clicked",
              "https://your_partner_domain.com/v1/clicked"
            ]
  }
}

Update an existing webhook.

curl -s --user 'api:YOUR_API_KEY' -X PUT \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/clicked \
    -F url='https://your_domain,com/v1/clicked'
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode updateWebhook() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.put("https://api.mailgun.net/v3/domains/" + YOUR_DOMAIN_NAME + "/webhooks/clicked")
            .basicAuth("api", API_KEY)
            .field("url", "https://your_domain.com/clicked")
            .asJson();

        return request.getBody();
    }
}
# 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/clicked", array(
    'url' => 'https://your_domain.com/clicked'
));
def update_webhook():
    return requests.put(
        ("https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/clicked"),
        auth=('api', 'YOUR_API_KEY'),
        data={'url': 'https://your_domain.com/clicked'})
def update_webhook
  RestClient.put("https://api:YOUR_API_KEY" \
                 "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/clicked",
                 :url => 'https://your_domain.com/clicked')
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/clicked";
        request.AddParameter ("url", "https://your_domain.com/clicked");
        request.Method = Method.PUT;
        return client.Execute (request);
    }

}
func UpdateWebhook(domain, apiKey string) error {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.UpdateWebhook("clicked", "https://your_domain.com/clicked")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.put(`/domain/${DOMAIN}/webhooks/clicked`, {"url": 'https://your_domain.com/v1/clicked'}, function (error, body) {
  console.log(body);
});

Sample response:

{
  "message": "Webhook has been updated",
  "webhook": {
    "urls": [ "https://your_domain.com/v1/clicked" ]
  }
}

Delete a webhook.

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/clicked
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import com.mashape.unirest.http.exceptions.UnirestException;

public class MGSample {

    // ...

    public static JsonNode deleteWebhook() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.delete("https://api.mailgun.net/v3/domains/" + YOUR_DOMAIN_NAME + "/webhooks/clicked")
            .basicAuth("api", API_KEY)
                   .asJson();

        return request.getBody();
    }
}
# 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/clicked");
def delete_domain():
    return requests.delete(
        "https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/clicked",
        auth=("api", "YOUR_API_KEY"))
def delete_domain
  RestClient.delete "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/clicked"
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/clicked";
        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("clicked")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.delete(`/domain/${DOMAIN}/webhooks/clicked`, function (error, body) {
  console.log(body);
});

Sample response:

{
  "message": "Webhook has been deleted",
  "webhook": {
    "urls": [
              "https://your_domain.com/v1/clicked",
              "https://your_domain.com/v2/clicked",
              "https://your_partner_domain.com/v1/clicked"
            ]
  }
}

Rate Limit Response:

{
        "retry-seconds": 60,
}