How ISP Email Filtering Works in 2026

Every major ISP runs sophisticated filtering systems that evaluate every inbound message in real time. The goal: distinguish legitimate senders from spam, phishing, and malware distribution.

Gmail’s Filtering Stack

Gmail processes over 300 billion emails per day. Their filtering system uses:

Sender reputation signals:

• IP address reputation (established via warmup history)
• Domain reputation (sending domain + From domain)
• DKIM/SPF/DMARC authentication pass rates
• Complaint rate (% of recipients marking as spam)

Content signals:

• Keyword density and spam trigger detection
• Image-to-text ratio
• Link analysis (where links point, URL shortening)
• HTML quality and rendering consistency

Engagement signals:

• Open rates (historical per-user engagement)
• Click rates
• Reply rates (Gmail-specific)
• Delete-without-opening rate

Behavioral signals:

• Direct marks as spam (% who click “Report Spam”)
• Whether recipients have your address in contacts
• Time spent reading (Gmail tracks this)

Microsoft (Outlook/Hotmail) Filtering

Microsoft’s filtering (used across Outlook.com, Microsoft 365, and some corporate Exchange) evaluates:

• SNDS IP reputation data
• Smart Network Data Services (free IP reputation portal)
• Outlook.com complaint rates
• Exchange Online Protection (EOP) rules

Microsoft is particularly sensitive to:

• High complaint rates
• Rapid list growth (sending to newly acquired addresses)
• Certain attachment types

Yahoo Mail Filtering

Yahoo improved filtering significantly in 2024 with mandatory DMARC requirements. Yahoo evaluates:

• DMARC pass rate (must be 100% aligned)
• Complaint feedback loop data
• Bounce rates (Yahoo is more tolerant than Gmail)
• Authentication consistency

The 7 Pillars of Sender Reputation

Pillar 1: IP Reputation

Your sending IP addresses carry significant reputation weight. Each IP you send from accumulates:

• Volume history (gradual growth = legitimate; spikes = suspicious)
• Bounce rate history
• Complaint rate
• Spam trap hits

Protecting IP reputation:

• Always warm up new IPs over 8+ weeks
• Never exceed 2x your established daily volume
• Rotate IPs if one gets flagged
• Monitor Postmaster Tools daily

Pillar 2: Domain Reputation

Your From domain and root domain carry reputation signals separate from IP reputation:

• [email protected] — your sending identity
• example.com — your organizational domain

Protecting domain reputation:

• Use separate subdomains for transactional and marketing email
• Never send marketing from your primary domain
• Publish and maintain proper SPF/DKIM/DMARC
• Monitor domain-level reputation in Postmaster Tools

Pillar 3: Authentication (SPF/DKIM/DMARC)

Authentication is non-negotiable in 2026. Gmail and Yahoo require it:

• SPF: Authorizes which IPs can send for your domain
• DKIM: Cryptographic signature proving message integrity
• DMARC: Policy layer enforcing alignment between SPF/DKIM and From domain

See our Email Authentication Guide for full setup instructions.

Pillar 4: List Quality

Your list quality determines your complaint rate and bounce rate:

• Purchased lists = high complaints and bounces = destroyed reputation
• Rented lists = same problem
• Organic subscribers = low complaints, high engagement

List quality benchmarks:
| List Source | Bounce Rate | Complaint Rate |
|————|————-|—————|
| Organic (opt-in) | < 1% | < 0.05% |
| Lead magnet | < 2% | < 0.1% |
| Purchased | > 10% | > 0.5% |

Pillar 5: Engagement Rate

Gmail and Microsoft both use engagement as a reputation signal. Engaged users = signals that you’re a legitimate sender.

Benchmark engagement rates:
| Industry | Open Rate | Click Rate |
|———|———-|———–|
| E-commerce | 15-25% | 2-5% |
| SaaS | 20-30% | 3-8% |
| Media/Publishing | 20-35% | 3-6% |
| Finance | 25-40% | 5-10% |

If your engagement drops significantly after a campaign, ISPs interpret it as a signal that recipients didn’t want your mail.

Pillar 6: Complaint Rate

Complaint rate = (% of recipients who click “Report Spam”). This is your most dangerous metric.

Thresholds:

• Gmail: Keep below 0.1% (1 complaint per 1,000 emails)
• Microsoft: Keep below 0.1%
• Yahoo: Keep below 0.1%

Complaint rate > 0.3% for even one day = expect throttling or reputation drop.

Pillar 7: Bounce Rate

Hard bounces signal that you’re sending to invalid addresses — a hallmark of purchased or scraped lists.

Thresholds:

• Hard bounce rate: Keep below 2%
• Total bounce rate: Keep below 3%

Hard bounce > 5% = immediate ISP throttling.

ISP-Specific Deliverability Requirements

Gmail Requirements (Mandatory for Bulk Senders)

Since February 2024, Gmail requires for senders of 5,000+ emails/day:

Microsoft / Outlook Requirements

Yahoo Requirements

Improving Inbox Placement: Practical Steps

Step 1: Authentication Audit

Before doing anything else, verify your authentication:

1. Go to mail-tester.com
2. Send a test email to their address
3. Review the full authentication report

Common issues:

• SPF includes IPs that shouldn’t be there (third-party senders not in record)
• DKIM selector mismatch (selector doesn’t match DNS)
• DMARC alignment failure (From domain doesn’t match DKIM/SPF domain)

Step 2: Warmup New IPs Properly

If you’re starting with new sending IPs:

1. Use our IP Warmup Guide
2. Start at 50-100 emails/day, increase by 50% weekly
3. Only send to engaged recipients during warmup
4. Monitor Gmail Postmaster Tools daily

Step 3: List Hygiene Implementation

Remove problematic addresses before sending:

• Remove hard bounces immediately (don’t retry)
• Verify new addresses via API before adding to list
• Re-verify addresses inactive > 60 days
• Remove addresses with 3+ soft bounces

Step 4: Engagement-Based Segmentation

Segment your list by engagement to protect reputation:

-- KumoMTA: Engagement-based routing
kumo.on('smtp_message_received', function(domain, meta)
    local headers = meta.headers or {}
    local engagement_tier = headers['X-Engagement-Tier']

    if engagement_tier == 'highly-engaged' then
        -- High priority: active recent openers
        kumo.set_queue_priority('high')
        -- Route to established IPs
        kumo.set_sending_ip(HIGH_REP_IP)
    elseif engagement_tier == 'cold' then
        -- Low priority: dormant subscribers
        -- Send last, from warmup IPs
        kumo.set_queue_priority('low')
    else
        -- Normal priority
    end
end)

Step 5: Content Optimization

Even well-authenticated email gets filtered based on content:

Red flags that trigger spam filters:

