Toromino's blog

Fixing Claws-Mail TLS on macOS (Homebrew, Apple Silicon)

28 Nov, 2025

Claws-Mail on macOS Apple Silicon (via Homebrew) currently fails to establish TLS connections.
The root cause is the way Homebrew builds and links libetpan, which results in broken TLS behaviour when used together with Claws on Apple Silicon. Even when GnuTLS itself works correctly, Claws aborts or reports failed handshakes.

One solution that worked for me is to avoid the Homebrew-supplied libetpan entirely and build a self-contained Claws-Mail stack in its own prefix.

1. Symptoms

Observable failures:

This indicates that the remote server and the system TLS libraries are fine, while the Claws-Mail + libetpan combination is not.

2. Prerequisites

Before building libetpan or Claws-Mail, macOS must have a complete development toolchain and all necessary libraries.

2.1 Xcode and developer tools

Install Xcode from the App Store.  

Set the active developer directory to the full Xcode installation:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

If the Command Line Tools are not installed, macOS will prompt you to install them the first time you run a build that needs them, or you can trigger installation manually:

xcode-select --install

2.2 Homebrew build dependencies

You need the tools and libraries that libetpan and claws-mail expect:

brew install automake autoconf libtool pkg-config \
             gnutls openssl@3 cyrus-sasl \
             gettext gpgme gtk+3 at-spi2-core

3. Remove Homebrew’s libetpan and Claws-Mail

The Homebrew libetpan must not be visible to the runtime or compiler. This avoids the already-linked broken libraries being reused.

brew uninstall claws-mail
brew uninstall libetpan

You might also need to remove leftover libraries:

sudo rm -f /opt/homebrew/lib/libetpan*.dylib
sudo rm -rf /opt/homebrew/Frameworks/libetpan.framework

4. Preparations

Create a dedicated installation prefix:

sudo mkdir -p /opt/claws-mail
sudo chown "$(id -u)":"$(id -g)" /opt/claws-mail

5. Build libetpan with GnuTLS support

Build libetpan as a library (not a framework) with GnuTLS only.

cd /tmp
git clone https://github.com/dinhvh/libetpan.git
cd libetpan

Set environment variables:

export PREFIX="/opt/claws-mail"
export PKG_CONFIG_PATH="/opt/homebrew/opt/gnutls/lib/pkgconfig:$PKG_CONFIG_PATH"
export CPPFLAGS="-I/opt/homebrew/include"
export LDFLAGS="-L/opt/homebrew/lib"

Configure libetpan with GnuTLS only:

./autogen.sh \
  --with-gnutls \
  --without-openssl \
  --with-sasl \
  --prefix="$PREFIX"

Build and install:

make -j"$(sysctl -n hw.ncpu)"
make install

This gives you a predictable libetpan linked against GnuTLS in /opt/claws-mail.

6. Patch the Claws-Mail source tree

You can either clone the Git repository:

cd /tmp
git clone https://git.claws-mail.org/readonly/claws.git
cd claws

Or use the latest release tarball:

cd /tmp
curl -O https://www.claws-mail.org/releases/claws-mail-4.3.1.tar.gz
tar xf claws-mail-4.3.1.tar.gz
cd claws-mail-4.3.1

6.1 Fix: rename version script

Claws ships a file named version. Modern libc++ provides a <version> header. The Claws file shadows the standard header may break the build.

Hide the version script, if this is an issue for you:

mv version version.sh.upstream

6.2 Fix: disable the PDF viewer plugin

The PDF viewer plugin requires X11-specific headers (gdk/gdkx.h) that do not exist on macOS (Quartz backend). Disable it at configure time.

7. Configure and build Claws-Mail

Specify the environment for Claws-Mail

export PREFIX="/opt/claws-mail"
export PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig:/opt/homebrew/opt/gnutls/lib/pkgconfig:$PKG_CONFIG_PATH"
export CPPFLAGS="-I$PREFIX/include -I/opt/homebrew/include"
export LDFLAGS="-L$PREFIX/lib -L/opt/homebrew/lib"

Configure:

./configure \
  --prefix="$PREFIX" \
  --disable-archive-plugin \
  --disable-dillo-plugin \
  --disable-notification-plugin \
  --disable-pdf_viewer-plugin

Build and install:

make -j"$(sysctl -n hw.ncpu)"
make install

8. Verify correct linkage

Check that the right libraries are used:

otool -L /opt/claws-mail/bin/claws-mail | grep -E 'libetpan|gnutls'

You should expect:

Not acceptable:

If you still see the libetpan bottle from Homebrew, return to step 3.

With a working claws-mail instance, it looked like this for me:

foxhkron@voyager claws-mail-4.3.1 % otool -L /opt/claws-mail/bin/claws-mail | grep -E 'libetpan|gnutls'
    /opt/claws-mail/lib/libetpan.20.dylib (compatibility version 26.0.0, current version 26.0.0)
    /opt/homebrew/opt/gnutls/lib/libgnutls.30.dylib (compatibility version 72.0.0, current version 72.0.0)

9. Run Claws-Mail

Start Claws-Mail from the custom prefix:

/opt/claws-mail/bin/claws-mail

Configure IMAP and SMTP as you normally would. TLS should now work without any handshake failures. Enjoy!

10. Dock launcher for Claws-Mail

You can use the launcher described here:

Always inspect and verify the contents before running it. Using unknown code can be risky. :)

11. Conclusion

The issue is known and has been reported a number of times:

The core problem lies somewhere in the interaction between Homebrew’s libetpan build and Claws-Mail on macOS. I have not yet pinpointed the exact cause, but every attempt so far has shown that the Homebrew-built library consistently breaks TLS for me. Even rebuilding Claws-Mail from source via Homebrew and forcing it to link against my own libetpan did not resolve the issue, which is why I ultimately chose the self-contained build described above.

By removing the Homebrew libetpan and building Claws-Mail self-contained in /opt/claws-mail, you avoid the broken TLS behaviour and obtain a working Claws-Mail installation on Apple Silicon.

Cheers,
~foxhkron

E-mail: foxhkron@cybre.club
Comments, fixes, and improvements welcome.