The one-click unsubscribe feature collects unsubscribe requests and automatically filters unsubscribed recipients from future mailings. This reduces spam complaints, improves sender reputation, and increases inbox placement rates.
The feature complies with RFC 2369 and RFC 8058. Major providers including Google, Microsoft, and Yahoo fully support it.
Whether the unsubscribe button appears depends on the recipient's email client policy. For example, Gmail may hide it for domains with low reputation.
Direct Mail adds an unsubscribe link to email headers, filters future emails to unsubscribed recipients, and provides APIs for list management.
Unsubscribe link mechanism
The unsubscribe link is added to the List-Unsubscribe field in the email header. It does not affect your email content.
By default, an unsubscribe link is generated for recipients at Google, ProtonMail, Feishu Mail, and domains containing the keywords "gmail", "yahoo", "google", "aol.com", "hotmail", "outlook", or "ymail.com". No link is generated for Microsoft 365 accounts.
An unsubscribe link is not generated for emails sent from a trigger address.
Example: Gmail
-
Relevant email header
-
Display in email client
Method 1: One-click unsubscribe
The email header must contain List-Unsubscribe-Post: List-Unsubscribe=One-Click.
Two implementation options:
-
Set the X-AliDM-Settings header. Direct Mail automatically configures the
List-Unsubscribe-PostandList-Unsubscribeheaders.NoteSet up
X-AliDM-Settingsby following Control features by using email header configurations over SMTP. -
Use a custom URL: Include the
List-Unsubscribe-Post: List-Unsubscribe=One-Clickheader and your own unsubscribe link in theList-Unsubscribefield when sending over SMTP.
Method 2: Redirect to an unsubscribe webpage
The email header must not contain List-Unsubscribe-Post: List-Unsubscribe=One-Click.
-
Use a custom URL: Omit the
X-AliDM-Settingsheader and provide your unsubscribe link in theList-Unsubscribeheader when sending over SMTP.
Unsubscribe list filtering
When a recipient unsubscribes, their address is added to your unsubscribe list. On each send, Direct Mail checks this list at the configured filter level and blocks delivery to listed addresses. Unsubscribe requests take effect within one hour. Three filter levels are available:
Sender address level: Blocks delivery if the recipient unsubscribed from the specific sender address.
Sender domain level: Blocks delivery if the recipient unsubscribed from any address in the sender domain. Recommended for domains that send bulk email, to separate bulk and triggered email unsubscribes.
Account level: Blocks delivery if the recipient has unsubscribed from all sender addresses under your cloud account. Recommended when all sender addresses are used for promotional campaigns.
Link generation and filtering by scenario:
|
Scenario |
Link generation (LinkType) |
Filtering (FilterLevel) |
|
Bulk email |
Yes |
Sender address level |
|
Trigger address |
No |
No filtering |
|
User-implemented one-click unsubscribe |
Keep the user's link |
No filtering |
|
User-defined |
User-defined |
User-defined |
To configure user-defined settings:
-
When sending over SMTP, configure the unsubscribe link and filter level by following Control features by using email header configurations over SMTP.
-
When sending through the API, use the SingleSendMail or BatchSendMail API.
Manage the unsubscribe list
Unsubscribe
Recipients unsubscribe by clicking the Unsubscribe button in their email client.
If the email client does not show an unsubscribe link, recipients can find it in the raw message headers.
The unsubscribe page language is determined by the recipient's browser or OS settings, not the lang parameter in the link.
Unsubscribe management
If a recipient accidentally unsubscribes, go to the Direct Mail console and navigate to data analytics > Unsubscribes to remove the entry.
Alternatively, the recipient can revisit the unsubscribe link and click Resubscribe to be automatically removed from the list.
Do not remove recipients from the unsubscribe list unless they unsubscribed by mistake. Re-subscribing without consent can cause high complaint rates, leading to blacklisting of your sender address or domain and reduced delivery rates for all recipients.
Do not send marketing, subscription, or promotional emails to unsubscribed recipients. For triggered emails such as verification codes, use a trigger address.
Related APIs: UnblockRecipient