• ALL CAPS subject lines
• Excessive punctuation (!!!, ???)
• “Click here” / “Act now” / “Limited time”
• Excessive links (more than 3 in body)
• High image-to-text ratio (> 60% images)
• Suspicious attachments (.zip, .exe, .js)

Best practices:

• Clear, descriptive subject lines (under 60 characters)
• Plain-text alternative alongside HTML
• Single clear CTA
• Manage sender expectations in the From line

Monitoring Infrastructure

Gmail Postmaster Tools (Free)

Monitor:

• Domain reputation (Poor → Fair → Good → Excellent)
• Spam rate
• Authentication results (SPF/DKIM/DMARC pass %)
• Encryption status

Microsoft SNDS (Free)

Register at snds.azurewebsites.net:

• IP reputation (Good → Neutral → Bad)
• Complaint rate
• Mail volume

Yahoo Postmaster

Register at postmaster.yahoo.com:

• DMARC compliance rate
• Spam rate

Internal Monitoring You Need

Build dashboards tracking:

Recovery: Getting Out of the Spam Folder

If you’re already in the spam folder:

Step 1: Diagnose

• Check Postmaster Tools for reputation damage
• Identify root cause (bounces, complaints, content, authentication)

Step 2: Pause if necessary

• If hard bounce > 5% or complaint > 0.3%, pause sending immediately

Step 3: Fix

• Clean your list (remove bounces, inactive)
• Review recent campaigns for complaint triggers
• Verify authentication is passing 100%

Step 4: Re-warmup

• If IP reputation is damaged, re-warmup over 4-8 weeks
• Send only to highly engaged recipients
• Monitor daily

Step 5: Gradual resume

• Resume at 25% of pre-pause volume
• Increase 20% weekly if metrics are clean

FAQ

Q: How long does it take to recover from a spam folder placement?
A: If you fix the root cause and have a clean list: 2-4 weeks for Gmail, 1-2 weeks for Outlook. If your IP is blacklisted, recovery can take 60-90 days.

Q: Can I buy my way out of a spam problem?
A: No. There are no shortcuts. Fix the root cause (list quality, authentication, engagement) and rebuild reputation systematically.

Q: Does double opt-in help deliverability?
A: Indirectly — double opt-in dramatically reduces complaint rates because only highly motivated subscribers confirm. High complaint rates are the most common cause of spam folder placement.

Q: Is inbox placement rate more important than open rate?
A: Yes — if you’re in the spam folder, your open rate drops to near zero. Inbox placement is the prerequisite; engagement follows from it.

Q: Do Gmail Postmaster Tools show real-time data?
A: No — Gmail data is delayed by 24-48 hours. For real-time alerting, build internal metrics from your delivery logs.

Get Help With Email Deliverability

PostMTA provides deliverability services:

• Full authentication audit and implementation
• IP warmup management
• List hygiene and verification integration
• Inbox placement monitoring
• ISP complaint response and recovery

👉 Talk to a deliverability specialist →

For related guides, see IP Warmup Strategies, Email Authentication Guide, Bounce Rate Reduction Guide, and SMTP Relay Setup Guide.

References: Gmail Postmaster Tools | Microsoft SNDS | RFC 8058 (List-Unsubscribe)

At the Open Source Summit North America 2026, Microsoft today revealed a sweeping set of updates aimed at strengthening the foundation of the AI-native era. Central to these announcements is the upcoming public preview of Azure Linux 4.0 on Azure Virtual Machines and the general availability of Azure Container Linux. These distributions represent a hardened … continue reading

The post Microsoft ushers in AI-native era with open agentic stack, Linux updates appeared first on SD Times.

Why I Built All 170 Tools to Run in the Browser

When I started building UtilVox, the obvious
approach was server-side processing. Upload file →
process on server → return result. Every major
tool site works this way.

I went the opposite direction. Here’s why —
and what I learned.

The Problem With Server-Side Tool Sites

Most free online tools have a dirty secret:

Your files go to their servers.

When you “compress” a PDF on a popular site,
that file travels to their infrastructure,
gets processed, stored (temporarily or permanently),
and returned. You’re trusting a random website
with potentially sensitive documents.

Contracts. Medical records. Financial statements.
Tax documents. People upload all of this to
“free” PDF tools without thinking about it.

The Client-Side Approach

I rebuilt everything using browser APIs:

• PDF processing → PDF.js + client-side compression
• Image manipulation → Canvas API + WebAssembly
• Currency conversion → Client fetches from forex API directly
• JWT decoding → Pure JavaScript (it’s just Base64)
• JSON formatting → JSON.parse() + JSON.stringify()

The result: your files never leave your device.

The Tradeoffs

Nothing is free. Client-side processing has limits:

Memory constraints
Large files (50MB+ PDFs) can crash browser tabs
on low-memory devices. Server processing handles
this better.

Processing speed
WebAssembly is fast but not as fast as native
server code for heavy operations like OCR.

No persistence
Can’t save user history, preferences, or
previous uploads without a backend.

For 90% of use cases, these tradeoffs are
worth it. The 10% who need server-side power
have Adobe Acrobat.

The Stack

• Next.js 14 App Router — Server Components
  for fast LCP, Client Components for interactivity
• TypeScript — 170 tools, type safety is essential
• Tailwind CSS — consistent UI across every tool
• Vercel — edge deployment, global CDN
• Cloudflare — DNS, DDoS protection

What I’d Do Differently

Ship faster. I spent too long perfecting
individual tools before launching. Users don’t
care about perfection — they care about
whether the tool works.

Build in public from day one. The tools that
got the most early traffic were ones I tweeted
about while building.

Current Status

170+ tools live at utilvox.com.

Working on: SEO, backlinks, and adding
requested tools from user feedback.

If you’re building something similar or have
questions about the architecture — ask below.

Transactional Email: Definition and Characteristics

Transactional emails are automated, triggered by a specific user action:

• Order confirmation
• Password reset
• Shipping notification
• Account verification
• Payment receipt
• Two-factor authentication codes

Characteristics:

• One-to-one communication (1 recipient per message)
• High individual value, low total volume
• Immediate delivery required (< 30 seconds SLA)
• Highly personalized content
• Must reach inbox — users are waiting for these
• Low complaint risk (user requested it)

SLA requirements:

• 99.9%+ delivery success rate
• < 30 second end-to-end latency
• 24/7 availability (no maintenance windows)

Bulk Email: Definition and Characteristics

Bulk (marketing) emails are one-to-many:

• Newsletters
• Promotional campaigns
• Product announcements
• Re-engagement campaigns
• Retention campaigns

Characteristics:

• One-to-many (single campaign → thousands/millions of recipients)
• High total volume, moderate individual value
• Delivery speed less critical (hours acceptable)
• Campaign-level tracking (open rates, click rates)
• Higher complaint risk (recipients may not have opted in)
• CAN-SPAM and GDPR compliance required

