Unsubscribes

Mailgun allows you to quickly add “Unsubscribe me” feature to your outgoing emails without any programming on your end. You can enable this in your Control Panel under your domain settings.

Mailgun can notify your application every time a user unsubscribes.

This API allows you to programmatically download the list of recipients who have unsubscribed from your emails. You can also programmatically “clear” the unsubscribe event.

GET /<domain>/unsubscribes

Fetches the list of unsubscribes.

Parameter Description
limit Number of records to return. (100 max)
skip Number of records to skip. (0 by default)
GET /<domain>/unsubscribes/<address>

Retreives a single unsubscribe record. Can be used to check if a given address is present in the list of unsubscribed users.

DELETE /<domain>/unsubscribes/<address or id>

Removes an address from the unsubscribes table. Address defines which events to delete. can be one of two things:

  • an email address: all unsubscribe events for that email address will be removed.
  • id string: deletes a specific event.
POST /<domain>/unsubscribes

Adds address to unsubscribed table.

Parameter Description
address Valid email address
tag Tag to unsubscribe from, use * to unsubscribe address from domain

Examples

Fetch the full list of all unsubscribed recipients:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes
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 getUnsubscribes() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.get("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/unsubscribes")
            .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/unsubscribes", array(
    'limit' => 5,
    'skip' => 10
));
def get_unsubscribes():
    return requests.get(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes",
        auth=("api", "YOUR_API_KEY"))
def get_unsubscribes
  RestClient.get "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes"
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetUnsubscribesChunk
{

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

    public static IRestResponse GetUnsubscribes ()
    {
        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 = "{domain}/unsubscribes";
        return client.Execute (request);
    }

}
func GetUnsubscribes(domain, apiKey string) (int, []mailgun.Unsubscribe, error) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.GetUnsubscribes(-1, -1)
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

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

Sample response:

{
  "total_count": 4,
  "items": [
      {
          "created_at": "Thu, 15 Mar 2012 08:35:02 GMT",
          "tag": "*",
          "id": "4f3b954a6addaa3e196735a2",
          "address": "bob@example.com"
      },
      {
          "created_at": "Thu, 15 Mar 2012 08:35:02 GMT",
          "tag": "tag1",
          "id": "4f3b954a6addaa3e1967359f",
          "address": "bob@example.com"
      },
      {
          "created_at": "Wed, 01 Feb 2012 08:09:45 GMT",
          "tag": "Testing Tag",
          "id": "4f28f3494d532a3a823d0d9f",
          "address": "alice@example.com"
      },
      {
          "created_at": "Wed, 01 Feb 2012 08:09:38 GMT",
          "tag": "*",
          "id": "4f28f1024d532a3a823d0d68",
          "address": "alice@example.com"
      }
  ]
}

Unsubscribe a recipient from a certain tag:

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes \
    -F address='bob@example.com' \
    -F tag='tag1'
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 addUnsubscribe() throws UnirestException {

               HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/unsubscribes")
                       .basicAuth("api", API_KEY)
                       .field("address", "bob@example.com")
                       .field("tag", "tag1")
                       .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("$domain/unsubscribes", array(
    'address' => 'bob@example.com',
    'tag'     => 'myexampletag'
));
def unsubscribe_from_tag():
    return requests.post(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes",
        auth=("api", "YOUR_API_KEY"),
        data={'address':'bob@example.com', 'tag': 'tag1'})
def unsubscribe_from_tag
  RestClient.post "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes",
  :address => 'bob@example.com',
  :tag => 'tag1'
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class AddUnsubscribeTagChunk
{

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

    public static IRestResponse UnsubscribeFromTag ()
    {
        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 = "{domain}/unsubscribes";
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.AddParameter ("address", "bob@example.com");
        request.AddParameter ("tag", "tag1");
        request.Method = Method.POST;
        return client.Execute (request);
    }

}
func CreateUnsubscriptionWithTag(domain, apiKey string) error {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.Unsubscribe("bob@example.com", "tag1")
}
var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.post(`/${DOMAIN}/unsubscribes`, {"address": 'bob@example.com', "tag":'tag1'}, function (error, body) {
  console.log(body);
});

Sample response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "bob@example.com"
}

Unsubscribe a recipient from all mail sent through this domain:

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes \
    -F address='bob@example.com' \
    -F tag='*'
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 addUnsubscribeAll() throws UnirestException {

        HttpResponse <JsonNode> request = Unirest.post("https://api.mailgun.net/v3/" + YOUR_DOMAIN_NAME + "/unsubscribes")
                       .basicAuth("api", API_KEY)
                       .field("address", "bob@example.com")
                   .field("tag", "*")
                   .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("$domain/unsubscribes", array(
    'address' => 'bob@example.com',
    'tag'     => '*'
));
def unsubscribe_from_all():
    return requests.post(
        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes",
        auth=("api", "YOUR_API_KEY"),
        data={'address':'bob@example.com', 'tag': '*'})
def unsubscribe_from_all
  RestClient.post "https://api:YOUR_API_KEY"\
  "@api.mailgun.net/v3/YOUR_DOMAIN_NAME/unsubscribes",
  :address => 'bob@example.com',
  :tag => '*'
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class AddUnsubscribeAllChunk
{

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

    public static IRestResponse UnsubscribeFromAll ()
    {
        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 = "{domain}/unsubscribes";
        request.AddParameter ("domain", "YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.AddParameter ("address", "bob@example.com");
        request.AddParameter ("tag", "*");
        request.Method = Method.POST;
        return client.Execute (request);
    }

}
func CreateUnsubscription(domain, apiKey string) {
  mg := mailgun.NewMailgun(domain, apiKey, "")
  return mg.Unsubscribe("bob@example.com", "*")
}

.. code-block:: node

var DOMAIN = 'YOUR_DOMAIN_NAME';
var mailgun = require('mailgun-js')({ apiKey: "YOUR_API_KEY", domain: DOMAIN });

mailgun.post(`/${DOMAIN}/unsubscribes`, {"address": 'bob@example.com', "tag":'*'}, function (error, body) {
  console.log(body);
});

Sample response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "bob@example.com"
}