Mailing Lists

You can programmatically create mailing lists using Mailgun Mailing List API.

The Mailing List API endpoint is available at:

v3/lists

A mailing list is a group of members (recipients) which itself has an email address, like developers@mailgun.net. This address becomes an ID for this mailing list.

When you send a message to developers@mailgun.net, all members of the list will receive a copy of it.

GET /lists/pages

Paginate over mailing lists under your account

Parameter Description
limit Maximum number of records to return (optional: 100 by default)
GET /lists/<address>

Returns a single mailing list by a given address.

POST /lists

Creates a new mailing list.

Parameter Description
address A valid email address for the mailing list, e.g. developers@mailgun.net, or Developers <devs@mg.net>
name Mailing list name, e.g. Developers (optional)
description A description (optional)
access_level List access level, one of: readonly (default), members, everyone
reply_preference Set where replies should go: list (default) | sender (optional)
PUT /lists/<address>

Update mailing list properties, such as address, description or name

Parameter Description
address New mailing list address, e.g. devs@mg.net (optional)
name New name, e.g. My newsletter (optional)
description Description string (optional)
access_level List access level, one of: readonly (default), members, everyone
reply_preference Set where replies should go: list (default) | sender (optional)
DELETE /lists/<address>

Deletes a mailing list.

POST /lists/<address>/validate

Verify all the members of the mailing list.

Note

Our Email Validation service has been renamed to Email Verification service. While the names are different, nothing within our codebase has changed to cause a disruption in service.

GET /lists/<address>/validate

Retrieve current status of the mailing list verification job.

Note

Our Email Validation service has been renamed to Email Verification service. While the names are different, nothing within our codebase has changed to cause a disruption in service.

DELETE /lists/<address>/validate

Cancel an active mailing list verification job.

Note

Our Email Validation service has been renamed to Email Verification service. While the names are different, nothing within our codebase has changed to cause a disruption in service.

GET /lists/<address>/members/pages

Paginate over list members in the given mailing list

Parameter Description
subscribed yes to lists subscribed, no for unsubscribed. list all if not set
limit Maximum number of records to return (optional: 100 by default)
GET /lists/<address>/members/<member_address>

Retrieves a mailing list member.

POST /lists/<address>/members

Adds a member to the mailing list.

Parameter Description
address Valid email address specification, e.g. Alice <alice@example.com> or just alice@example.com
name Optional member name
vars JSON-encoded dictionary string with arbitrary parameters, e.g. {"gender":"female","age":27}
subscribed yes to add as subscribed (default), no as unsubscribed
upsert
yes to update member if present, no to
raise error in case of a duplicate member (default)
PUT /lists/<address>/members/<member_address>

Updates a mailing list member with given properties. Won’t touch the property if it’s not passed in.

Parameter Description
address Valid email address specification, e.g. Alice <alice@example.com> or just alice@example.com
name Recipient name, e.g. Alice
vars JSON-encoded dictionary string with arbitrary parameters, e.g. {"gender":"female","age":27}
subscribed no to set unsubscribed, yes as subscribed
POST /lists/<address>/members.json

Adds multiple members, up to 1,000 per call, to a Mailing List.

Parameter Description
members JSON-encoded array. Elements can be either addresses, e.g. ["bob@example.com", "alice@example.com"], or JSON objects, e.g. [{"address": "bob@example.com", "name": "Bob", "subscribed": false}, {"address": "alice@example.com", "name": "Alice"}] . Custom variables can be provided, see examples. When passing a JSON object subscribed will always be set to true if a value is not passed for it per member.
upsert yes to update existing members, no (default) to ignore duplicates
DELETE /lists/<address>/members/<member_address>

Delete a mailing list member.

Access Levels

Mailing lists have three different access levels. These levels define how users can interact with the list.

Access Level Description
read-only Only authenticated users can post to this list. It is used for mass announcements and newsletters. This is the default access level.
members Subscribed members of the list can communicate with each other.
everyone Everyone can post to this list. Recommended turning spam filtering on when using this mode.

Examples

Create a mailing list:

