Mailing Lists

Programatically create mailing lists.

Create a mailing list

post/v3/lists

Adds a mailing list to the account.

SecuritybasicAuth

Request

Request Body schema: multipart/form-data

address required	string A valid email address for the mailing list, e.g. developers@mailgun.net, or Developers devs@mg.net
name	string Mailing list name, e.g. Developers
description	string A description
access_level	string List access level, one of: readonly, members, everyone. Defaults to readonly
reply_preference	string Set where replies should go: list or sender. Defaults to list

Responses

201

Mailing list creation success

Response Schema: application/json

object

address	string
name	string
description	string
access_level	string
reply_preference	string
created_at	string
members_count	integer

400

Bad Request

Request samples

multipart/form-data

{
  "address": "developers@mailgun.net",
  "name": "Developers",
  "description": "Describe the mailing list",
  "access_level": "readonly",
  "reply_preference": "list"
}

Response samples

201
400

application/json

{"list": {"address": "developers@mailgun.net",
"name": "Developers",
"description": "Describe the mailing list",
"access_level": "readonly",
"reply_preference": "list",
"created_at": "Tue, 09 Aug 2011 20:50:27 -0000",
"members_count": 2
},
"message": "Mailing list has been created"
}

Get mailing lists

get/v3/lists

A mailing list is a group of members (recipients) which itself has an email address. This address becomes an ID for this mailing list.

SecuritybasicAuth

Request

query Parameters

limit	string Set limit for the list length returned. Defaults to 100.
skip	string Skip the first n values in the list. Defaults to 0.
address	string Filter mailing lists matching a specific address

Responses

200

OK

Response Schema: application/json

total_count	integer
	Array of objects

Request samples

Response samples

200

application/json

{"total_count": 1,
"items": [{"address": "developers@mailgun.net",
"name": "Developers",
"description": "Describe the mailing list",
"access_level": "readonly",
"reply_preference": "list",
"created_at": "Tue, 09 Aug 2011 20:50:27 -0000",
"members_count": 2
}
]
}

Get mailing lists members

get/v3/lists/{list_address}/members

Lists members in a given mailing list

SecuritybasicAuth

Request

path Parameters

list_address

required

string

The mailing list's address

query Parameters

address	string A valid email address specification.
subscribed	boolean Filtering list on whether the member is subscribed or not.
limit	integer Maximum number of records to return. Max is 100. Defaults to 100.
skip	integer

Responses

200

OK

Response Schema: application/json

total_count	integer
	Array of objects

Request samples

Response samples

200

application/json

{"total_count": 1,
"items": [{"address": "alice@example.com",
"name": "Alice",
"vars": {"gender": "female",
"age": 27
},
"subscribed": true
}
]
}

Create a mailing list member

post/v3/lists/{list_address}/members

Adds a new member to the mailing list.

SecuritybasicAuth

Request

path Parameters

list_address

required

string

The mailing list's address

Request Body schema: multipart/form-data

address	string Valid email address specification.
name	string An optional member name.
vars	object JSON-encoded dictionary string with arbitrary parameters.
subscribed	boolean Set the member as subscribed or not. Defaults to true.
upsert	boolean Set to True to update member if present, False to raise error in case of a duplicate member. Defaults to false.

Responses

200

OK

Response Schema: application/json

	object
message	string

400

Bad Request

Request samples

multipart/form-data

{
  "address": "alice@example.com",
  "name": "Alice",
  "vars": {
    "gender": "female",
    "age": 27
  },
  "subscribed": true,
  "upsert": true
}

Response samples

200
400

application/json

{"member": {"address": "alice@example.com",
"name": "Alice",
"vars": {"gender": "female",
"age": 27
},
"subscribed": true
},
"message": "Mailing list member has been created"
}

Bulk upload members to a mailing list (JSON)

post/v3/lists/{list_address}/members.json

Adds multiple members, up to 1000 per call, to a mailing list, using JSON array format. If the request includes more than 100 entries, the mailing list will be updated asynchronously.

SecuritybasicAuth

Request

path Parameters

list_address

required

string

The mailing list's address

query Parameters

required	string or Array of Mailing list member (objects) Mailing list recipients in JSON array format. Can be, either, an array of string addresses or an array of ListMemberRequest JSON objects.
upsert	boolean If true, an existing member will be updated. Defaults to false.

Responses

200

OK

Response Schema: application/json

	object
task-id	string
message	string

404

Not Found

Request samples

Response samples

200
404

application/json

{"list": {"address": "developers@mailgun.net",
"name": "Developers",
"description": "Describe the mailing list",
"access_level": "readonly",
"reply_preference": "list",
"created_at": "Tue, 09 Aug 2011 20:50:27 -0000",
"members_count": 2
},
"task-id": "4321",
"message": "Mailing list upload started in background"
}

Bulk upload members to a mailing list (CSV)

post/v3/lists/{list_address}/members.csv

Adds multiple members, up to 1000 per call, to a mailing list via CSV file.

SecuritybasicAuth

Request

path Parameters

list_address

required

string

The mailing list's address

Request Body schema: multipart/form-data

subscribed	boolean
upsert	boolean
members	string Absolute path to the CSV file

Responses

200

OK

Response Schema: application/json

	object
task-id	string
message	string

400

Bad Request

404

Not Found

Request samples

multipart/form-data