SLA requirements:

• 95%+ delivery success rate
• < 4 hour campaign completion
• List-unsubscribe compliance (RFC 8058)
• Unsubscribe processing within 10 days (CAN-SPAM)

Why Separation Matters

Problem 1: Marketing Traffic Competes With Transactional

If your marketing campaign sends 500K emails over 2 hours, it consumes MTA resources (connections, queue slots, CPU) that your transactional emails need. The result: password resets arriving 10 minutes late.

Problem 2: Reputation Contamination

One bad marketing campaign (high bounce rate, complaints) can damage your IP reputation — which affects your transactional emails’ inbox placement.

Problem 3: Compliance Conflicts

Marketing email requires List-Unsubscribe headers (RFC 8058) and opt-out mechanisms. Transactional email doesn’t. Mixing them in one queue creates compliance complexity.

Problem 4: Monitoring Complexity

Blending transactional and bulk metrics makes it impossible to know if your transactional deliverability is healthy.

Architecture: Separate MTA Stacks

Recommended Architecture for 5M+/month Senders

┌─────────────────────────────────────────────────────────┐
│              Application Layer                          │
│   (Orders, Auth, Marketing Platform, CRM)               │
└──────────────────────┬──────────────────────────────────┘
                       │
         ┌─────────────┴──────────────┐
         │                            │
┌────────▼─────────┐      ┌──────────▼──────────┐
│  Transactional   │      │   Bulk/Marketing     │
│  SMTP Relay       │      │   SMTP Relay         │
│  (KumoMTA-1)      │      │  (KumoMTA-2)         │
│                   │      │                      │
│  - High priority  │      │  - Normal priority   │
│  - 2s SLA         │      │  - 4h campaign SLA   │
│  - Separate IPs   │      │  - Separate IPs       │
│  - P0 alerting    │      │  - P1 alerting        │
└────────┬─────────┘      └──────────┬──────────┘
         │                             │
┌────────▼─────────┐      ┌──────────▼──────────┐
│  Dedicated        │      │  Dedicated           │
│  IPs (warm,       │      │  IPs (warm,         │
│  established rep) │      │  separate rep)      │
└───────────────────┘      └─────────────────────┘

Separate DKIM and Domains

Transactional:

• From: [email protected]
• DKIM: mail._domainkey.mx.example.com
• Separate reputation for critical sending

Bulk/Marketing:

• From: [email protected]
• DKIM: mail._domainkey.example.com
• More tolerant reputation risk

KumoMTA Configuration: Transactional vs Bulk

Transactional Configuration (High Priority)

-- /etc/kumomta/transactional.conf

-- High-priority SMTP listener
kumo.start_smtp_listener {
    listen = "[::]:2525",
    name = "transactional",
    relay_hosts = { "10.0.0.0/8" },
    auth_require_tls = true,
}

-- Prometheus metrics (separate port)
kumo.start_http_listener {
    listen = "[::]:2001",
    trusted_hosts = { "127.0.0.1" },
}

-- Minimal queue depth for low latency
kumo.configure_queue {
    max_queue_depth = 5000,
    retry_interval = "1m",
    max_retry_age = "24h",
}

-- DKIM signing
kumo.configure_dkim_signing {
    domain = "mx.example.com",
    selector = "mail",
    key_file = "/etc/kumomta/keys/mail._domainkey.mx.example.com.pem",
}

Bulk Configuration (Normal Priority)

-- /etc/kumomta/bulk.conf

-- Bulk/marketing listener
kumo.start_smtp_listener {
    listen = "[::]:2526",
    name = "bulk",
    relay_hosts = { "10.0.0.0/8" },
    auth_require_tls = true,
}

-- Prometheus metrics (separate port)
kumo.start_http_listener {
    listen = "[::]:2002",
    trusted_hosts = { "127.0.0.1" },
}

-- Higher queue depth for volume
kumo.configure_queue {
    max_queue_depth = 100000,
    retry_interval = "5m",
    max_retry_age = "72h",
}

-- DKIM signing
kumo.configure_dkim_signing {
    domain = "example.com",
    selector = "mail",
    key_file = "/etc/kumomta/keys/mail._domainkey.example.com.pem",
}

-- RFC 8058 List-Unsubscribe headers
kumo.on("smtp_message_received", function(domain, meta)
    local headers = meta.headers or {}

    -- Only add for bulk campaigns
    if headers["X-Campaign-Type"] == "marketing" then
        kumo.add_header("List-Unsubscribe",
            "<mailto:[email protected]?subject=unsubscribe>")
        kumo.add_header("List-Unsubscribe-Post",
            "List-Unsubscribe=One-Click")
        kumo.add_header("Precedence", "bulk")
    end
end)

Compliance: CAN-SPAM and GDPR

Transactional Exemption

Key fact: CAN-SPAM exempts transactional emails from:**

• Physical postal address requirements
• Opt-out link requirements (though still recommended)

Transactional exemption applies when:

• Email is to facilitate an existing transaction
• Email is about a purchase or account status
• Email is a one-to-one communication

Marketing emails are NOT exempt:

• Newsletters, promotions, announcements
• Re-engagement campaigns
• Non-triggered educational content

GDPR Considerations

For bulk sending to EU residents:

• Explicit consent required before sending
• Double opt-in recommended
• Clear unsubscribe mechanism
• Data minimization (don’t retain more than needed)

When NOT to Separate

Separating transactional and bulk infrastructure adds operational complexity. Don’t separate if:

• Your total volume is under 500K/month
• Your transactional volume is under 10K/month
• You have no engineering capacity to manage two stacks
• Your marketing and transactional emails come from the same product (e.g., a marketplace where order confirmations ARE your marketing)

In these cases, use a single MTA with traffic shaping to prioritize transactional:

kumo.on("smtp_message_received", function(domain, meta)
    local headers = meta.headers or {}
    if headers["X-Priority"] == "high" then
        kumo.set_queue_priority("high")
    end
end)

Monitoring: Separate Metrics for Each

Transactional Metrics Dashboard

Bulk Campaign Metrics Dashboard

FAQ

Q: Can I use the same domain for transactional and bulk email?
A: Technically yes, but not recommended. If your bulk sending damages the domain’s reputation, your transactional emails suffer too. Use subdomains (e.g., mx.example.com for transactional, example.com for bulk).

Q: Should I use separate IP addresses for transactional and bulk?
A: Yes — always. This is the most effective way to prevent reputation cross-contamination. Your transactional IP should have established, pristine reputation. Your bulk IP(s) can absorb more risk.

Q: Can I send transactional and bulk through the same KumoMTA instance?
A: Yes, using Lua policies to route and prioritize differently. But for high-volume operations (10M+/month), separate instances on separate infrastructure provide better isolation.

