Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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"
  }
}

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-Unsubscribe URL must use https:// 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.


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 UNSUB suppression.

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-urlencoded or multipart/form-data

  • Body: List-Unsubscribe=One-Click

  • Max Payload Size: 4,096 bytes

Success Response (200 OK)

Endpoint Errors

HTTP Status
Reason

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_unsub webhook event in Webhooks.

Last updated