curl -s --user 'api:YOUR_API_KEY' \
   https://api.mailgun.net/v3/lists \
   -F address='LIST@YOUR_DOMAIN_NAME' \
   -F description='Mailgun developers list'
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.enums.AccessLevel;
import com.mailgun.enums.ReplyPreference;
import com.mailgun.model.mailing.lists.MailingListRequest;
import com.mailgun.model.mailing.lists.MailingListResponse;

// ...

public MailingListResponse createMailingList() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    MailingListRequest mailingListRequest = MailingListRequest.builder()
        .address( "LIST@YOUR_DOMAIN_NAME")
        .name("LIST_NAME")
        .description("LIST_DESCRIPTION")
        .accessLevel(AccessLevel.EVERYONE)
        .replyPreference(ReplyPreference.LIST)
        .build();

    return mailgunMailingListApi.createMailingList(mailingListRequest);
}
# 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');
$mailing_list     = 'LIST@YOUR_DOMAIN_NAME';
$list_name        = 'Mailgun Subscribers';
$list_description = 'News and service updates';
$access_level     = 'readonly';

# Issue the call to the client.
$result = $mgClient->mailingList()->create($mailing_list, $list_name, $list_description, $access_level);
def create_mailing_list():
    return requests.post(
        "https://api.mailgun.net/v3/lists",
        auth=('api', 'YOUR_API_KEY'),
        data={'address': 'LIST@YOUR_DOMAIN_NAME',
              'description': "Mailgun developers list"})
def create_mailing_list
  RestClient.post("https://api:YOUR_API_KEY" \
                  "@api.mailgun.net/v3/lists",
                  :address => 'LIST@YOUR_DOMAIN_NAME',
                  :description => "Mailgun developers list")
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class CreateMailingListChunk
{

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

    public static IRestResponse CreateMailingList ()
    {

        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 = "lists";
        request.AddParameter ("address", "LIST@YOUR_DOMAIN_NAME");
        request.AddParameter ("description", "Mailgun developers list");
        request.Method = Method.POST;
        return client.Execute (request);
    }

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

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

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

    return mg.CreateMailingList(ctx, mailgun.MailingList{
        Address:     "list@example.com",
        Name:        "dev",
        Description: "Mailgun developers list.",
        AccessLevel: mailgun.AccessLevelMembers,
    })
}
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 newList = await client.lists.create({
      address: "list_name@${DOMAIN}",
      name: "list_name",
      description: "list_description",
      access_level: "everyone", // readonly (default), members, everyone
    });
    console.log('newList', newList);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{
  "message": "Mailing list has been created",
  "list": {
      "created_at": "Tue, 06 Mar 2012 05:44:45 GMT",
      "address": "dev@samples.mailgun.org",
      "members_count": 0,
      "description": "Mailgun developers list",
      "name": ""
  }
}

Get a page of mailing lists:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/lists/pages
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.model.mailing.lists.MailingListDataResponse;

// ...

public MailingListDataResponse mailingLists() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    return mailgunMailingListApi.getMailingList();
}
# 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');

# Issue the call to the client.
$response = $mgClient->mailingList()->pages();
def list_members():
    return requests.get(
        "https://api.mailgun.net/v3/lists/pages",
        auth=('api', 'YOUR_API_KEY'))