Q: Does SendGrid/Mailgun separate transactional and bulk?
A: Yes — both have separate APIs and infrastructure for transactional (via SMTP/API) and marketing (via marketing campaigns). This is one reason enterprise senders often migrate to self-hosted KumoMTA for full control.

Q: What’s the minimum volume where separation becomes worth it?
A: When your bulk campaigns regularly exceed 100K emails/session, or when transactional SLA < 30s is business-critical. For most organizations, this is around 2-5M total monthly volume.

Get Help With Email Architecture

PostMTA designs email infrastructure for high-volume senders:

• Transactional/bulk separation architecture
• KumoMTA multi-stack configuration
• Compliance audit (CAN-SPAM, GDPR)
• Reputation management and IP strategy

👉 Talk to our infrastructure team →

For related guides, see SMTP Relay Setup Guide, IP Warmup Strategies, and KumoMTA Setup Guide.

References: RFC 8058 (List-Unsubscribe) | CAN-SPAM Requirements

Cross-posted from my Medium article.

Migrating 200+ Microsites to a Multi-Tenant CMS: Architecture Patterns That Scale

Lessons from consolidating fragmented web properties into a scalable, reusable, governance-friendly digital platform.

Many enterprises accumulate dozens — sometimes hundreds — of microsites over time.

A product team launches one site. A regional team launches another. A campaign creates a temporary site that becomes permanent. A business unit chooses a different template, plugin, hosting model, or content workflow. Over several years, what started as flexibility becomes fragmentation.

At small scale, this may look manageable. At enterprise scale, it creates real operational cost.

Teams begin dealing with duplicate codebases, inconsistent user experience, fragmented SEO, accessibility gaps, security patching complexity, slow global updates, and unclear ownership. Even simple changes — such as updating a header, footer, privacy notice, tracking script, or accessibility component — can become a large coordination effort.

A multi-tenant CMS architecture can help solve this problem.

But successful migration is not just about moving content from old sites into a new CMS. It is about creating a reusable digital platform with shared templates, configurable components, consistent governance, automated delivery, and enough local flexibility for business teams to manage their own content.

This article outlines practical architecture patterns for migrating large groups of microsites into a scalable, reusable, governance-friendly CMS platform.

The Problem With Microsite Sprawl

Microsites usually begin with good intentions.

A team needs speed. A business unit needs independence. A campaign needs a custom experience. A regional group needs local control. Those needs are valid.

The problem appears when every microsite becomes its own mini-platform.

Over time, the enterprise may end up with many different codebases, hosting models, templates, plugins, tracking scripts, accessibility patterns, content workflows, and release processes. This creates fragmentation across technology, content, operations, compliance, and user experience.

Common symptoms include duplicate codebases, inconsistent branding, multiple versions of headers and footers, uneven accessibility compliance, fragmented SEO, different analytics implementations, slow global changes, and high dependency on developers for basic content updates.

The hidden cost is not just technical debt. It is organizational drag.

When simple changes require coordination across dozens or hundreds of sites, the enterprise loses speed. When every site behaves differently, users lose consistency. When governance is unclear, risk increases.

That is why large-scale microsite migration should not be treated as a lift-and-shift exercise. It should be treated as platform modernization.

Why Multi-Tenant CMS Architecture Helps

A multi-tenant CMS architecture allows one platform to support many sites while sharing common capabilities.

Instead of every site having its own templates, components, deployment pipeline, and governance model, a shared platform provides reusable foundations. Individual sites can still maintain local identity and content ownership, but they operate within a consistent architecture.

A good multi-tenant CMS model typically includes shared templates, reusable widgets, common security patterns, standardized analytics, centralized DevSecOps pipelines, consistent accessibility practices, and role-based content governance.

The goal is balance.

Too much central control creates bottlenecks. Too much local freedom recreates fragmentation.

The architecture should give central teams control over platform standards while giving local teams enough flexibility to manage content without developer involvement for every change.

That balance is where multi-tenant CMS architecture becomes powerful.

Pattern 1: Parent/Child Site Architecture

One useful pattern is a parent/child site model.

In this model, a parent or global layer provides shared platform capabilities. Child sites inherit those capabilities while maintaining local content, navigation, and business-specific pages.

The parent layer may define global templates, shared themes, header and footer structure, common navigation patterns, shared assets, analytics configuration, accessibility standards, reusable content blocks, and approved widgets.

Child sites can then use those shared assets while customizing local pages, service lines, landing pages, location information, or business-specific content.

This pattern helps reduce duplication.

For example, if the enterprise needs to update a global footer, privacy link, analytics script, or accessibility component, the change can be made at the shared layer and propagated across sites. Without this architecture, the same change may require separate updates across dozens or hundreds of properties.

The key design question is simple:

What should be inherited globally, and what should remain local?

A scalable architecture defines this boundary clearly.

Pattern 2: Reusable Widgets and Components

A multi-tenant CMS succeeds or fails based on its component model.

If every page requires custom development, the platform will not scale. Content authors will remain dependent on developers, release cycles will stay slow, and the enterprise will continue accumulating one-off solutions.

Reusable widgets and components solve this problem.

Instead of building hundreds of custom page variations, architects can create configurable building blocks such as hero banners, content cards, location finders, call-to-action sections, accordions, forms, search modules, alert banners, and related content sections.

The important word is configurable.

A reusable component should support controlled variation without becoming a free-for-all. Authors should be able to adjust content, ordering, imagery, labels, and layout options within approved boundaries.

This improves delivery speed, brand consistency, accessibility compliance, testing efficiency, reuse across sites, maintainability, and author independence.

The best component libraries are designed with both developers and content authors in mind.

Developers need clean architecture and maintainable code. Authors need practical flexibility. Users need consistency.

Pattern 3: Shared Content With Local Overrides

Large enterprises often have content that applies across many sites.

Examples may include service descriptions, compliance notices, policies, campaign messages, brand assets, or standard calls to action.

Duplicating that content across many sites creates maintenance risk. If content changes, every duplicate must be updated. Inevitably, some copies become outdated.

Shared content reduces that problem.

A strong CMS architecture should support global content blocks, shared descriptions, reusable metadata, common disclaimers, shared media assets, localized variants, regional overrides, approval workflows, and clear content ownership.

But shared content alone is not enough. Local teams often need flexibility.

That is where local overrides matter.

A scalable model allows central teams to define standard content while allowing local teams to override specific fields where appropriate. The architecture should define which fields are global, which are local, and which require approval.

Without those rules, shared content becomes either too rigid or too chaotic.

Good governance turns shared content from a technical feature into an operating model.

Pattern 4: Centralized DevSecOps and Release Management

A multi-tenant CMS platform is not just a content platform. It is also a delivery platform.

If each site has its own deployment process, release calendar, testing strategy, and rollback method, the enterprise still has operational fragmentation.

Centralized DevSecOps helps standardize delivery.

