Unsubscribes

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.

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 Maximum number of records to return. (100 by default)
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:

def get_unsubscribes
  RestClient.get "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/unsubscribes"
end

Response:

{
  "total_count": 6,
  "items": [
    {
      "created_at": "Wed, 15 Feb 2012 11:21:46 GMT",
      "tag": "*",
      "id": "4f3b954a6addaa3e196735a2",
      "address": "ev@mailgun.net"
    },
    {
      "created_at": "Wed, 15 Feb 2012 11:21:46 GMT",
      "tag": "tag1",
      "id": "4f3b954a6addaa3e1967359f",
      "address": "ev@mailgun.net"
    },
    {
      "created_at": "Wed, 01 Feb 2012 08:09:45 GMT",
      "tag": "Testing Tag",
      "id": "4f28f3494d532a3a823d0d9f",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Wed, 01 Feb 2012 08:09:38 GMT",
      "tag": "*",
      "id": "4f28f1024d532a3a823d0d68",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Sat, 07 Jan 2012 20:13:40 GMT",
      "tag": "*",
      "id": "4f08a7744d532a3a8236b5a4",
      "address": "kunw@cs.washington.edu"
    },
    {
      "created_at": "Sat, 22 Oct 2011 13:04:20 GMT",
      "tag": "*",
      "id": "4ea2bf546c5f6b0f935831de",
      "address": "gino.heyman@gmail.com"
    }
  ]
}

Unsubscribe a recipient from a certain tag:

def unsubscribe_from_tag
  RestClient.post "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/unsubscribes",
  :address => 'ev@mailgun.net',
  :tag => 'tag1'
end

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

Unsubscribe a recipient from all mail sent through this domain:

def unsubscribe_from_all
  RestClient.post "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/unsubscribes",
  :address => 'ev@mailgun.net',
  :tag => '*'
end

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

Fetch the full list of all unsubscribed recipients:

public static ClientResponse GetUnsubscribes() {
       Client client = new Client();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org" +
                               "/unsubscribes");
       return webResource.get(ClientResponse.class);
}

Response:

{
  "total_count": 6,
  "items": [
    {
      "created_at": "Wed, 15 Feb 2012 11:26:34 GMT",
      "tag": "*",
      "id": "4f3b954a6addaa3e196735a2",
      "address": "ev@mailgun.net"
    },
    {
      "created_at": "Wed, 15 Feb 2012 11:26:33 GMT",
      "tag": "tag1",
      "id": "4f3b954a6addaa3e1967359f",
      "address": "ev@mailgun.net"
    },
    {
      "created_at": "Wed, 01 Feb 2012 08:09:45 GMT",
      "tag": "Testing Tag",
      "id": "4f28f3494d532a3a823d0d9f",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Wed, 01 Feb 2012 08:09:38 GMT",
      "tag": "*",
      "id": "4f28f1024d532a3a823d0d68",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Sat, 07 Jan 2012 20:13:40 GMT",
      "tag": "*",
      "id": "4f08a7744d532a3a8236b5a4",
      "address": "kunw@cs.washington.edu"
    },
    {
      "created_at": "Sat, 22 Oct 2011 13:04:20 GMT",
      "tag": "*",
      "id": "4ea2bf546c5f6b0f935831de",
      "address": "gino.heyman@gmail.com"
    }
  ]
}

Unsubscribe a recipient from a certain tag:

public static ClientResponse UnsubscribeFromTag() {
       Client client = new Client();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org" +
                               "/unsubscribes");
       MultivaluedMapImpl formData = new MultivaluedMapImpl();
       formData.add("address", "ev@mailgun.net");
       formData.add("tag", "tag1");
       return webResource.type(MediaType.APPLICATION_FORM_URLENCODED).
               post(ClientResponse.class, formData);
}

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

Unsubscribe a recipient from all mail sent through this domain:

public static ClientResponse UnsubscribeFromAll() {
       Client client = new Client();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org" +
                               "/unsubscribes");
       MultivaluedMapImpl formData = new MultivaluedMapImpl();
       formData.add("address", "ev@mailgun.net");
       formData.add("tag", "*");
       return webResource.type(MediaType.APPLICATION_FORM_URLENCODED).
               post(ClientResponse.class, formData);
}

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

Fetch the full list of all unsubscribed recipients:

