DEV Community: Yoni Ryabinski

Why a local SMTP catcher is not an email integration test

Yoni Ryabinski — Sat, 31 Oct 2026 20:47:54 +0000

Your Playwright test fills the signup form. The app sends the confirmation email. Mailpit shows the message with the right subject and link. The test passes.

Then staging sends the same email to a real address and nothing arrives.

The local catcher did its job. It proved the app opened an SMTP connection, built a MIME message, and rendered the template. It did not prove the message could reach an inbox.

What the catcher checks

Mailpit, MailHog, and similar tools are useful. They are fast, free, and easy to run in CI. They catch template errors, missing links, broken HTML, and the wrong recipient in the test payload. Keep them.

The problem starts when the local catcher is the only email test. It sits inside your network, so it never exercises the parts that decide whether a real message arrives.

What it cannot see

Failure	What the local catcher shows	What the real inbox shows
DNS or MX is wrong	The message is delivered locally	The message bounces or disappears
DKIM key was rotated	The message is signed with the old key	The message fails authentication
SPF or DMARC is misaligned	The message is accepted	The message is filtered or rejected
The provider is sandboxed	The message is delivered	Only allowlisted recipients receive it
Spam filtering rewrites a link	The link is intact	The link points somewhere else
The recipient is over quota	The message is delivered	The message is deferred or dropped

None of those failures need a code change to reproduce. They need a real address outside your network.

The pattern: one inbox per test run

Create a real inbox for the test, use its address in the form, wait for the message, assert its contents, then delete the inbox. The inbox can be a hosted service or a small internal service on your own domain. The test shape is the same.

const inbox = await inboxApi.create({ ttl: "15m" });

await page.fill("#email", inbox.address);
await page.click('button[type="submit"]');

const message = await inbox.waitForMessage({
  subject: /confirm/i,
  timeout: 30_000,
});

const link = message.links.find((url) => url.host === "app.example.com");
await page.goto(link);
await expect(page.getByText("Welcome")).toBeVisible();

The code assumes a small helper; the shape is the point, not the package. The helper is the part you build or buy. The assertions are the part that catches bugs:

The recipient is the exact per-run address, not a shared inbox.
The sender domain is yours.
SPF, DKIM, and DMARC pass.
The link host is on an allowlist. Never follow arbitrary links from email.
The OTP format and expiry match the product.
The message contains no real user data.

A few operational rules keep the test reliable:

One inbox per worker. A shared inbox gives parallel tests the same message.
Set a TTL and delete the inbox in teardown.
Log the message id, not the body.
Do not use a shared Gmail account. MFA, rate limits, and someone reading the inbox will break the test.

Keep the fast test

Run the local catcher on every commit. Run one real-inbox test on the staging deploy or nightly. The first catches template mistakes in seconds. The second catches the failures that only appear after the message leaves your network.

Replacing Mailpit with a real inbox makes the suite slower and more expensive. Replacing the real-inbox test with Mailpit makes the suite confident about the wrong thing.

Try one this week

If your suite only asserts against Mailpit, add one real-inbox test. Pick the signup email or the password reset, because those are the flows users notice first. Run it against staging once. If it passes, keep it in the nightly suite. If it fails, you found a bug your local tests could not see.

I work on Emcognito. We are testing a hosted version of this: a real address, an HTTP read, and a signed webhook. It is a waitlist, not a live product. If you run email tests, the page asks what you would pay: https://emcognito.com/test-inbox?src=devto. No card, and the article works without it.

How to Add Comments to an Eleventy Site (with a Custom Shortcode)

Yoni Ryabinski — Tue, 14 Apr 2026 13:23:26 +0000

Eleventy gets out of your way, which is great until you want a feature like comments and have to wire it up yourself. The cleanest answer: a hosted widget plus a custom shortcode so you can drop comments into any template with one line.

Here's how to add EchoThread (privacy-first, no ads, under 15 KB gzipped, free during beta) to an Eleventy site.

1. Get an API key

2. Set up env var loading

Install dotenv:

npm install --save-dev dotenv

.env:

ECHOTHREAD_API_KEY=YOUR_API_KEY

3. Add a shortcode in `.eleventy.js`

require("dotenv").config();

module.exports = function (eleventyConfig) {
  eleventyConfig.addShortcode("echothread", function () {
    const apiKey = process.env.ECHOTHREAD_API_KEY;
    if (!apiKey) return `<!-- EchoThread: missing key -->`;
    return `
<section class="echothread-wrapper">
  <div id="echothread" data-api-key="${apiKey}"></div>
  <script src="https://cdn.echothread.io/widget.js" defer></script>
</section>`;
  });

  return { dir: { input: "src", output: "_site" } };
};

