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 can contain the following column headers: address, tags, created_at. address is a valid email address (required). tags is tag to unsubscribe from, use * to unsubscribe an address from all domain's correspondence (optional, default: *). created_at is timestamp of unsubscribe event in RFC2822 format (optional, default: current time)

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
file
required
string

CSV file

Responses
202

A 202 response

400

A 400 response

500

A 500 response

Request samples 
Response samples 
application/json
{
  • "message": "file uploaded successfully for processing. standby..."
}
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
{
  • "address": "alice@example.com",
  • "tags": [
    • "some tag"
    ],
  • "created_at": "Tue, 07 Jan 2025 19:25:45 UTC"
}
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
 Array 
address
required
string
 
tags
required
Array of strings
 
created_at
required
object
 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
400
A 400 response


Request samples 
[
  • {
    • "address": "alice@example.com",
    • "tags": [
      ],
    • "createdat": "Tue, 07 Jan 2025 19:25:45 UTC"
    },
  • {
    • "address": "bob@example.com",
    • "tags": [
      ],
    • "createdat": "Mon, 01 Jan 0001 00:00:00 UTC"
    },
  • {
    • "address": "carol@example.com",
    • "tags": [ ],
    • "createdat": "Mon, 01 Jan 0001 00:00:00 UTC"
    }
]
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"
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.