function get_unsubscribes() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/'.
                    'unsubscribes',
                    HttpRequest::METH_GET);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->send();
  return $request;
}

Response:

{
  "total_count": 6,
  "items": [
    {
      "created_at": "Wed, 15 Feb 2012 11:42:53 GMT",
      "tag": "*",
      "id": "4f3b954a6addaa3e196735a2",
      "address": "ev@mailgun.net"
    },
    {
      "created_at": "Wed, 15 Feb 2012 11:42:53 GMT",
      "tag": "tag1",
      "id": "4f3b954a6addaa3e1967359f",
      "address": "ev@mailgun.net"
    },
    {
      "created_at": "Wed, 01 Feb 2012 08:09:45 GMT",
      "tag": "Testing Tag",
      "id": "4f28f3494d532a3a823d0d9f",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Wed, 01 Feb 2012 08:09:38 GMT",
      "tag": "*",
      "id": "4f28f1024d532a3a823d0d68",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Sat, 07 Jan 2012 20:13:40 GMT",
      "tag": "*",
      "id": "4f08a7744d532a3a8236b5a4",
      "address": "kunw@cs.washington.edu"
    },
    {
      "created_at": "Sat, 22 Oct 2011 13:04:20 GMT",
      "tag": "*",
      "id": "4ea2bf546c5f6b0f935831de",
      "address": "gino.heyman@gmail.com"
    }
  ]
}

Unsubscribe a recipient from a certain tag:

function unsubscribe_from_tag() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/'.
                    'unsubscribes',
                    HttpRequest::METH_POST);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->setPostFields(array('address' => 'ev@mailgun.net'));
  $request->setPostFields(array('tag' => 'tag1'));
  $request->send();
  return $request;
}

The response:

{
  "message": "'address' parameter is missing"
}

Unsubscribe a recipient from all mail sent through this domain:

function unsubscribe_from_all() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/'.
                    'unsubscribes',
                    HttpRequest::METH_POST);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
    $request->setPostFields(array('address' => 'ev@mailgun.net'));
    $request->setPostFields(array('tag' => '*'));
  $request->send();
  return $request;
}

The response:

{
  "message": "'address' parameter is missing"
}

Fetch the full list of all unsubscribed recipients:

def get_unsubscribes():
    r = requests.\
        get(("https://api.mailgun.net/v2/samples.mailgun.org/"
             "unsubscribes"),
            auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"))
    return r

Response:

{
  "total_count": 4,
  "items": [
    {
      "created_at": "Wed, 01 Feb 2012 08:09:45 GMT",
      "tag": "Testing Tag",
      "id": "4f28f3494d532a3a823d0d9f",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Wed, 01 Feb 2012 08:09:38 GMT",
      "tag": "*",
      "id": "4f28f1024d532a3a823d0d68",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Sat, 07 Jan 2012 20:13:40 GMT",
      "tag": "*",
      "id": "4f08a7744d532a3a8236b5a4",
      "address": "kunw@cs.washington.edu"
    },
    {
      "created_at": "Sat, 22 Oct 2011 13:04:20 GMT",
      "tag": "*",
      "id": "4ea2bf546c5f6b0f935831de",
      "address": "gino.heyman@gmail.com"
    }
  ]
}

Unsubscribe a recipient from a certain tag:

def unsubscribe_from_tag():
    r = requests.\
        post(("https://api.mailgun.net/v2/samples.mailgun.org/"
              "unsubscribes"),
             auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"),
             data={'address':'ev@mailgun.net', 'tag': 'tag1'})
    return r

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

Unsubscribe a recipient from all mail sent through this domain:

def unsubscribe_from_all():
    r = requests.\
        post(("https://api.mailgun.net/v2/samples.mailgun.org/"
              "unsubscribes"),
             auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"),
             data={'address':'ev@mailgun.net', 'tag': '*'})
    return r

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

Fetch the full list of all unsubscribed recipients:

public static RestResponse GetUnsubscribes() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.AddParameter("domain",
                            "samples.mailgun.org", ParameterType.UrlSegment);
       request.Resource = "{domain}/unsubscribes";
       return client.Execute(request);
}

Response:

{
  "total_count": 6,
  "items": [
    {
      "created_at": "Wed, 15 Feb 2012 11:35:59 GMT",
      "tag": "*",
      "id": "4f3b954a6addaa3e196735a2",
      "address": "ev@mailgun.net"
    },
    {
      "created_at": "Wed, 15 Feb 2012 11:35:59 GMT",
      "tag": "tag1",
      "id": "4f3b954a6addaa3e1967359f",
      "address": "ev@mailgun.net"
    },
    {
      "created_at": "Wed, 01 Feb 2012 08:09:45 GMT",
      "tag": "Testing Tag",
      "id": "4f28f3494d532a3a823d0d9f",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Wed, 01 Feb 2012 08:09:38 GMT",
      "tag": "*",
      "id": "4f28f1024d532a3a823d0d68",
      "address": "alex@mailgun.net"
    },
    {
      "created_at": "Sat, 07 Jan 2012 20:13:40 GMT",
      "tag": "*",
      "id": "4f08a7744d532a3a8236b5a4",
      "address": "kunw@cs.washington.edu"
    },
    {
      "created_at": "Sat, 22 Oct 2011 13:04:20 GMT",
      "tag": "*",
      "id": "4ea2bf546c5f6b0f935831de",
      "address": "gino.heyman@gmail.com"
    }
  ]
}

Unsubscribe a recipient from a certain tag:

public static RestResponse UnsubscribeFromTag() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.Resource = "{domain}/unsubscribes";
       request.AddParameter("domain",
                            "samples.mailgun.org", ParameterType.UrlSegment);
       request.AddParameter("address", "ev@mailgun.net");
       request.AddParameter("tag", "tag1");
       request.Method = Method.POST;
       return client.Execute(request);
}

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

Unsubscribe a recipient from all mail sent through this domain:

public static RestResponse UnsubscribeFromAll() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.Resource = "{domain}/unsubscribes";
       request.AddParameter("domain",
                            "samples.mailgun.org", ParameterType.UrlSegment);
       request.AddParameter("address", "ev@mailgun.net");
       request.AddParameter("tag", "*");
       request.Method = Method.POST;
       return client.Execute(request);
}

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

Fetch the full list of all unsubscribed recipients:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 -G \
    https://api.mailgun.net/v2/samples.mailgun.org/unsubscribes

Response:

{
  "total_count": 6,
  "items": [
      {
          "created_at": "Wed, 15 Feb 2012 12:35:51 GMT",
          "tag": "*",
          "id": "4f3b954a6addaa3e196735a2",
          "address": "ev@mailgun.net"
      },
      {
          "created_at": "Wed, 15 Feb 2012 12:35:50 GMT",
          "tag": "tag1",
          "id": "4f3b954a6addaa3e1967359f",
          "address": "ev@mailgun.net"
      },
      {
          "created_at": "Wed, 01 Feb 2012 08:09:45 GMT",
          "tag": "Testing Tag",
          "id": "4f28f3494d532a3a823d0d9f",
          "address": "alex@mailgun.net"
      },
      {
          "created_at": "Wed, 01 Feb 2012 08:09:38 GMT",
          "tag": "*",
          "id": "4f28f1024d532a3a823d0d68",
          "address": "alex@mailgun.net"
      },
      {
          "created_at": "Sat, 07 Jan 2012 20:13:40 GMT",
          "tag": "*",
          "id": "4f08a7744d532a3a8236b5a4",
          "address": "kunw@cs.washington.edu"
      },
      {
          "created_at": "Sat, 22 Oct 2011 13:04:20 GMT",
          "tag": "*",
          "id": "4ea2bf546c5f6b0f935831de",
          "address": "gino.heyman@gmail.com"
      }
  ]
}

Unsubscribe a recipient from a certain tag:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 \
    https://api.mailgun.net/v2/samples.mailgun.org/unsubscribes \
    -F address='ev@mailgun.net' \
    -F tag='tag1'

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

Unsubscribe a recipient from all mail sent through this domain:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 \
    https://api.mailgun.net/v2/samples.mailgun.org/unsubscribes \
    -F address='ev@mailgun.net' \
    -F tag='*'

The response:

{
  "message": "Address has been added to the unsubscribes table",
  "address": "ev@mailgun.net"
}

© Copyright 2011, Mailgun Inc.
Created using Sphinx 1.1.2.
Style for Mailgun Documentation based on ADCtheme Copyright (c) 2009, Corey Oordt.