Important practices include common source control, shared CI/CD pipelines, automated build and deployment, environment consistency, security scanning, dependency scanning, accessibility testing, regression testing, performance checks, release approvals, rollback plans, monitoring, and alerting.

This matters because platform changes affect many sites.

A small component change could impact dozens of pages across multiple properties. A shared template change could affect an entire portfolio. A tracking script update could affect analytics across the enterprise.

That requires disciplined release management.

Automation helps, but governance is equally important. Teams need clear rules for what can be released independently, what requires regression testing, and what needs broader stakeholder review.

The larger the platform, the more important release discipline becomes.

Pattern 5: Migration Factory Approach

Migrating hundreds of microsites cannot be handled as a collection of one-off projects.

A repeatable migration factory approach works better.

The migration factory model starts with inventory. Teams identify existing sites, group them by template and content pattern, map old pages to new structures, clean up outdated content, define migration waves, and create repeatable QA checklists.

The first few migrations may be slower because the team is building the playbook. Later migrations become faster because patterns repeat.

This approach also helps with estimation. Once site types are grouped, teams can better predict effort based on complexity rather than treating every site as unique.

The goal is not to eliminate all variation.

The goal is to reduce unnecessary variation.

A good migration factory creates repeatable execution without ignoring legitimate business differences.

Metrics That Matter

Large CMS migrations should be measured.

Without metrics, teams may only know that the migration was completed. They may not know whether the platform actually improved delivery, quality, performance, or maintainability.

Useful metrics include release cycle time, deployment frequency, content publishing velocity, number of reusable components, reduction in custom code, page performance, mobile performance, accessibility score, SEO health, regression testing effort, support tickets, and time required for global updates.

Metrics help prove whether the architecture is working.

For example, if global updates still take weeks, the shared architecture may not be shared enough. If content authors still require developers for basic page updates, the component model may be too rigid. If accessibility issues keep recurring, accessibility may not be built into components and templates.

The right metrics reveal where the platform needs improvement.

Common Mistakes

Large-scale CMS migrations fail or underperform when teams treat the migration as a cosmetic redesign or a content copy exercise.

One common mistake is rebuilding every old site exactly as-is. That preserves old problems inside a new platform. Migration is an opportunity to simplify.

Another mistake is allowing too much customization. Excessive customization recreates fragmentation. The platform needs controlled flexibility.

Teams also underestimate content governance. Without ownership rules, content becomes outdated quickly.

Accessibility is another common gap. It should be built into templates and components from the beginning, not treated as a late-stage checklist item.

Content cleanup also matters. Bad content in a better CMS is still bad content.

Finally, author training is often underestimated. A platform only works if content teams know how to use it properly.

Avoiding these mistakes requires architecture discipline and operating discipline.

Practical Architecture Checklist

Before migrating microsites into a multi-tenant CMS, architects should answer several questions:

• What is the tenant model?
• Which capabilities are global?
• Which capabilities are local?
• What content should be shared?
• What content can be overridden?
• What templates are standardized?
• What components or widgets are reusable?
• Who owns global content?
• Who owns local content?
• What approval workflows are needed?
• How are accessibility requirements enforced?
• How are SEO standards enforced?
• What analytics model will be used?
• How are deployments automated?
• What regression testing is required?
• How will performance be measured?
• What is the rollback plan?
• How will content authors be trained?
• How will platform adoption be measured?

A checklist does not replace architecture, but it helps keep the migration honest.

Conclusion

A CMS migration is not just a content migration.

It is platform modernization.

When enterprises consolidate large numbers of microsites, the real value comes from reusable architecture, consistent governance, shared components, automated delivery, and clear operating models.

A well-designed multi-tenant CMS can reduce duplication, improve consistency, accelerate global changes, strengthen accessibility, improve maintainability, and give content teams more independence.

But the technology alone is not enough.

The difference between another fragmented platform and a scalable digital foundation is architecture discipline.

Originally published on Medium:

https://medium.com/@anujagrawal4/migrating-200-microsites-to-a-multi-tenant-cms-architecture-patterns-that-scale-b2da69ee69b4

The views expressed here are my own and are based on general enterprise architecture experience. They do not represent any current or former employer or client.

What Is an SMTP Relay Server?

An SMTP relay accepts outbound email from your applications and delivers it to the final destination mail servers (Gmail, Outlook, Yahoo, etc.). Unlike a local MTA that handles both inbound and outbound, a relay focuses purely on outbound delivery optimization.

Typical architecture:

Application → SMTP Relay → Internet → Recipient Mail Server
              (KumoMTA)   (TLS)

The relay handles:

• Message queuing and retry logic
• TLS encryption with certificate management
• Rate limiting and traffic shaping
• DKIM signing and SPF passthrough
• Bounce processing and delivery tracking

Self-Hosted vs Cloud SMTP Relay

Choose self-hosted if: You send > 5M emails/month, have engineering capacity, need full compliance control, or want to eliminate per-email pricing.

Choose cloud SMTP if: You’re under 1M emails/month, have no infra engineering, or need rapid setup without infrastructure management.

KumoMTA as SMTP Relay: Production Configuration

Core Relay Configuration

-- /etc/kumomta/relay.conf
-- Production SMTP relay configuration

-- SMTP Listener (accepts from internal apps)
kumo.start_smtp_listener {
    listen = "[::]:2525",  -- Internal relay port
    name = "relay-in",
    relay_hosts = { "10.0.0.0/8", "172.16.0.0/12" }, -- Internal networks only
    auth_require_tls = true, -- Require AUTH from application servers
}

-- HTTP API for application injection
kumo.start_http_listener {
    listen = "[::]:8080",
    trusted_hosts = { "10.0.0.0/8", "127.0.0.1" },
}

-- DKIM signing for all outbound
kumo.configure_dkim_signing {
    domain = "example.com",
    selector = "mail",
    key_file = "/etc/kumomta/keys/mail._domainkey.example.com.pem",
    headers = { "From", "To", "Subject", "Date", "Message-ID" },
}

-- TLS for outbound delivery
kumo.configure_tls {
    min_tls_version = "1.3",
    ciphers = "ECDHE-RSA-AES256-GCM-SHA384",
}

-- Prometheus metrics
kumo.start_http_listener {
    listen = "[::]:2000",
    trusted_hosts = { "127.0.0.1" },
}

Application Integration via HTTP API

Applications inject mail via KumoMTA’s HTTP API:

curl -X POST http://kumomta-relay:8080/v1/message 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]", "[email protected]"],
    "subject": "Your Order #12345 Has Shipped",
    "headers": {
      "X-Order-ID": "12345",
      "X-Campaign": "shipping-confirmation"
    },
    "html": "<h1>Your order is on its way!</h1>",
    "text": "Your order #12345 has shipped. Track at: https://track.example.com/12345"
  }'