4. Use it in your post layout

---
layout: layouts/base.njk
---
<article>
  <h1>{{ title }}</h1>
  {{ content | safe }}
  {% echothread %}
</article>

5. Make it opt-in (optional)

Add comments: true to a post's front matter, then:

{% if comments %}
  {% echothread %}
{% endif %}

6. Theme it

.echothread-wrapper {
  --echothread-bg: #fafafa;
  --echothread-text: #1a1a1a;
  --echothread-accent: #2563eb;
  min-height: 400px;
}

Done

The widget identifies threads by page URL automatically. Every post gets its own conversation, no extra config. Eleventy stays essentially zero-JS aside from the widget itself.

Full guide with troubleshooting: echothread.io/docs/guides/eleventy

How to Add Comments to a Hugo Site (Without a Backend)

Yoni Ryabinski — Fri, 10 Apr 2026 22:20:27 +0000

Hugo is wonderful for performance and terrible for anything stateful — including comments. If you want readers to talk back, you need a third-party widget that runs in the browser.

Here's the shortest path to threaded comments on a Hugo site, using EchoThread (privacy-first, no ads, no tracking, under 15 KB gzipped, free during beta).

1. Get an API key

2. Add the embed to `layouts/_default/single.html`

{{ define "main" }}
<article>
  <h1>{{ .Title }}</h1>
  {{ .Content }}
</article>

<section class="comments">
  <div id="echothread" data-api-key="{{ .Site.Params.echothreadApiKey }}"></div>
  <script src="https://cdn.echothread.io/widget.js" defer></script>
</section>
{{ end }}

3. Add the key to `hugo.toml`

[params]
  echothreadApiKey = "YOUR_API_KEY"

Or use an env var: HUGO_PARAMS_ECHOTHREADAPIKEY=... hugo. Hugo maps HUGO_PARAMS_* automatically.

4. (Optional) Make a shortcode

layouts/shortcodes/echothread.html:

<div class="echothread-wrapper">
  <div id="echothread" data-api-key="{{ .Site.Params.echothreadApiKey }}"></div>
  <script src="https://cdn.echothread.io/widget.js" defer></script>
</div>

Now you can drop {{< echothread >}} into any Markdown file.

5. Theme it

.comments {
  --echothread-bg: #0f0f10;
  --echothread-text: #e8e8ea;
  --echothread-accent: #7c5cff;
  min-height: 400px;
}

That min-height matters — it prevents layout shift when the widget hydrates.

Done

The widget identifies threads by page URL automatically, so every post gets its own conversation with no extra config. Sign in with Google to leave a comment, manage everything from the EchoThread dashboard.

Full guide with troubleshooting and CSP notes: echothread.io/docs/guides/hugo

How to Add Comments to an Astro Site (Lazy-Loaded, Zero JS by Default)

Yoni Ryabinski — Thu, 09 Apr 2026 20:38:55 +0000

Astro's "ship zero JavaScript by default" model is a perfect fit for comment widgets — they're the one thing on the page that actually needs to be interactive, and they're the perfect candidate for lazy loading.

Here's how to add EchoThread (privacy-first, no ads, under 15 KB gzipped, free during beta) to an Astro site as a reusable component.

1. Get an API key

2. Add the key to `.env`

PUBLIC_ECHOTHREAD_API_KEY=YOUR_API_KEY

The PUBLIC_ prefix is required to expose it client-side.

3. Create `src/components/EchoThread.astro`

---
const apiKey = import.meta.env.PUBLIC_ECHOTHREAD_API_KEY;
const { theme = "auto" } = Astro.props;
---

<section class="echothread-wrapper">
  <div id="echothread" data-api-key={apiKey} data-theme={theme}></div>
  <script src="https://cdn.echothread.io/widget.js" defer></script>
</section>

