Implementing an Email Unsubscribe Management System

Email Unsubscribe Management System

Every marketing email that lacks an easy unsubscribe is a risk of receiving a spam complaint. One click on the "This is spam" button in Gmail or Outlook triggers a chain: algorithms detect low sender reputation, the domain enters blacklists, and email deliverability plummets to zero. For an e-commerce store with a monthly turnover of 50 million rubles, losing the email channel means a lost profit of 1-2 million rubles per month. The system implementation cost ranges from 50,000 to 150,000 rubles depending on complexity. We build an unsubscribe system that is legally flawless (GDPR, FZ-152) and technically transparent: one-click link, List-Unsubscribe, preference management. No data black holes and no security compromises.

Key Problems and Risks

The first and main risk is legal. Lack of easy unsubscribe is a direct violation of Article 17 GDPR ("Right to erasure") and Russian FZ-152. Fines can reach 4% of annual turnover, which for medium-sized businesses amounts to millions of rubles. Recently, a large e-commerce project received a Roskomnadzor order for 2.5 million rubles precisely due to an opaque unsubscribe procedure.

The second problem is email server blocking. Gmail and Outlook require the List-Unsubscribe header for senders with volumes above 5,000 emails per day. Without it, emails land in spam, and domain reputation degrades within a week—deliverability drops by 10% every campaign.

The third is user experience. A complex unsubscribe procedure (requiring login, multiple clicks) provokes mass complaints. A Return Path study found that 68% of users click "Spam" if they don't see an unsubscribe button within three seconds. And each percentage point of complaints lowers sender reputation by 5-10 points.

How Does One-Click Unsubscribe Work?

One-click unsubscribe is built on the List-Unsubscribe header (RFC 8058). Upon receiving an email, the mail client shows an "Unsubscribe" button. The user does not need to open a browser or enter a password—a POST request goes to the server, and the unsubscribe is processed instantly. Under the hood, an HMAC-signed token prevents forgery and allows exact identification of what the user is unsubscribing from.

import { createHmac } from 'crypto';

function generateUnsubscribeToken(userId: string, type: string): string {
  const payload = `${userId}:${type}:${Date.now()}`;
  const signature = createHmac('sha256', process.env.UNSUBSCRIBE_SECRET!)
    .update(payload)
    .digest('hex');
  return Buffer.from(`${payload}:${signature}`).toString('base64url');
}

function generateUnsubscribeUrl(userId: string, type: string = 'all'): string {
  const token = generateUnsubscribeToken(userId, type);
  return `/unsubscribe/${token}`;
}

Why Is List-Unsubscribe Important?

Without List-Unsubscribe, emails are highly likely to land in spam. Major email providers—Gmail, Outlook, Yandex—analyze headers and penalize senders without this field. Reputation penalty: every million emails without List-Unsubscribe can cost 10-15% deliverability. For a project with 100,000 subscribers, this means losing 10,000-15,000 contacts per single campaign. One-click unsubscribe is 5x faster than mailto and 10x more user-friendly.

How We Do It: Stack and Approach

We use a database with subscription type separation and a suppression list. Our team has implemented this system for over 30 businesses across retail and SaaS, with 5+ years of experience in email infrastructure.

Example structure:

CREATE TABLE email_subscriptions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id),
  subscription_type VARCHAR(100) NOT NULL,
  -- 'marketing', 'digest', 'product_updates', 'security', 'transactional'
  is_active BOOLEAN NOT NULL DEFAULT true,
  unsubscribed_at TIMESTAMPTZ,
  unsubscribe_reason TEXT,
  created_at TIMESTAMPTZ DEFAULT now(),
  UNIQUE (user_id, subscription_type)
);

CREATE TABLE email_suppression_list (
  email VARCHAR(255) PRIMARY KEY,
  reason VARCHAR(100) NOT NULL,  -- 'unsubscribe', 'bounce', 'complaint'
  created_at TIMESTAMPTZ DEFAULT now()
);

The unsubscribe handler accepts GET (show page) and POST (confirm):

// GET /unsubscribe/:token — link in email (one-click preview)
app.get('/unsubscribe/:token', async (req, res) => {
  const decoded = parseUnsubscribeToken(req.params.token);
  if (!decoded) return res.status(400).render('unsubscribe-invalid');
  res.render('unsubscribe', {
    userId: decoded.userId,
    type: decoded.type,
    token: req.params.token,
  });
});