Multi-Tenant Relay Configuration

For SaaS platforms sending on behalf of customers:

-- Per-customer relay configuration
kumo.on("smtp_server_greeting", function(domain, meta)
    local tenant = meta.tenant

    if tenant then
        -- Apply per-tenant rate limits
        local limit = get_tenant_rate_limit(tenant)
        kumo.limit_sending(tenant, limit, { per = "minute" })

        -- Set tenant-specific DKIM
        local dkim = get_tenant_dkim(tenant)
        if dkim then
            kumo.sign_dkim(dkim.domain, dkim.selector, dkim.key_file)
        end
    end
end)

Security: TLS, AUTH, and IP Allowlisting

TLS Configuration (Required for 2026)

-- Enforce TLS 1.3 for all delivery
kumo.configure_tls {
    min_tls_version = "1.3",
    prefer_server_ciphers = true,
}

-- For submission ports (SMTPS)
kumo.start_smtp_listener {
    listen = "[::]:465",
    name = "smtps",
    tls = {
        cert_file = "/etc/kumomta/tls/server.crt",
        key_file = "/etc/kumomta/tls/server.key",
    },
}

Generate self-signed certificates for testing:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes 
  -subj "/CN=mail.example.com"

SMTP AUTH Configuration

-- Require AUTH for submission port
kumo.start_smtp_listener {
    listen = "[::]:587",
    name = "submission",
    auth_require_tls = true,
    -- Supported mechanisms
    auth_mechanisms = { "PLAIN", "LOGIN", "CRAM-MD5" },
}

Application authentication (for HTTP API):

-- API key validation
kumo.on("http_request", function(request)
    local token = request.headers["Authorization"]:gsub("Bearer ", "")
    if not validate_api_key(token) then
        return { status = 401, body = "Unauthorized" }
    end
end)

IP Allowlisting

-- Only accept connections from trusted IPs
kumo.start_smtp_listener {
    listen = "[::]:2525",
    name = "relay-in",
    relay_hosts = { "10.0.0.0/8", "172.16.0.0/12" },
    -- Deny all other IPs
}

For additional security with cloud applications:

# Firewall: only allow specific application server IPs
sudo ufw allow from 10.0.1.0/24 to any port 2525
sudo ufw allow from 10.0.2.0/24 to any port 2525

Performance Tuning for High-Volume Relay

Connection and Thread Tuning

-- /etc/kumomta/tuning.conf

-- Delivery threads (scale with CPU cores)
kumo.configure_delivery {
    threads = 16, -- 2x CPU cores
    max_connections_per_domain = 10,
    max_message_rate = 1000, -- per minute per domain
}

-- Queue management
kumo.configure_queue {
    max_queue_depth = 100000,
    retry_interval = "5m",
    max_retry_age = "72h",
    dead_letter_after = "7d",
}

Monitoring Metrics

Key metrics to track:

SMTP Relay for Specific Use Cases

Transactional Email (Order Confirmations, Password Resets)

Requirements:

• Immediate delivery (< 30 seconds end-to-end)
• High reliability (99.9% success rate)
• DKIM signing required
• Low volume per user, high total volume

-- Transactional: low latency priority
kumo.on("smtp_message_received", function(domain, meta)
    local headers = meta.headers or {}
    if headers["X-Type"] == "transactional" then
        -- Elevate priority
        kumo.set_queue_priority("high")
    end
end)

Bulk/Marketing Email

Requirements:

• High throughput (100K+ emails/hour)
• Per-campaign tracking
• Bounce processing integration
• List unsubscribe handling (RFC 8058)

-- Bulk: throughput priority
kumo.on("smtp_message_received", function(domain, meta)
    local headers = meta.headers or {}
    local campaign = headers["X-Campaign"]

    if campaign then
        -- Track campaign metrics
        increment_campaign_metric(campaign, "queued")
    end
end)

-- List-Unsubscribe header (RFC 8058 - required for bulk)
kumo.on("smtp_message_received", function(domain, meta)
    if is_bulk_campaign(meta.headers) then
        kumo.add_header("List-Unsubscribe", "<mailto:[email protected]?subject=unsubscribe>")
        kumo.add_header("List-Unsubscribe-Post", "List-Unsubscribe=One-Click")
    end
end)

Troubleshooting Common SMTP Relay Issues

Issue: Connection Timeout / Slow Delivery

Cause: Network latency, remote MX throttling, or TLS negotiation failure
Fix:

# Test SMTP connectivity
telnet gmail-smtp-in.l.google.com 25

# Check TLS
openssl s_client -connect gmail-smtp-in.l.google.com:25 -starttls smtp

# Check KumoMTA queue
curl http://localhost:2000/metrics | grep queue_depth

Issue: 421/429 Throttling from Gmail/MS

Cause: ISP is throttling your IP — you’re sending too fast
Fix: Implement adaptive throttling in your relay policy:

kumo.on("smtp_delivery_result", function(result, meta)
    if result.code == 421 or result.code == 429 then
        -- Reduce rate by 30%
        adjust_domain_rate(meta.domain, -0.3)
        log_warn("Throttled by " .. meta.domain .. ", reducing rate")
    end
end)

Issue: TLS Handshake Failures

Cause: Outdated TLS config or untrusted certificate
Fix: Ensure min_tls_version = "1.2" minimum (1.3 preferred). Check certificate expiration:

openssl x509 -in /etc/kumomta/tls/server.crt -noout -dates

FAQ

Q: What’s the difference between SMTP port 25, 465, and 587?
A: Port 25 is the standard MX port (server-to-server delivery). Port 465 (SMTPS) is for legacy submission with implicit TLS. Port 587 (Submission) is the modern standard for application-to-relay submission with explicit STARTTLS. Use 587 for your application relay integration.

Q: Can KumoMTA relay from Postfix?
A: Yes. Configure Postfix to relay to KumoMTA on an internal port:

relayhost = [kumomta.internal]:2525

Q: How do I handle SMTP relay for WordPress/WooCommerce?
A: Install WP Mail SMTP plugin, configure it to point to your KumoMTA relay at kumomta.example.com:587 with AUTH credentials. KumoMTA will DKIM-sign and deliver all WordPress mail.

Q: Is port 25 blocked by cloud providers — what do I do?
A: Most cloud providers (AWS, GCP, Azure) block port 25 by default. Solutions: (1) Use port 587 submission instead, (2) request port 25 unblock from your provider, (3) use a dedicated SMTP relay service for the “last mile” if needed.

Q: How does KumoMTA compare to Postfix for relay use?
A: KumoMTA has superior multi-tenant traffic shaping, built-in DKIM, and Prometheus metrics. Postfix requires external tools (OpenDKIM, policyd) for equivalent functionality. For high-volume relay, KumoMTA is significantly easier to operate.