<style>
  .echothread-wrapper {
    margin-top: 4rem;
    padding-top: 2rem;
    border-top: 1px solid var(--border-color, #e5e5e5);
    min-height: 400px;
  }
</style>

4. Use it in your post layout

---
import BaseLayout from "./BaseLayout.astro";
import EchoThread from "../components/EchoThread.astro";
---
<BaseLayout title={frontmatter.title}>
  <article>
    <h1>{frontmatter.title}</h1>
    <slot />
  </article>
  <EchoThread />
</BaseLayout>

5. (Bonus) Lazy-load with IntersectionObserver

If you want true zero-JS until the reader actually scrolls to the comments:

<section id="echothread-section">
  <div id="echothread" data-api-key={apiKey}></div>
</section>

<script>
  const section = document.getElementById("echothread-section");
  const observer = new IntersectionObserver((entries) => {
    if (entries[0].isIntersecting) {
      const s = document.createElement("script");
      s.src = "https://cdn.echothread.io/widget.js";
      s.defer = true;
      document.body.appendChild(s);
      observer.disconnect();
    }
  }, { rootMargin: "200px" });
  observer.observe(section);
</script>

Now the widget script never loads for readers who don't scroll past the post.

Done

The widget identifies threads by page URL automatically. Works with content collections, MDX, static or SSR builds.

Full guide with troubleshooting: echothread.io/docs/guides/astro

How to Add Comments to a Next.js Site (App Router and Pages Router)

Yoni Ryabinski — Thu, 09 Apr 2026 00:18:05 +0000

Next.js gives you so many ways to render a page that the answer to "how do I add comments" depends on which version you're on and which architecture you've chosen. Here's a single approach that works for both the App Router and the Pages Router: a small client component that wraps the EchoThread widget (privacy-first, no ads, under 15 KB gzipped, free during beta).

1. Get an API key

2. Add to `.env.local`

NEXT_PUBLIC_ECHOTHREAD_API_KEY=YOUR_API_KEY

The NEXT_PUBLIC_ prefix is mandatory for client-side access.

3. Create `components/EchoThread.tsx`

"use client";

import Script from "next/script";

export default function EchoThread({ theme = "auto" }: { theme?: string }) {
  const apiKey = process.env.NEXT_PUBLIC_ECHOTHREAD_API_KEY;
  if (!apiKey) return null;

  return (
    <section
      className="echothread-wrapper"
      style={{ marginTop: "4rem", paddingTop: "2rem", minHeight: 400 }}
    >
      <div id="echothread" data-api-key={apiKey} data-theme={theme}></div>
      <Script src="https://cdn.echothread.io/widget.js" strategy="lazyOnload" />
    </section>
  );
}

The lazyOnload strategy ensures the widget never blocks LCP.

4. Use it in your post page

App Router (app/blog/[slug]/page.tsx):

import EchoThread from "@/components/EchoThread";

export default async function Post({ params }) {
  const post = await getPost(params.slug);
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
      <EchoThread />
    </article>
  );
}

Pages Router is essentially identical — same component, just imported into your pages/blog/[slug].tsx.

5. Handle soft navigation

Next.js does client-side navigation between routes. To make sure the widget refreshes when readers click between posts, force a remount with a key prop:

"use client";
import { usePathname } from "next/navigation";
import EchoThread from "@/components/EchoThread";

export default function Wrapper() {
  const pathname = usePathname();
  return <EchoThread key={pathname} />;
}

For Pages Router, use useRouter().asPath instead.

Done

The widget identifies threads by page URL automatically. Server components stay server components — only the comment island hydrates.

Full guide with troubleshooting and CSP notes: echothread.io/docs/guides/nextjs

DEV Community: Yoni Ryabinski

Why a local SMTP catcher is not an email integration test

What the catcher checks

What it cannot see

The pattern: one inbox per test run

Keep the fast test

Try one this week

How to Add Comments to an Eleventy Site (with a Custom Shortcode)

1. Get an API key

2. Set up env var loading

3. Add a shortcode in .eleventy.js

4. Use it in your post layout

5. Make it opt-in (optional)

6. Theme it

Done

How to Add Comments to a Hugo Site (Without a Backend)

1. Get an API key

2. Add the embed to layouts/_default/single.html

3. Add the key to hugo.toml

4. (Optional) Make a shortcode

5. Theme it

Done

How to Add Comments to an Astro Site (Lazy-Loaded, Zero JS by Default)

1. Get an API key

2. Add the key to .env

3. Create src/components/EchoThread.astro

4. Use it in your post layout

5. (Bonus) Lazy-load with IntersectionObserver

Done

How to Add Comments to a Next.js Site (App Router and Pages Router)

1. Get an API key

2. Add to .env.local

3. Create components/EchoThread.tsx

4. Use it in your post page

5. Handle soft navigation

Done

3. Add a shortcode in `.eleventy.js`

2. Add the embed to `layouts/_default/single.html`

3. Add the key to `hugo.toml`

2. Add the key to `.env`

3. Create `src/components/EchoThread.astro`

2. Add to `.env.local`

3. Create `components/EchoThread.tsx`