Webhooks

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

The webhooks API endpoint is available at:

v3/domains/<domain>/webhooks

Supported webhooks, and their documentation, are listed below:

Webhook Name Documentation
accepted Tracking Accepted
clicked Tracking Clicks
complained Tracking Spam Complaints
delivered Tracking Deliveries
opened Tracking Opens
permanent_fail Tracking Failures
temporary_fail Tracking Failures
unsubscribed Open and Click Bot Detection
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.mailgun.api.v3.MailgunWebhooksApi;
import com.mailgun.model.webhooks.WebhookListResult;;

// ...

public WebhookListResult getWebhooks() {
    MailgunWebhooksApi mailgunWebhooksApi = MailgunClient.config(API_KEY).createApi(MailgunWebhooksApi.class);

    return mailgunWebhooksApi.getAllWebhooks(YOUR_DOMAIN_NAME);
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$domain   = 'YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->webhooks()->index($domain)
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);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func ListWebhooks(domain, apiKey string) (map[string]string, error) {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mg.ListWebhooks(ctx)
}
const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const webhooks = await client.webhooks.list(DOMAIN);
    console.log('webhooks', webhooks);
  } catch (error) {
    console.error(error);
  }
})();

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.mailgun.api.v3.MailgunWebhooksApi;
import com.mailgun.enums.WebhookName;
import com.mailgun.model.webhooks.WebhookDetailsResult;

// ...

public WebhookDetailsResult getWebhookEvent() {
    MailgunWebhooksApi mailgunWebhooksApi = MailgunClient.config(API_KEY).createApi(MailgunWebhooksApi.class);

    return mailgunWebhooksApi.getWebhookDetails(YOUR_DOMAIN_NAME, WebhookName.CLICKED);
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$domain   = 'YOUR_DOMAIN_NAME';
$webhook  = 'delivered';

# Issue the call to the client.
$result = $mgClient->webhooks()->show($domain, $webhook)
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);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func GetWebhook(domain, apiKey string) (string, error) {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mg.GetWebhook(ctx, "clicked")
}
const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const webhooks = await client.webhooks.get(DOMAIN,'delivered');
    console.log('webhooks', webhooks);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

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

Create a new webhook.

curl -s --user 'api:YOUR_API_KEY' -X POST \
   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.mailgun.api.v3.MailgunWebhooksApi;
import com.mailgun.enums.WebhookName;
import com.mailgun.model.webhooks.WebhookRequest;
import com.mailgun.model.webhooks.WebhookResult;

import java.util.List;

// ...

public WebhookResult addWebhook() {
    MailgunWebhooksApi mailgunWebhooksApi = MailgunClient.config(API_KEY).createApi(MailgunWebhooksApi.class);

    WebhookRequest request = WebhookRequest.builder()
        .webhookName(WebhookName.CLICKED)
        .url("https://your_domain.com/v1/clicked")
        .urls(List.of("https://your_domain.com/v2/clicked", "https://your_partner_domain.com/v1/clicked"))
        .build();

    return mailgunWebhooksApi.createNewWebhook(YOUR_DOMAIN_NAME, request);
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$domain   = 'YOUR_DOMAIN_NAME';
$webhook  = 'delivered';
$destination_url = 'https://my.webhook.url/delivered'

# Issue the call to the client.
$result = $mgClient->webhooks()->create($domain, $webhook, $destination_url);
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);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func CreateWebhook(domain, apiKey string) error {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mg.CreateWebhook(ctx, "clicked", []string{"https://your_domain.com/v1/clicked"})
}
const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    // clicked or one of the Supported webhooks
    const createdWebhook = await client.webhooks.create(DOMAIN, 'clicked', 'https://your_domain.com/v1/clicked');
    console.log('createdWebhook', createdWebhook);
  } catch (error) {
      console.error(error);
  }
})();

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.mailgun.api.v3.MailgunWebhooksApi;
import com.mailgun.enums.WebhookName;
import com.mailgun.model.webhooks.WebhookResult;
import com.mailgun.model.webhooks.WebhookUpdateRequest;

// ...

public WebhookResult updateWebhook() {
    MailgunWebhooksApi mailgunWebhooksApi = MailgunClient.config(API_KEY)
        .createApi(MailgunWebhooksApi.class);

    WebhookUpdateRequest request = WebhookUpdateRequest.builder()
        .url("https://your_domain.com/clicked")
        .build();

    return mailgunWebhooksApi.updateWebhook(YOUR_DOMAIN_NAME, WebhookName.CLICKED, request);
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$domain   = 'YOUR_DOMAIN_NAME';
$webhook  = 'delivered';
$destination_url = 'https://my.webhook.url/delivered'

# Issue the call to the client.
$result = $mgClient->webhooks()->update($domain, $webhook, $destination_url);
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);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func UpdateWebhook(domain, apiKey string) error {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mg.UpdateWebhook(ctx, "clicked", []string{"https://your_domain.com/clicked"})
}
const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const updatedWebhooks = await client.webhooks.update(DOMAIN, 'clicked', 'https://your_domain.com/v1/clicked');
    console.log('updatedWebhooks', updatedWebhooks);
  } catch (error) {
    console.error(error);
  }
})();

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.mailgun.api.v3.MailgunWebhooksApi;
import com.mailgun.enums.WebhookName;
import com.mailgun.model.webhooks.WebhookResult;

// ...

public WebhookResult deleteWebhook() {
    MailgunWebhooksApi mailgunWebhooksApi = MailgunClient.config(API_KEY).createApi(MailgunWebhooksApi.class);

    return mailgunWebhooksApi.deleteWebhook(YOUR_DOMAIN_NAME, WebhookName.CLICKED);
}
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('PRIVATE_API_KEY', 'https://API_HOSTNAME');
$domain   = 'YOUR_DOMAIN_NAME';
$webhook  = 'delivered';

# Issue the call to the client.
$result = $mgClient->webhooks()->delete($domain, $webhook);
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);
    }

}
import (
    "context"
    "github.com/mailgun/mailgun-go/v3"
    "time"
)

func DeleteWebhook(domain, apiKey string) error {
    mg := mailgun.NewMailgun(domain, apiKey)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
    defer cancel()

    return mg.DeleteWebhook(ctx, "clicked")
}
const DOMAIN = 'YOUR_DOMAIN_NAME';

import formData from 'form-data';
import Mailgun from 'mailgun.js';

const mailgun = new Mailgun(formData);

const client = mailgun.client({ username: 'api', key: 'YOUR_API_KEY' || '' });
(async () => {
  try {
    const deletedWebhook = await client.webhooks.destroy(DOMAIN, 'clicked');
    console.log('deletedWebhook', deletedWebhook);
  } catch (error) {
    console.error(error);
  }
})();

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,
}