Get Help With SMTP Relay Setup

PostMTA provides:

• Production KumoMTA relay configuration and deployment
• Secure TLS and AUTH setup
• Multi-tenant relay for SaaS platforms
• Integration with existing applications (WordPress, Shopify, custom)
• 24/7 relay monitoring and alerting

👉 Get SMTP relay consulting →

For related guides, see KumoMTA Setup Guide, Email Authentication Guide, and Open Source Email Infrastructure.

References: RFC 5321 (SMTP) | RFC 8460 (SMTP TLS Reporting)

“𝗛𝗼𝘄 𝗱𝗼 𝘆𝗼𝘂 𝗽𝗿𝗲𝘃𝗲𝗻𝘁 𝗨𝗜 𝗹𝗮𝗴 𝘄𝗵𝗲𝗻 𝗿𝗲𝗰𝗲𝗶𝘃𝗶𝗻𝗴 𝗼𝘃𝗲𝗿 𝟭𝟬𝟬 𝗪𝗲𝗯𝗦𝗼𝗰𝗸𝗲𝘁 𝗲𝘃𝗲𝗻𝘁𝘀 𝗽𝗲𝗿 𝘀𝗲𝗰𝗼𝗻𝗱?”

They clarified that the issue is not related to the server or backend but rather how to approach and resolve it on the frontend.

This made me think for a while, and then I realized that we often use these techniques—knowingly or unknowingly. We are familiar with these concepts, but they often come with technical jargon.

Let me explain these techniques as simply as possible.

To stop UI lag from 100+ WebSocket events per second, you must decouple the high-frequency message stream from the main rendering thread.
Throttle or buffer the events, batch your DOM updates using requestAnimationFrame, and offload heavy processing to a Web Worker.

Implementing these targeted strategies will stabilize your frame rate:

1. Throttle or Buffer the Event Stream
Never update the UI on every single WebSocket message. At 100+ events per second, your browser is forced into constant layout recalculations (reflows) and repaints.
  • 𝗧𝗵𝗿𝗼𝘁𝘁𝗹𝗶𝗻𝗴: Use libraries like Lodash to limit state updates to a maximum of 10–15 frames per second
  • 𝗕𝘂𝗳𝗳𝗲𝗿𝗶𝗻𝗴: Push incoming events into an array. Set up an interval or a requestAnimationFrame loop that drains this array, processes the aggregated data, and updates the UI once per cycle.

𝟮. 𝗕𝗮𝘁𝗰𝗵 𝗗𝗢𝗠 𝗨𝗽𝗱𝗮𝘁𝗲𝘀
If you are updating UI components individually for every event, you will overwhelm the event loop.
  • Batch multiple data points into a single state update.
  • Use requestAnimationFrame to schedule your DOM updates so they align perfectly with the browser’s refresh rate.

𝟯. 𝗢𝗳𝗳𝗹𝗼𝗮𝗱 𝗛𝗲𝗮𝘃𝘆 𝗣𝗿𝗼𝗰𝗲𝘀𝘀𝗶𝗻𝗴 𝘁𝗼 𝗮 𝗪𝗲𝗯 𝗪𝗼𝗿𝗸𝗲𝗿
  • If you need to parse, filter, or transform the incoming payload data before displaying it, do not do this on the main JavaScript thread.
  • Move your WebSocket connection and data parsing logic into a Web Worker.
  • The worker can handle the 100+ events per second, aggregate or reduce the data, and only send a condensed, render-ready payload back to the main UI thread periodically.

𝟰. 𝗢𝗽𝘁𝗶𝗺𝗶𝘇𝗲 𝗥𝗲𝗮𝗰𝘁𝗶𝘃𝗶𝘁𝘆 𝗮𝗻𝗱 𝗖𝗼𝗺𝗽𝗼𝗻𝗲𝗻𝘁 𝗥𝗲𝗻𝗱𝗲𝗿𝗶𝗻𝗴
If you are using frameworks like React, Vue, or Angular, uncontrolled state updates will trigger massive re-render cascades.
  • 𝗥𝗲𝗮𝗰𝘁: Use useMemo and useCallback to prevent unnecessary component re-renders. Avoid storing rapidly changing WebSocket data directly in component state; instead, use a mutable ref for the raw data and sync to state on a throttled interval.
  • 𝗩𝗶𝗿𝘁𝘂𝗮𝗹𝗶𝘇𝗮𝘁𝗶𝗼𝗻: If rendering these events in a list or table, use windowing libraries (like TanStack Table or Virtuoso) so the DOM only renders the rows currently visible on the screen.

𝟱. 𝗨𝘁𝗶𝗹𝗶𝘇𝗲 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁 𝗙𝗿𝗮𝗴𝗺𝗲𝗻𝘁𝘀
For vanilla JavaScript implementations, avoid appending elements to the DOM in a loop. Instead, create a DocumentFragment, append your newly processed elements to it, and then append the entire fragment to the live DOM in one single operation

WebSockets #ReactJS #Frontend #JavaScript #Performance #SystemDesign #InterviewPrep #EngineeringMindset

Originally published at harshit.cloud on 2026-05-08.

If you’re reading this, there’s roughly an 80% chance your company rolled out an MDM last quarter, your network team wedged Claude API traffic through an AI gateway around the same time, and now Claude Code boots with MCPs you didn’t pick while forwarding your prompts somewhere you haven’t audited. /mcp shows three servers nothing in your repo touches. env | grep ANTHROPIC returns a base URL on a domain you’ve never seen. The experience got worse and nobody asked you.

This post covers both leashes. The MDM one is fixable in 12 lines of zsh. The AI gateway one depends on how deep your network team went.

what’s an MDM, in three sentences

MDM stands for Mobile Device Management. Jamf, Kandji, Intune, Workspace ONE, whichever agent enrolled your laptop on day one. It owns parts of /Library, can write files there as root with the system-immutable flag set, and re-pushes them on a schedule, which is why a plain rm doesn’t survive. For Claude Code, the relevant directory is /Library/Application Support/ClaudeCode/.

the managed-settings situation

The two files doing the work are /Library/Application Support/ClaudeCode/managed-settings.json and /Library/Application Support/ClaudeCode/managed-mcp.json. Claude Code reads them on startup, treats them as the highest-priority settings layer, and merges them over whatever you have in ~/.claude/settings.json. Anything IT puts in there wins: forced MCPs, forced skills, allowed and denied permission lists, and the env block that can set ANTHROPIC_BASE_URL. That last one is how the AI gateway routing gets wired into Claude Code in the first place.

why rm doesn’t work

First instinct fails, and not in a way that’s obvious:

sudo rm "/Library/Application Support/ClaudeCode/managed-settings.json"
# rm: managed-settings.json: Operation not permitted