def list_members
  RestClient.get("https://api:YOUR_API_KEY" \
                 "@api.mailgun.net/v3/lists/pages")
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetMailingListsChunk
{

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

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

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

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

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

    var page, result []mailgun.MailingList
    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 listsArray = await client.lists.list();
    console.log('lists', listsArray);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{
  "items": [
    {
      "access_level": "everyone",
      "address": "dev@samples.mailgun.org",
      "created_at": "Tue, 06 Mar 2012 05:44:45 GMT",
      "description": "Mailgun developers list",
      "members_count": 1,
      "name": ""
    },
    {
      "access_level": "readonly",
      "address": "bar@example.com",
      "created_at": "Wed, 06 Mar 2013 11:39:51 GMT",
      "description": "",
      "members_count": 2,
      "name": ""
    }
  ],
  "paging": {
    "first": "https://url_to_next_page",
    "last": "https://url_to_last_page",
    "next": "https://url_to_next_page",
    "previous": "https://url_to_previous_page"
  }
}

Add a mailing list member:

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members \
    -F subscribed=True \
    -F address='bar@example.com' \
    -F name='Bob Bar' \
    -F description='Developer' \
    -F vars='{"age": 26}'
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.model.mailing.lists.MailingListMemberResponse;
import com.mailgun.model.mailing.lists.MailingListNewMemberRequest;

import java.util.Map;

// ...

public MailingListMemberResponse addListMember() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    Map<String, Object> vars = vars = Map.of("age", "26");

    MailingListNewMemberRequest request = MailingListNewMemberRequest.builder()
        .address("bob@example.com")
        .name("Bob Bar")
        .vars(vars)
        .subscribed(true)
        .build();

    return mailgunMailingListApi.addMemberToMailingList(MAILING_LIST_ADDRESS, 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');
$mailing_list = 'LIST@YOUR_DOMAIN_NAME';
$address ='bob@example.com';
$name = 'Bob';
$vars = array("id" => "123456");

# Issue the call to the client.
$result = $mgClient->mailingList()->member()->create(
                                                  $mailing_list,
                                                  $address,
                                                  $name,
                                                  $vars);
def add_list_member():
    return requests.post(
        "https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members",
        auth=('api', 'YOUR_API_KEY'),
        data={'subscribed': True,
              'address': 'bar@example.com',
              'name': 'Bob Bar',
              'description': 'Developer',
              'vars': '{"age": 26}'})
def add_list_member
  RestClient.post("https://api:YOUR_API_KEY" \
                  "@api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members",
                  :subscribed => true,
                  :address => 'bar@example.com',
                  :name => 'Bob Bar',
                  :description => 'Developer',
                  :vars => '{"age": 26}')
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class AddListMemberChunk
{

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

    public static IRestResponse AddListMember ()
    {
        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 = "lists/{list}/members";
        request.AddParameter ("list", "LIST@YOUR_DOMAIN_NAME",
                              ParameterType.UrlSegment);
        request.AddParameter ("address", "bar@example.com");
        request.AddParameter ("subscribed", true);
        request.AddParameter ("name", "Bob Bar");
        request.AddParameter ("description", "Developer");
        request.AddParameter ("vars", "{\"age\": 26}");
        request.Method = Method.POST;
        return client.Execute (request);
    }

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

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

    memberJoe := mailgun.Member{
        Address:    "joe@example.com",
        Name:       "Joe Example",
        Subscribed: mailgun.Subscribed,
    }

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

    return mg.CreateMember(ctx, true, "mailingList@example.com", memberJoe)
}
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 newMember = await client.lists.members.createMember(DOMAIN,
      {
          address: 'bob@example.com',
          name: 'Bob Barr',
          vars: JSON.stringify({age: 27}),
          subscribed: 'yes',
          upsert: 'yes'
      }
    );
    console.log('newMember', newMember);
  } catch (error) {
      console.error(error);
  }
})();

Sample response:

{
  "member": {
      "vars": {
          "age": 26
      },
      "name": "Bob Bar",
      "subscribed": true,
      "address": "bar@example.com"
  },
  "message": "Mailing list member has been created"
}

Add multiple mailing list members (limit 1,000 per call):

curl -s --user 'api:YOUR_API_KEY' \
   https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members.json \
   -F upsert=true \
   -F members='[{"address": "Alice <alice@example.com>", "vars": {"age": 26}},{"name": "Bob", "address": "bob@example.com", "vars": {"age": 34}}]'
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.model.mailing.lists.AddMailingListMembersRequest;
import com.mailgun.model.mailing.lists.MailingListMember;
import com.mailgun.model.mailing.lists.MailingListResponse;

import java.util.List;
import java.util.Map;

// ...