{
  "upsert": true,
  "members": "absolute/path/to/file/members.csv"
}

Response samples

200
400
404

application/json

{"list": {"address": "developers@mailgun.net",
"name": "Developers",
"description": "Describe the mailing list",
"access_level": "readonly",
"reply_preference": "list",
"created_at": "Tue, 09 Aug 2011 20:50:27 -0000",
"members_count": 2
},
"task-id": "4321",
"message": "Mailing list upload started in background"
}

Get a member

get/v3/lists/{list_address}/members/{member_address}

Get details about a specific mailing list member

SecuritybasicAuth

Request

path Parameters

list_address required	string The mailing list's address
member_address required	string The member's address

Responses

200

OK

Response Schema: application/json

address	string
name	string
vars	object
subscribed	boolean

Request samples

Response samples

200

application/json

{"address": "alice@example.com",
"name": "Alice",
"vars": {"gender": "female",
"age": 27
},
"subscribed": true
}

Update a mailing list member

put/v3/lists/{list_address}/members/{member_address}

Updates a mailing list member with the given properties. Existing properties not included in the request will not be changed.

SecuritybasicAuth

Request

path Parameters

list_address required	string The mailing list's address
member_address required	string The member's address

Request Body schema: multipart/form-data

address	string A valid email address specification.
name	string An optional member name.
vars	object JSON-encoded dictionary string with arbitrary parameters.
subscribed	boolean Set the member to subscribed or not. Defaults to True.

Responses

200

OK

Response Schema: application/json

	object
message	string

Request samples

multipart/form-data

{
  "address": "alice@example.com",
  "name": "Alice",
  "vars": {
    "gender": "female",
    "age": 27
  },
  "subscribed": true
}

Response samples

200

application/json

{"member": {"address": "alice@example.com",
"name": "Alice",
"vars": {"gender": "female",
"age": 27
},
"subscribed": true
},
"message": "Mailing list member has been updated"
}

Delete a member

delete/v3/lists/{list_address}/members/{member_address}

Deletes a member from a mailing list

SecuritybasicAuth

Request

path Parameters

list_address required	string The mailing list's address
member_address required	string The member's address

Responses

200

OK

Response Schema: application/json

object

address

string

404

Not Found

Request samples

Response samples

200
404

application/json

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

Update a mailing list

put/v3/lists/{list_address}

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

SecuritybasicAuth

Request

path Parameters

list_address

required

string

The mailing list's address

Request Body schema: multipart/form-data

address	string The new mailing list address.
description	string
name	string
access_level	string One of: readonly, members, everyone. Defaults to readonly.
reply_reference	string Set where replies should go. Can be list or sender. Defaults to list.
list-id	string

Responses

200

OK

Response Schema: application/json

message	string
	object

404

Not Found

Request samples

multipart/form-data

{
  "address": "developers@mailgun.net",
  "name": "Developers",
  "description": "Describe the mailing list",
  "access_level": "readonly",
  "reply_preference": "list",
  "list_id": "123"
}

Response samples

200
404

application/json

{"message": "Mailing list has been updated",
"list": {"address": "developers@mailgun.net",
"name": "Developers",
"description": "Describe the mailing list",
"access_level": "readonly",
"reply_preference": "list",
"created_at": "Tue, 09 Aug 2011 20:50:27 -0000",
"members_count": 2
}
}

Delete mailing list

delete/v3/lists/{list_address}

Deletes a mailing list

SecuritybasicAuth

Request

path Parameters

list_address

required

string

The mailing list's address

Responses

200

OK

Response Schema: application/json

address	string
message	string

404

Not Found

Request samples

Response samples

200
404

application/json

{"address": "developers@mailgun.net",
"message": "Mailing list has been removed"
}

Get a mailing list by address

get/v3/lists/{list_address}

Returns the matching mailing list for the given address

SecuritybasicAuth

Request

path Parameters

list_address

required

string

The mailing list's address

Responses

200

OK

Response Schema: application/json

object

address	string
name	string
description	string
access_level	string
reply_preference	string
created_at	string
members_count	integer

404

Not Found

Request samples

Response samples

200
404

application/json

{"list": {"address": "developers@mailgun.net",
"name": "Developers",
"description": "Describe the mailing list",
"access_level": "readonly",
"reply_preference": "list",
"created_at": "Tue, 09 Aug 2011 20:50:27 -0000",
"members_count": 2
}
}

Get mailing lists by page

get/v3/lists/pages

Paginate over mailing lists

SecuritybasicAuth

Request

query Parameters

limit

integer

Set limit for the list length returned. Defaults to 100.

Responses

200

OK

Response Schema: application/json

	object
	Array of objects

Request samples

Response samples

200

application/json

{"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"
},
"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": ""
}
]
}

Get members by page

get/v3/lists/{list_address}/members/pages

Paginate over list members in a given mailing list in ascending order

SecuritybasicAuth

Request

path Parameters

list_address

required

string

The mailing list's address

query Parameters

subscribed	boolean Filtering list on whether the member is subscribed or not.
limit	integer Set limit for the list length returned. Defaults to 100.
address	string Use as pivot for pagination.
page	string Could be either: first, last, next or prev

Responses

200

OK

Response Schema: application/json

	object
	Array of objects

Request samples

Response samples

200

application/json

{"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"
},
"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": ""
}
]
}