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>

Retrieves 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.mailgun.api.v3.suppression.MailgunSuppressionUnsubscribeApi;
import com.mailgun.model.suppression.unsubscribe.UnsubscribeItemResponse;

// ...

public UnsubscribeItemResponse getUnsubscribes() {
    MailgunSuppressionUnsubscribeApi suppressionUnsubscribeApi = MailgunClient.config(API_KEY)
        .createApi(MailgunSuppressionUnsubscribeApi.class);

    return suppressionUnsubscribeApi.getAllUnsubscribe(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->suppressions()->unsubscribes()->index($domain);

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);
    }

}

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

func ListUnsubscribes(domain, apiKey string) ([]mailgun.Unsubscribe, error) {
    mg := mailgun.NewMailgun(domain, apiKey)
    it := mg.ListUnsubscribes(nil)

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

    var page, result []mailgun.Unsubscribe
    for it.Next(ctx, &page) {
        result = append(result, page...)
    }

    if it.Err() != nil {
        return nil, it.Err()
    }
    return result, nil
}

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 unsubscribes = await client.suppressions.list(DOMAIN, 'unsubscribes');
    console.log('unsubscribes', unsubscribes);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{
  "total_count": 4,
  "items": [
      {
          "created_at": "Thu, 15 Mar 2012 08:35:02 GMT",
          "tags":["*"],
          "id": "4f3b954a6addaa3e196735a2",
          "address": "bob@example.com"
      },
      {
          "created_at": "Thu, 15 Mar 2012 08:35:02 GMT",
          "tags":["tag1"],
          "id": "4f3b954a6addaa3e1967359f",
          "address": "bob@example.com"
      },
      {
          "created_at": "Wed, 01 Feb 2012 08:09:45 GMT",
          "tags":["Testing Tag"],
          "id": "4f28f3494d532a3a823d0d9f",
          "address": "alice@example.com"
      },
      {
          "created_at": "Wed, 01 Feb 2012 08:09:38 GMT",
          "tags":["*", "tag2"],
          "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.mailgun.api.v3.suppression.MailgunSuppressionUnsubscribeApi;
import com.mailgun.model.suppression.SuppressionResponse;
import com.mailgun.model.suppression.unsubscribe.UnsubscribeSingleItemRequest;

import java.time.ZonedDateTime;

// ...

public SuppressionResponse addUnsubscribe() {
    MailgunSuppressionUnsubscribeApi suppressionUnsubscribeApi = MailgunClient.config(API_KEY)
        .createApi(MailgunSuppressionUnsubscribeApi.class);

    UnsubscribeSingleItemRequest unsubscribeSingleItemRequest = UnsubscribeSingleItemRequest.builder()
        .address("bob@example.com")
        .tag("tag1")
        .createdAt(ZonedDateTime.now())
        .build();

    return suppressionUnsubscribeApi.addAddressToUnsubscribeTable(YOUR_DOMAIN_NAME, unsubscribeSingleItemRequest);
}

# 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';
$recipient = 'bob@example.com';
$tag       = 'my_tag';

# Issue the call to the client.
$result = $mgClient->suppressions()->unsubscribes()->create($domain, $recipient, $tag);

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);
    }

}

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

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

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

    return mg.CreateUnsubscribe(ctx, "bob@example.com", "tag1")
}

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 createdUnsubscribe = await client.suppressions.create(DOMAIN, 'unsubscribes', { address: 'bob@example.com', tag: 'tag1' });
         console.log('createdUnsubscribe', createdUnsubscribe);
     } catch (error) {
         console.error(error);
     }
 })();

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.mailgun.api.v3.suppression.MailgunSuppressionUnsubscribeApi;
import com.mailgun.model.suppression.SuppressionResponse;
import com.mailgun.model.suppression.unsubscribe.UnsubscribeSingleItemRequest;

import java.time.ZonedDateTime;

// ...

public SuppressionResponse addUnsubscribeAll() {
    MailgunSuppressionUnsubscribeApi suppressionUnsubscribeApi = MailgunClient.config(API_KEY)
        .createApi(MailgunSuppressionUnsubscribeApi.class);

    UnsubscribeSingleItemRequest unsubscribeSingleItemRequest = UnsubscribeSingleItemRequest.builder()
        .address("bob@example.com")
        .tag("*")
        .createdAt(ZonedDateTime.now())
        .build();

    return suppressionUnsubscribeApi.addAddressToUnsubscribeTable(YOUR_DOMAIN_NAME, unsubscribeSingleItemRequest);
}

# 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';
$recipient = 'bob@example.com';
$tag       = '*';

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

}

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

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

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

    return mg.CreateUnsubscribe(ctx, "bob@example.com", "*")
}

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 createdUnsubscribe = await client.suppressions.create(DOMAIN, 'unsubscribes', { address: 'bob@example.com', tag: '*' });
        console.log('createdUnsubscribe', createdUnsubscribe);
    } catch (error) {
        console.error(error);
    }
})();

Sample response:

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