Root isn’t enough. The MDM agent sets the file’s system-immutable flag with chflags schg after writing it. That flag blocks deletion even by root until it’s cleared. The macOS chflags(1) man page is the receipt. schg is the “system immutable” flag, and the file “may not be changed, moved, or deleted” while it’s set.

Confirm it on your own machine:

ls -lO "/Library/Application Support/ClaudeCode/managed-settings.json"
# -rw-r--r--  1 root  wheel  schg  482 May 14 09:11 managed-settings.json

schg in column five is the marker.

The detail that matters: managed-settings.json is the same config layer your ~/.claude/settings.json uses. The IT copy just lives under /Library, is owned by root, and has the schg flag set. The merge logic doesn’t know which file came from a human.

the cleanup script

One thing worth flagging before you run this. On macOS, the schg flag is normally clearable by root for files outside SIP-protected paths — and /Library/Application Support/ClaudeCode/ is not SIP-protected. So sudo chflags noschg works as written. If your MDM also writes its config into a SIP-protected location (rare for application config, more common for system extensions), you’d need Recovery Mode Terminal to clear those, which is a different conversation. The script’s 2>/dev/null will silently swallow that failure, so if reruns don’t seem to take, that’s where to look.

Save this as /usr/local/sbin/claudecode-cleanup.sh, make it executable, run with sudo:

#!/bin/zsh
FILES=(
  "/Library/Application Support/ClaudeCode/managed-settings.json"
  "/Library/Application Support/ClaudeCode/managed-mcp.json"
)
for f in "${FILES[@]}"; do
  # Clear immutable flag if file exists, then remove
  [ -e "$f" ] && /usr/bin/chflags noschg "$f" 2>/dev/null
  /bin/rm -f "$f"
done

sudo chmod 755 /usr/local/sbin/claudecode-cleanup.sh
sudo /usr/local/sbin/claudecode-cleanup.sh

Two lines do the real work. chflags noschg clears the immutable bit. rm -f removes the file. The 2>/dev/null swallows the noise on a clean machine where the file isn’t there.

Restart Claude Code. /mcp should be back to whatever you actually installed, and /permissions should be whatever’s in ~/.claude/settings.json instead of whatever IT decided you needed.

the launchd arms race

I’d love to tell you this is permanent. It isn’t.

MDM agents sync on a schedule. Every 15 minutes, every hour, on login, depending on profile. When they sync, they notice the file is gone, put it back, and re-apply the schg flag. You’ll watch managed-mcp.json reappear like a horror-movie villain you keep stabbing.

A few options, in increasing order of trouble you’re inviting:

• Run the script on a launchd LaunchAgent that fires at login. Once per session. Low impact, low effectiveness, but if your MDM only syncs at login this is enough.
• Run it on a launchd timer with a 60-second interval. Now you’re in an arms race with the sync schedule. Works until someone in IT notices a config-drift alert for your hostname.
• Block the MDM agent’s outbound DNS. Effective, loud, and the kind of thing that gets your laptop wiped on the next compliance audit.

I run the first one. The MDM gets its login telemetry, my dev environment isn’t broken for the hour or so between syncs, nobody opens a ticket. Pick the option that matches how much you actually want to fight this.

Minimal ~/Library/LaunchAgents/cloud.harshit.claudecode-cleanup.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>cloud.harshit.claudecode-cleanup</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/sudo</string>
    <string>-n</string>
    <string>/usr/local/sbin/claudecode-cleanup.sh</string>
  </array>
  <key>RunAtLoad</key><true/>
</dict>
</plist>

sudo -n only works if you’ve added a NOPASSWD line for that exact script in /etc/sudoers.d/claudecode-cleanup. Which the MDM might rewrite. The arms race goes deeper than you think.

the AI gateway angle

The other leash sits at the network layer. Companies route Claude API traffic through a gateway (Cloudflare AI Gateway, Portkey, LiteLLM, internal proxies) so they can log prompts, strip PII, enforce per-user quotas, or quietly downgrade Opus calls to Haiku when the monthly bill spikes. Claude Code respects ANTHROPIC_BASE_URL and will talk to whatever endpoint it points at, as long as your OAuth token or API key authenticates there.

Two routing patterns to recognize:

• The env block in managed-settings.json. IT sets ANTHROPIC_BASE_URL=https://ai-gw.corp.example.com/v1 inside the env section of the managed file. Claude Code reads it on startup. Same fix as the MCP file. The cleanup script above already kills this.
• System proxy plus a corporate root CA. Your laptop has a “Corporate Root CA” in keychain, and either an https.proxy setting or transparent network interception routes api.anthropic.com traffic through the gateway. Deleting managed-settings.json does nothing here. The interception lives below the application layer.

To tell which one you have, run this in a fresh shell:

env | grep -i anthropic
# If you see ANTHROPIC_BASE_URL, it's the env block.

curl -v https://api.anthropic.com/v1/messages 2>&1 | grep -iE 'issuer|subject|server certificate'
# If the cert chain is signed by your corporate CA, it's transparent interception.

bypassing the gateway

For the env-block case, the cleanup script already does the work. Restart your shell after running it:

unset ANTHROPIC_BASE_URL
env | grep -i anthropic
# (empty)

For the transparent-proxy case, your options shrink:

• Personal hotspot for sensitive sessions. Burns mobile data, leaves no trail through the gateway. Most realistic option for an individual contributor.
• WireGuard or Tailscale out to a personal node. Works if your MDM profile allows it. Many block third-party VPNs through com.apple.systempolicy.kernel-extension-policy.
• Personal device for personal work. Boring answer. The one that holds up in HR if it ever comes up.

What doesn’t work: removing the corporate root CA from keychain. It’s pinned by an MDM payload and gets re-added on next sync, same pattern as managed-settings.json.

should you actually do this

Worth saying out loud: both leashes exist because someone at your company had a reason. Compliance, data residency, an incident from six months ago whose postmortem nobody can find.

If the forced MCP is internal-secrets-lookup and the gateway logs prompts to a SOC pipeline, your team probably wants you using it. If the MCP is corporate-docs-mcp pointed at a 404 and the gateway downgrades Opus to Haiku because someone misread an invoice, you’re deleting dead weight.

The script doesn’t know which. Ask before you script. Most MDM platforms support per-user opt-out scopes, and one polite Slack message to IT beats a launchd plist.

what these scripts don’t do

The cleanup clears two files. It does not:

• Stop the MDM agent.
• Touch ~/.claude/settings.json. Your settings stay yours.
• Handle /Library/Application Support/ClaudeCode/managed-permissions.json if your MDM uses one. Add it to the FILES array.
• Survive a reboot or a sync. The agent re-pushes on next check-in.
• Defeat a transparent proxy with a pinned corporate CA. Use the hotspot.

If you wanted a permanent escape from corporate IT, you wouldn’t be reading a blog about chflags.