Unsubscribe

Unsubscribe list stores email addresses of recipients who unsubscribed from your mailings by clicking a Mailgun generated unsubscribe link.

Import list of unsubscribes

post/v3/{domainID}/unsubscribes/import

Import a CSV file containing a list of addresses to add to the unsubscribe list.The CSV file must be 25MB or under and must contain the following column headers: address, tags, created_at.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to update

header Parameters
Content-Type
required
string

Content-Type must be multipart/form-data

Request Body schema: multipart/form-data
required
address
required
string

Valid email address

tags
string

Tag to unsubscribe from, use * to unsubscribe an address from all domain’s correspondence (optional, default: *)

created_at
string

Timestamp of an unsubscribe event in RFC2822 format (optional, default: current time)

Responses
202

A 202 response

400

A 400 response

500

A 500 response

Request samples
Response samples
application/json
{
  • "message": "file uploaded successfully"
}

View a single unsubscribe

get/v3/{domainID}/unsubscribes/{address}

Fetch a single unsubscribe record to check if a given address is present in a list of unsubscribed users.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to fetch an unsubscribe from

address
required
string.+

The address to search for

Responses
200

A 200 response

Response Schema: application/json
address
required
string
tags
required
Array of strings
created_at
required
object
404

A 404 response

Request samples
Response samples
application/json
{
  • "tags": [
    • "some tag"
    ],
  • "created_at": "Fri, 18 Oct 2024 18:28:14 UTC",
  • "address": "alice@example.com"
}

Clear a given unsubscribe event

delete/v3/{domainID}/unsubscribes/{address}

The delivery to the deleted email address resumes until it unsubscribes again.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to delete a unsubscribe from

address
required
string.+

The address to remove

Responses
200

A 200 response

Response Schema: application/json
message
required
string
address
required
string
400

A 400 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "message": "Unsubscribe event has been removed",
  • "address": "foo@bar.com"
}

View all unsubscribes

get/v3/{domainID}/unsubscribes

Paginate over a list of unsubscribes for a domain.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The name of the domain you want to get unsubscribes from

query Parameters
address
required
string

address serving as a "divider" between pages

term
required
string

Filter records based on addresses that start with the specified substring.

limit
integer

Maximum number of records to return (optional, default: 100, max: 1000)

page
string

Page direction relative to the above address, can be next, previous or last, if empty, returns the first page

Responses
200

A 200 response

Response Schema: application/json
required
Array of objects
required
object
400

A 400 response

Request samples
Response samples
application/json
{
  • "items": [
    • {
      }
    ],
  • "paging": {
    • "previous": "<previous page url>",
    • "first": "<first page url>",
    • "next": "<next page url>",
    • "last": "<last page url>"
    }
}

Insert unsubscribe records to the unsubscribe list

post/v3/{domainID}/unsubscribes

Request body is expected to be a valid JSON encoded sting containing up to 1000 unsubscribe records or a single unsubscribe record as application/form-data

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to insert unsubscribes

header Parameters
Content-Type
required
string

Content-Type must be application/json if inserting using JSON, no header necessary for form-data insertion

Request Body schema:
required
address
required
string

Valid email address

tags
string

Tag to unsubscribe from, use * to unsubscribe an address from all domain’s correspondence (optional, default: *)

created_at
string

Timestamp of an unsubscribe event in RFC2822 format (optional, default: current time)

Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

Request samples
No sample
Response samples
application/json
{
  • "message": "4 addresses have been added to the unsubscribes table"
}

Delete entire unsubscribe list

delete/v3/{domainID}/unsubscribes

Clear all unsubscribe email addresses for the domain. Delivery to the deleted email addresses will no longer be suppressed.

SecuritybasicAuth
Request
path Parameters
domainID
required
string

The id of the domain you want to delete unsubscribes from

Responses
200

A 200 response

Response Schema: application/json
message
required
string
400

A 400 response

404

A 404 response

Request samples
Response samples
application/json
{
  • "message": "Unsubscribe addresses for this domain have been removed"
}