public MailingListResponse addListMembers() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    Map<String, Object> aliceVars = Map.of("age", 26);

    MailingListMember alice = MailingListMember.builder()
        .address("Alice <alice@example.com>")
        .name("Alice")
        .vars(aliceVars)
        .subscribed(true)
        .build();

    Map<String, Object> bobVars = Map.of(
            "gender", "male",
            "age", 1,
            "name", "Bob"
    );

    MailingListMember bob = MailingListMember.builder()
        .address("bob@example.com")
        .name("Bob")
        .vars(bobVars)
        .subscribed(true)
        .build();

    AddMailingListMembersRequest request = AddMailingListMembersRequest.builder()
        .members(List.of(alice, bob))
        .upsert(true)
        .build();

    return mailgunMailingListApi.addMembersToMailingList(MAILING_LIST_ADDRESS, 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');
$mailing_list = 'LIST@YOUR_DOMAIN_NAME';
$members = array(
    array(
        'address'   => 'bob@example.com',
        'name'      => 'Bob',
        'vars'      => array("id" => "123456")
    )
);

# Issue the call to the client.
$result = $mgClient->mailingList()->member()->createMultiple($mailing_list, $members);
def add_list_member():
    return requests.post(
        "https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members.json",
        auth=('api', 'YOUR_API_KEY'),
        data={'upsert': True,
              'members': '[{"address": "Alice <alice@example.com>", "vars": {"age": 26}},{"name": "Bob", "address": "bob@example.com", "vars": {"age": 34}}]')
def add_list_member
  RestClient.post("https://api:YOUR_API_KEY" \
                  "@api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members.json",
                  :upsert => true,
                  :members => '[{"address": "Alice <alice@example.com>", "vars": {"age": 26}},{"name": "Bob", "address": "bob@example.com", "vars": {"age": 34}}]')
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class AddListMembersChunk
{

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

    public static IRestResponse AddListMembers ()
    {
        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 = "lists/{list}/members.json";
        request.AddParameter ("list", "LIST@YOUR_DOMAIN_NAME",
                              ParameterType.UrlSegment);
        request.AddParameter ("members",
                              "[{\"address\":\"Alice<alice@example.com>\",\"vars\":{\"age\":26}},{\"name\":\"Bob\",\"address\":\"bob@example.com\",\"vars\":{\"age\":34}}]");
        request.AddParameter ("upsert", true);
        request.Method = Method.POST;
        return client.Execute (request);
    }

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

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

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

    return mg.CreateMemberList(ctx, nil, "mailgunList@example.com", []interface{}{
        mailgun.Member{
            Address:    "alice@example.com",
            Name:       "Alice's debugging account",
            Subscribed: mailgun.Unsubscribed,
        },
        mailgun.Member{
            Address:    "Bob Cool <bob@example.com>",
            Name:       "Bob's Cool Account",
            Subscribed: mailgun.Subscribed,
        },
        mailgun.Member{
            Address: "joe.hamradio@example.com",
            // Charlette is a ham radio packet BBS user.
            // We attach her packet BBS e-mail address as an arbitrary var here.
            Vars: map[string]interface{}{
                "packet-email": "KW9ABC @ BOGUS-4.#NCA.CA.USA.NOAM",
            },
        },
    })
}
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 newMembersList = [
      {
      address: 'bob@example.com',
      name: 'Bob Barr',
      vars: JSON.stringify({ age: 27 }),
      subscribed: 'yes',
      upsert: 'yes'
      },
      {
      address: 'Alice <alice@example.com>',
      name: 'Alice Barr',
      vars: JSON.stringify({ age: 27 }),
      subscribed: 'yes',
      upsert: 'yes'
      },
    ];

    const newMembers = await client.lists.members.createMembers(
      DOMAIN,
      {
      members: newMembersList,
      upsert: 'yes'
      }
    );
    console.log('newMembers', newMembers);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{
  "message": "Mailing list has been updated",
  "list": {
    "members_count": 7,
    "description": "My updated test mailing list",
    "created_at": "Wed, 06 Mar 2013 11:39:51 GMT",
    "access_level": "readonly",
    "address": "dev@samples.mailgun.org",
    "name": "Test List Updated"
  }
}

You can also update an existing member:

curl -s --user 'api:YOUR_API_KEY' -X PUT \
    https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members/bar@example.com \
    -F subscribed=False \
    -F name='Foo Bar'
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.model.mailing.lists.MailingListMemberResponse;
import com.mailgun.model.mailing.lists.MailingListMemberUpdateRequest;

import java.util.Map;

// ...

public MailingListMemberResponse updateMembers() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    MailingListMemberUpdateRequest request = MailingListMemberUpdateRequest.builder()
        .name("Alice")
        .vars(Map.of("age", "26"))
        .subscribed(false)
        .build();

    return mailgunMailingListApi.updateMailingListMember(MAILING_LIST_ADDRESS, "alice@example.com", 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');
$mailing_list = 'LIST@YOUR_DOMAIN_NAME';
$recipient    = 'bob@example.com';
$params = array(
    'name'      => 'Bob',
    'subscribed => 'yes',
    'vars'      => '{"age": 30, "pet": "cat"}'
);

# Issue the call to the client.
$result = $mgClient->mailingList()->member()->update($mailing_list, $recipient, $params);
def update_member():
    return requests.put(
        ("https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members"
         "/bar@example.com"),
        auth=('api', 'YOUR_API_KEY'),
        data={'subscribed': False,
              'name': 'Foo Bar'})
def update_member
  RestClient.put("https://api:YOUR_API_KEY" \
                 "@api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members" \
                 "/bar@example.com",
                 :subscribed => false,
                 :name => 'Foo Bar')
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class UpdateListMemberChunk
{

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

    public static IRestResponse UpdateListMember ()
    {
        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 = "lists/{list}/members/{member}";
        request.AddParameter ("list", "LIST@YOUR_DOMAIN_NAME",
                              ParameterType.UrlSegment);
        request.AddParameter ("member", "bar@example.com",
                              ParameterType.UrlSegment);
        request.AddParameter ("subscribed", false);
        request.AddParameter ("name", "Foo Bar");
        request.Method = Method.PUT;
        return client.Execute (request);
    }

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

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

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

    _, err := mg.UpdateMember(ctx, "bar@example.com", "list@example.com", mailgun.Member{
        Name: "Foo Bar",
        Subscribed: mailgun.Unsubscribed,
    })
    return err
}
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 updatedMember = await client.lists.members.updateMember(`mylist@${DOMAIN}`, 'bob@example.com',
        {
            subscribed: 'yes'
        }
    );
    console.log('updatedMember', updatedMember);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{
  "member": {
      "vars": {
          "age": 26
      },
      "name": "Foo Bar",
      "subscribed": false,
      "address": "bar@example.com"
  },
  "message": "Mailing list member has been updated"
}

Listing members:

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members/pages
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.model.mailing.lists.MailingListMembersResponse;

// ...

public MailingListMembersResponse listMembers() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    return mailgunMailingListApi.getMailingListMembers(MAILING_LIST_ADDRESS);
}
# 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');
$mailing_list = 'LIST@YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result =  $mgClient->mailingList()->member()->index($mailing_list);
def list_members():
    return requests.get(
        "https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members/pages",
        auth=('api', 'YOUR_API_KEY'))
def list_members
  RestClient.get("https://api:YOUR_API_KEY" \
                 "@api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members/pages")
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetListMembersChunk
{

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

    public static IRestResponse GetListMembers ()
    {
        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 = "lists/{list}/members/pages";
        request.AddParameter ("list", "LIST@YOUR_DOMAIN_NAME",
                              ParameterType.UrlSegment);
        return client.Execute (request);
    }

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

func GetMembers(domain, apiKey string) ([]mailgun.Member, error) {
    mg := mailgun.NewMailgun(domain, apiKey)
    it := mg.ListMembers("list@example.com", nil)

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

    var page, result []mailgun.Member
    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 listingMembers = await client.lists.members.listMembers(DOMAIN);
    console.log('listingMembers', listingMembers);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{
  "items": [
      {
          "vars": {
              "age": 26
          },
          "name": "Foo Bar",
          "subscribed": false,
          "address": "bar@example.com"
      }
  ],
  "paging": {
    "first": "https://url_to_first_page",
    "last": "https://url_to_last_page",
    "next": "http://url_to_next_page",
    "previous": "http://url_to_previous_page"
  }
}

Remove a member:

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members/bar@example.com
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.model.mailing.lists.MailingListMemberResponse;

// ...

public MailingListMemberResponse removeMembers() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    return mailgunMailingListApi.deleteMemberFromMailingList(MAILING_LIST_ADDRESS, "karen@example.com");
}
# 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');
$mailing_list = 'LIST@YOUR_DOMAIN_NAME';
$recipient    = 'bob@example.com';

# Issue the call to the client.
$result = $mgClient->mailingList()->member()->delete($mailing_list, $recipient);
def remove_member():
    return requests.delete(
        ("https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members"
         "/bar@example.com"),
        auth=('api', 'YOUR_API_KEY'))
def remove_member
  RestClient.delete("https://api:YOUR_API_KEY" \
                    "@api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members" \
                    "/bar@example.com")
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class RemoveListMemberChunk
{

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

    public static IRestResponse RemoveListMember ()
    {
        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 = "lists/{list}/members/{member}";
        request.AddParameter ("list", "LIST@YOUR_DOMAIN_NAME",
                              ParameterType.UrlSegment);
        request.AddParameter ("member", "bar@example.com",
                              ParameterType.UrlSegment);
        request.Method = Method.DELETE;
        return client.Execute (request);
    }

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

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

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

    return mg.DeleteMember(ctx, "joe@example.com", "list@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 deletedMember = await client.lists.members.destroyMember(DOMAIN, 'bob@example.com');
    console.log('deletedMember', deletedMember);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{
  "member": {
      "address": "bar@example.com"
  },
  "message": "Mailing list member has been deleted"
}

Remove mailing list:

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.model.mailing.lists.DeleteMailingListResponse;

// ...

public DeleteMailingListResponse removeMailingList() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    return mailgunMailingListApi.deleteMailingList(MAILING_LIST_ADDRESS);
}
# 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');
$mailing_list = 'LIST@YOUR_DOMAIN_NAME';

# Issue the call to the client.
$result = $mgClient->mailingList()->delete($mailing_list);
def remove_list():
    return requests.delete(
        "https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME",
        auth=('api', 'YOUR_API_KEY'))
def remove_list
  RestClient.delete("https://api:YOUR_API_KEY" \
                    "@api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME")
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class RemoveMailingListChunk
{

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

    public static IRestResponse RemoveMailingList ()
    {
        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 = "lists/{list}";
        request.AddParameter ("list", "LIST@YOUR_DOMAIN_NAME",
                              ParameterType.UrlSegment);
        request.Method = Method.DELETE;
        return client.Execute (request);
    }

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

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

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

    return mg.DeleteMailingList(ctx, "list@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 removedList = await client.lists.destroy('YOUR_LIST_NAME');
    console.log('removedList', removedList);
  } catch (error) {
    console.error(error);
  }
})();

Sample response:

{
  "message": "Mailing list has been deleted",
  "address": "dev@samples.mailgun.org"
}

Run mailing list verification:

Note

Our Email Validation service has been renamed to Email Verification service. While the names are different, nothing within our codebase has changed to cause a disruption in service.

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate \
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.model.mailing.lists.MailingListVerificationRespo

// ...

public MailingListVerificationResponse validateMailingList() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    return mailgunMailingListApi.verifyMailingListMembers(MAILING_LIST_ADDRESS);
}
# Currently, the PHP SDK does not support Mailing List verifications.
# Consider using the following php curl function.
function upload_bulk_validation() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate');

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def validate_mailing_list():
    return requests.post(
        "https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate",
        auth=('api', 'YOUR_API_KEY'))
def validate_mailing_list
  RestClient.post("https://api:YOUR_API_KEY" \
                  "@api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate")
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class ValidateMailingListChunk
{

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

    public static IRestResponse ValidateMailingList ()
    {
        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 = "lists/{list}/validate";
        request.AddParameter ("list", "LIST@YOUR_DOMAIN_NAME",
                              ParameterType.UrlSegment);
        request.Method = Method.POST;
        return client.Execute (request);
    }

}

Sample response:

{
    "id": "listname@yourdomain.com",
    "message": "The validation job was submitted."
}

Get mailing list verification status:

Note

Our Email Validation service has been renamed to Email Verification service. While the names are different, nothing within our codebase has changed to cause a disruption in service.

curl -s --user 'api:YOUR_API_KEY' -G \
    https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME
import com.mailgun.api.v3.MailgunMailingListApi;
import com.mailgun.model.mailing.lists.MailingListVerificationStatusResponse;

// ...

public MailingListVerificationStatusResponse getMailingListValidation() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    return mailgunMailingListApi.getMailingListVerificationJobStatus(MAILING_LIST_ADDRESS);
}
# Currently, the PHP SDK does not support Mailing List verifications.
# Consider using the following php curl function.
function get_mailing_list_validation() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate');

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def get_mailing_list_validation_status():
    return requests.get(
        "https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate",
        auth=('api', 'YOUR_API_KEY'))
def get_mailing_list_validation_status
  RestClient.get("https://api:YOUR_API_KEY"\
                 "@api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate"\
                 {|response, request, result| response }
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class GetMailingListValidationChunk
{

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

    public static IRestResponse GetMailingListValidation ()
    {
        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 ("list", "LIST@YOUR_DOMAIN_NAME", ParameterType.UrlSegment);
        request.Resource = "/lists/{list}/validate";
        return client.Execute (request);
    }

}

Sample response:

{
  "created_at": "Tue, 26 Feb 2019 21:30:03 GMT",
  "download_url": {
    "csv": "<download_link>",
    "json": "<download_link>"
  },
  "id": "listname@mydomain.sandbox.mailgun.org",
  "quantity": 207665,
  "records_processed": 207665,
  "status": "uploaded",
  "summary": {
    "result": {
      "deliverable": 184199,
      "do_not_send": 5647,
      "undeliverable": 12116,
      "unknown": 5613
    },
    "risk": {
      "high": 17763,
      "low": 142547,
      "medium": 41652,
      "unknown": 5613
    }
  }
}

Field Explanation:

Parameter Type Description
created_at string Date/Time that the request was initiated
download_url array csv and json representation of the download link for the results of the list verification
id string list name given when the list was initially created
quantity integer number of total items in the list to be verified
records_processed integer de-duplicated total of verified email addresses
status string current state of the list verification request
summary array nested count results for deliverable, do_not_send, undeliverable and unknown statuses
risk array nested count results for high, low, medium or unknown risk assessment results

Cancel mailing list verification:

Note

Our Email Validation service has been renamed to Email Verification service. While the names are different, nothing within our codebase has changed to cause a disruption in service.

curl -s --user 'api:YOUR_API_KEY' -X DELETE \
    https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/members/bar@example.com
import com.mailgun.api.v3.MailgunMailingListApi;

// ...

public String cancelMailingListValidation() {
    MailgunMailingListApi mailgunMailingListApi = MailgunClient.config(API_KEY)
        .createApi(MailgunMailingListApi.class);

    return mailgunMailingListApi.cancelActiveMailingListVerificationJob(MAILING_LIST_ADDRESS);
}
# Currently, the PHP SDK does not support Mailing List verifications.
# Consider using the following php curl function.
function delete_mailing_list_validation() {
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:PRIVATE_API_KEY');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate');

  $result = curl_exec($ch);
  curl_close($ch);

  return $result;
}
def cancel_mailing_list_validation():
    return requests.delete(
        ("https://api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate"),
        auth=('api', 'YOUR_API_KEY'))
def cancel_mailing_list_validation
  RestClient.delete("https://api:YOUR_API_KEY" \
                    "@api.mailgun.net/v3/lists/LIST@YOUR_DOMAIN_NAME/validate" \
                    "/bar@example.com")
end
using System;
using System.IO;
using RestSharp;
using RestSharp.Authenticators;

public class DeleteMailingListValidationChunk
{

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

    public static IRestResponse CancelMailingListValidation()
    {
        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 = "lists/{list}/validate}";
        request.AddParameter ("list", "LIST@YOUR_DOMAIN_NAME",
                              ParameterType.UrlSegment);
        request.Method = Method.DELETE;
        return client.Execute (request);
    }

}

Sample response:

{
    "message": "Validation job canceled."
}