Laravel one-click unsubscribe: RFC 8058 code example

Laravel Mailables can add RFC 8058 headers through the underlying Symfony message. Use this pattern for marketing and subscribed messages; password resets, receipts, and other ordinary transactional messages do not require one-click unsubscribe.

Required headers

• List-Unsubscribe: include an HTTPS endpoint; mailto can be an additional fallback.
• List-Unsubscribe-Post: List-Unsubscribe=One-Click: tells providers to send the RFC 8058 POST.
• Honor requests inside 48 hours; aim for immediate suppression.

Add headers inside a Mailable

Use withSymfonyMessage to set headers on the underlying Symfony Email object:

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
use Symfony\Component\Mime\Email;

class ProductUpdateMail extends Mailable
{
    use Queueable, SerializesModels;

    public function build()
    {
        $token = 'abcd1234'; // signed token for this recipient+list

        $this->withSymfonyMessage(function (Email $message) use ($token) {
            $message->getHeaders()
                ->addTextHeader('List-Unsubscribe', "<https://example.com/unsub/{$token}>, <mailto:[email protected]?subject=unsubscribe>")
                ->addTextHeader('List-Unsubscribe-Post', 'List-Unsubscribe=One-Click');
        });

        return $this
            ->from('[email protected]', 'Product Updates')
            ->subject('Service notice')
            ->view('emails.product-update')
            ->with(['unsubscribe_url' => "https://example.com/unsub/{$token}"]);
    }
}

Recommendations:

• Keep a visible unsubscribe link in the blade view.
• Accept the POST without login, cookies, or a CSRF token and return a successful response quickly.
• Do not expose raw emails in the URL; sign the token.

Apply defaults (optional)

If you always include one-click, set a mail macro/service provider to add List-Unsubscribe-Post globally, and still inject the per-recipient List-Unsubscribe in each Mailable.

Handling the endpoint

• Accept POST with List-Unsubscribe=One-Click; use GET only for a human-facing preference page.
• Add the address to the token's subscription-list suppression immediately.
• Keep essential transactional mail separate from subscription mail.
• Log timestamp, token/list, and IP for audits.

Testing checklist

• Send a test to Gmail/Yahoo; confirm headers in message source.
• Click the link; verify instant suppression and 200 response.
• Send another test within 24 hours; the unsubscribed address must not receive it.
• Track complaint rates; keep under 0.1%.

Where SMTP Zen helps

SMTP Zen delivers your Laravel Mail output with aligned authentication. Add the headers above, wire the endpoint to your suppression logic, and you meet Gmail/Yahoo one-click expectations without a marketing ESP.