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 |
|
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."
}