// POST /unsubscribe/:token — confirm unsubscribe
app.post('/unsubscribe/:token', async (req, res) => {
  const decoded = parseUnsubscribeToken(req.params.token);
  if (!decoded) return res.status(400).json({ error: 'Invalid token' });
  const { type, reason } = req.body;
  if (type === 'all') {
    await db.query(
      `UPDATE email_subscriptions
       SET is_active = false, unsubscribed_at = now(), unsubscribe_reason = $1
       WHERE user_id = $2 AND subscription_type != 'transactional'`,
      [reason, decoded.userId]
    );
    const user = await db.users.findById(decoded.userId);
    await db.query(
      `INSERT INTO email_suppression_list (email, reason) VALUES ($1, 'unsubscribe')
       ON CONFLICT (email) DO NOTHING`,
      [user.email]
    );
  } else {
    await db.query(
      `UPDATE email_subscriptions
       SET is_active = false, unsubscribed_at = now()
       WHERE user_id = $1 AND subscription_type = $2`,
      [decoded.userId, type]
    );
  }
  res.json({ ok: true });
});

List-Unsubscribe Header and One-Click (RFC 8058)

In addition to the standard mailto header, we add List-Unsubscribe-Post for one-click unsubscribe without opening a browser. This is mandatory for Gmail and Outlook with high sending volumes.

await sendEmail({
  to: user.email,
  subject: 'Our Digest',
  html: emailHtml,
  headers: {
    'List-Unsubscribe': `<mailto:[email protected]?subject=unsub-${userId}>, <https://app.domain.com/unsubscribe/${token}>`,
    'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
  },
});

// POST /api/email/list-unsubscribe — One-Click handler
app.post('/api/email/list-unsubscribe', async (req, res) => {
  const { 'list-unsubscribe': fieldValue } = req.body;
  // Field = 'One-Click' — just process
  res.status(200).end();
});

Which Subscription Types Should Remain Mandatory?

Transactional and security notifications must not be disableable. Others are user's choice. Here is a typical matrix:

Comparison of Unsubscribe Methods

Work Process

1. Analysis — study current subscription structure, legal requirements, email restrictions.
2. Design — database schema, API endpoints, contracts.
3. Implementation — code, integration with your system, List-Unsubscribe setup.
4. Testing — verify on real mailboxes (Gmail, Outlook, Yandex).
5. Deploy and Document — deliver code, API description, admin instructions.

What's Included

• Design of subscription and suppression schema
• Development of one-click link with HMAC token
• Configuration of List-Unsubscribe (RFC 2369 + RFC 8058)
• Preference management page
• Integration with your database
• Testing with email providers
• Documentation and staff training
• Launch support

Estimated Timeline

Basic system (one-click + suppression list) — from 2 to 3 days. With extended preferences and analysis — up to 5 days. Cost is calculated individually based on your architecture.

Evaluate your project: contact us, and we will send a detailed proposal with stages and timelines. Get a consultation on integrating the unsubscribe system. Our solution ensures email marketing compliance with all regulations.

Email Campaign Integration: Why Does It Often Break?

We’ve observed that a trigger email sent 10 minutes after registration converts 4–5 times better than the same email sent after 24 hours. This isn’t a marketing myth—it’s mechanics: while the user is still warm, while they remember the context. But most integrations with email services are built like this: form submits → synchronous HTTP request to API → if the API is slow, the user waits 3 seconds → the email either goes out or doesn’t, nobody knows. In one project, we saw a 30% drop in conversion simply because the email service responded with 504 and Laravel’s queue driver wasn’t configured. Lost emails often hit customers silently – no log, no alert, just a missing order confirmation.

If you’re facing lost emails or spam folder issues, order an audit of your current integration – we’ll find bottlenecks within 2 days.

Providers and Their APIs

Unisender — a Russian provider popular in the SMB segment. REST API, simple. Adding a contact: importContacts, sending a transactional email: sendEmail. Important: for transactional emails (order confirmations, password resets), Unisender Go is a separate service with a different API and separate pricing. Mixing bulk and transactional mailings in one stream is bad for domain reputation. Unisender Go handles up to 1000 requests per second.

SendPulse — provides email, SMS, web push, Viber, and Telegram bots through a unified API. Convenient for projects requiring an omnichannel approach. Automation 360 is a visual chain builder; you can trigger automation via API events. The PHP SDK (sendpulse/rest-api-php-sdk) is maintained but updated irregularly – better to use Guzzle directly.

