Unsubscribe management
Kasplo provides automated, compliant unsubscribe mechanisms adhering to modern mailbox provider mandates (such as Google and Yahoo RFC 8058 one-click unsubscribe requirements).
Unsubscribe behavior is determined primarily by your message type (marketing vs transactional) and your account footer settings.
Marketing vs Transactional Behavior
Feature
Marketing Emails (type: "marketing" or omitted)
Transactional Emails (type: "transactional")
Default Unsubscribe
Always enabled
Disabled by default
RFC 8058 One-Click Headers
Automatically generated by Kasplo
Enabled only when configured
HTML Footer Insertion
Controlled by account setting "Add unsub links"
Not automatically inserted
Custom Unsubscribe URLs
Ignored (Kasplo-managed URL enforced)
Supported via custom headers
Plain-Text Emails
Headers added; no footer appended
Headers added if enabled; no footer
1. Marketing Emails
When sending marketing or promotional emails, Kasplo automatically inserts RFC 8058 compliant List-Unsubscribe and List-Unsubscribe-Post headers using recipient-specific Kasplo endpoints.
{
"email": {
"from": "marketing@yourdomain.com",
"subject": "Seasonal Sale"
}
}Positioning the Link in HTML Content
By default, if the Add unsub links account setting is turned on, Kasplo appends a standard unsubscribe footer to your HTML.
To control exactly where the unsubscribe link appears within your branded email template, use the {{kasplo.unsubscribe}} placeholder:
Automatic Footer Suppression: If
{{kasplo.unsubscribe}}is detected anywhere in your HTML, Kasplo replaces the tag with the recipient-specific URL and will not append the default footer.
2. Transactional Emails
By default, emails sent with "type": "transactional" do not include unsubscribe links or headers.
Option A: Enable Kasplo-Managed Unsubscribe
If your transactional email requires opt-out functionality, enable it in the payload:
Kasplo will generate recipient-specific one-click headers and allow the use of {{kasplo.unsubscribe}} in the body.
Option B: Use Your Own Unsubscribe Endpoint
To direct recipients to your internal preference center or opt-out handler, provide your HTTPS endpoint in the message headers:
Custom Header Validation Rules
The
List-UnsubscribeURL must usehttps://and include a valid hostname.The URL must be enclosed in angle brackets
< ... >.Credentials (e.g.
https://user:pass@...) and fragments (#fragment) are rejected.Newlines or carriage returns inside headers are strictly rejected.
3. RFC 8058 One-Click Execution vs Link Visits
Kasplo differentiates between automated mailbox provider one-click actions and browser link clicks:
A. One-Click Request (Mailbox Provider Action)
When a recipient clicks the native "Unsubscribe" button in Gmail or Yahoo, the mailbox provider sends an HTTP POST to the URL in List-Unsubscribe:
Immediate Processing: No webpage visit or confirmation click is required.
The token is validated, and the recipient is immediately queued for
UNSUBsuppression.
B. HTML Body Link Visit (Recipient Browser Action)
When a recipient clicks the link inside the email body:
Kasplo validates the token and redirects the browser to a confirmation/preferences page.
The GET request itself does not immediately suppress the recipient; confirmation is captured on the landing page.
4. Kasplo Unsubscribe Receiver Endpoint
If you are using Kasplo-managed unsubscribe URLs, receiving requests follow these specifications:
Accepted POST Format
Content-Type:
application/x-www-form-urlencodedormultipart/form-dataBody:
List-Unsubscribe=One-ClickMax Payload Size: 4,096 bytes
Success Response (200 OK)
Endpoint Errors
400
Invalid form values or missing List-Unsubscribe=One-Click.
404
Expired or non-existent recipient token.
413
Payload exceeds 4,096 bytes.
415
Unsupported content type.
503
Service temporarily unavailable; retry according to Retry-After: 30.
5. Synchronizing Opt-Outs with Suppression APIs
When your own application handles an unsubscribe event, synchronize it immediately with Kasplo so future marketing dispatches are blocked:
For the complete Suppression API reference and batch synchronization, see Suppression APIs.
To capture unsubscribe events automatically in your backend, subscribe to the
engine_unsubwebhook event in Webhooks.
Last updated