Mailchimp — a choice for international audiences and marketing teams accustomed to the Mailchimp ecosystem. Transactional email via Mandrill (a subsidiary service). Marketing API v3 for list, tag, and campaign management. Webhooks for opens, clicks, unsubscribes, bounces.

SMS. For Russia: SMSCenter, MTS Exolve, Devino Telecom, SMS Aero. Their APIs are similar: a send method with phone, message, sender parameters (sender name must be registered separately with the operator). One nuance: the sender name must be registered through the aggregator with a contract – otherwise SMS won’t be sent on MTS/MegaFon/Beeline networks.

How to Build an Integration That Doesn’t Lose Emails?

Separate Transactional and Marketing Streams

Transactional emails (order confirmations, password resets, delivery status) go through a dedicated sender domain or subdomain tx.example.com. Marketing campaigns go through mail.example.com or news.example.com. If a marketing campaign receives many spam complaints, it should not affect the reputation of the transactional stream. According to SendGrid documentation, transactional messages should be sent through a dedicated IP pool to prevent cross-contamination.

Queue and Retry

Any call to the email API goes through a queue (Laravel Queue, Bull, Celery). If Unisender returns a 503, the job retries after 5 minutes, then 15, then 60. After 5 failed attempts, it goes to a dead letter queue with an alert. The user already received their 200 OK and knows nothing about the issue. This approach reduces bounce rate on projects to 0.5%.

Example Laravel job:

public function handle(): void
{
    try {
        $response = Http::post(config('services.unisender.email_url'), $this->params);
        if ($response->failed()) {
            $this->release(300); // retry after 5 min
        }
    } catch (\Throwable $e) {
        $this->release(300);
    }
}

Templates

We store templates in code (Blade, Twig, React Email), not in the provider’s interface. Reasons: versioning via Git, browser preview without sending, testability. For complex templates with dynamic content — react-email with export to HTML via @react-email/render.

Validation and Consent

Before adding a contact to a list — double opt-in (confirmation email). Store the confirmation timestamp in your own database. Upon unsubscription — synchronously unsubscribe both at the provider and in your database. Ignoring webhook unsubscriptions is a direct path to account suspension at the provider. All processes comply with Федеральный закон № 152-ФЗ «О персональных данных».

Deliverability Monitoring and DKIM Setup

Connect provider webhooks for events: bounce (hard and soft), spam_complaint, unsubscribe. Hard bounce — immediately mark the email as invalid in your database, stop sending. Soft bounce 3 times in a row — same. Metrics: open rate, click rate, bounce rate, unsubscribe rate — review at least once a week. Our certified engineers configure alerts in Grafana/Prometheus.

DKIM configuration steps:

1. Generate a key pair (e.g., openssl genrsa -out private.key 2048).
2. Publish the public key in DNS as a TXT record for the selector (e.g., mail._domainkey.tx.example.com).
3. Provide the selector to the provider (SendGrid, Mailgun, Unisender).
4. Verify with dig TXT mail._domainkey.tx.example.com.

SPF, DKIM, DMARC must be configured separately for each stream. We use subdomains with different DNS records.

Why Is It Important to Separate Streams?

If you send a marketing campaign from the same domain as transactional emails and receive spam complaints, you risk getting the domain blocked — and users will stop receiving even order confirmations. SPF, DKIM, DMARC (Sender Policy Framework, DomainKeys Identified Mail, Domain‑based Message Authentication, Reporting and Conformance) must be configured separately for each stream. In one project, a marketing blast with 12% spam complaints blocked the transactional domain for 48 hours — we had to re‑authenticate with Google and Yandex.

What Does the Integration Scope Include?

• Audit of current communication streams and domain reputation (SPF, DKIM, DMARC)
• Provider and schema selection: transactional vs marketing traffic
• Configuration of SPF, DKIM, DMARC DNS records
• Development of email templates (HTML + dynamic content)
• Backend integration via queues and API
• Webhook setup for deliverability and complaints
• Operations documentation and team training
• Deliverability guarantee and post‑launch support

We deliver production‑ready documentation, access to monitoring dashboards, and a handover session with your engineers. Our certified engineers provide a 30‑day post‑launch health check guarantee.

Timelines and Cost

Cost is calculated individually after audit. We provide turnkey service: from analysis to production monitoring. Contact us for a free engineer consultation — we’ll evaluate your project and give accurate timelines. Over 7 years of experience in email service integration, 50+ projects implemented. Order a free audit of your current integration and receive a report with recommendations and estimated savings.