Ubuntu 24.04 uzerine Listmonk kurulumu ve SMTP ayarları

Self-hosted bir Listmonk bülten sisteminin gereksinimleri

Listmonk, self-hosted bir bülten ve posta listesi yöneticisidir: tek bir Go binary dosyası, bir PostgreSQL veritabanı, bir yapılandırma dosyası ve bir systemd biriminden oluşur. Listmonk, aboneleri saklar ve kampanya kuyruklarını yönetir ancak postaları bizzat göndermediği için küçük bir VPS üzerinde zahmetsizce çalışır. Her iletiyi bir SMTP (simple mail transfer protocol) sunucusuna iletir; bu nedenle teslimat oranınız yazılımın kendisine değil, ilgili sunucunun itibarına bağlıdır.

Bu kılavuz, Temmuz 2026 itibarıyla güncel sürüm olan Listmonk v6.2.0'ın Ubuntu 24.04 üzerine kurulumunu anlatır. Genel IP adresine sahip bir VPS, kontrolünüzde olan bir alan adı ve PostgreSQL 12 veya daha yeni bir sürüm gereklidir. Kurulum yaklaşık bir saat sürer. Gönderim itibarının oluşması ise haftalar alır; bu konu kılavuzun son bölümlerinde ele alınmıştır.

PostgreSQL kurulumu ve veritabanı oluşturma

Ubuntu 24.04, Listmonk'un gereksinimlerini fazlasıyla karşılayan PostgreSQL 16 sürümünü kendi depolarında sunar.

sudo apt update
sudo apt install -y postgresql curl
sudo systemctl enable --now postgresql

Rolü ve veritabanını tek bir psql oturumunda oluşturun. -v ON_ERROR_STOP=1, psql'in ilk başarısız komutta durmasını sağlar; böylece bir yazım hatası, tamamlanmış gibi görünen yarım bir kurulumla sonuçlanmaz.

sudo -u postgres psql -v ON_ERROR_STOP=1 <<'SQL'
CREATE USER listmonk WITH PASSWORD 'pick-a-long-random-password';
CREATE DATABASE listmonk OWNER listmonk;
SQL

OWNER listmonk bir süsleme değildir. Şema kurulumu tabloları, türleri, indeksleri ve fonksiyonları oluşturur; bu nedenle rolün veritabanının sahibi olması gerekir. Listmonk'u başka bir rolün sahip olduğu bir veritabanına yönlendirirseniz, GRANT CONNECT komutunu çalıştırmış olsanız dahi kurulum permission denied hatasıyla durur.

İlerlemeden önce veritabanının var olduğunu doğrulayın.

sudo -u postgres psql -tAc "SELECT datname FROM pg_database WHERE datname='listmonk';"

Bu komut listmonk çıktısını verir. Boş bir satır, CREATE komutunun hiç çalışmadığı anlamına gelir; bu durumda psql çıktısını tekrar inceleyin.

Listmonk ikili dosyasının kurulumu

Listmonk, her mimari için statik bir ikili dosya yayımlar. Öncelikle kendi mimarinizi kontrol edin; çünkü ARM tabanlı bir VPS üzerinde amd64 ikili dosyası, çekirdeğin çalıştırmayı reddedeceği bir dosyadır.

dpkg --print-architecture
cd /tmp
curl -fsSLO https://github.com/knadh/listmonk/releases/download/v6.2.0/listmonk_6.2.0_linux_amd64.tar.gz
tar -xzf listmonk_6.2.0_linux_amd64.tar.gz
sudo install -m 755 listmonk /usr/bin/listmonk
listmonk --version

ARM tabanlı bir VPS kullanıyorsanız dosya adındaki amd64 ifadesini arm64 ile değiştirin. listmonk --version komutuyla sürüm bilgisinin ekrana yazdırılması, ikili dosyanın makine ile uyumlu olduğunun ilk kanıtıdır.

config.toml dosyasını oluşturun ve erişimini kısıtlayın

--new-config, config.toml dosyasını mevcut çalışma dizinine yazar. cd komutunun sudo öncesinde değil, sh -c içinde yer almasının nedeni budur.

sudo install -d -m 750 /etc/listmonk
sudo sh -c 'cd /etc/listmonk && listmonk --new-config'

Oluşturulan dosya kısadır. [app] altında, address = "localhost:9000" ayarı HTTP sunucusunu yalnızca loopback arayüzüne bağlar; bu sayede yönetici paneli, önüne bir reverse proxy koyana kadar internetten erişilemez durumda kalır. Bu satırı değiştirmeyin. [db] altında host = "localhost", port = 5432, user = "listmonk", database = "listmonk" ve ssl_mode = "disable" değerlerini göreceksiniz. Bu varsayılanlar oluşturduğunuz veritabanı ile uyumludur, bu nedenle değiştirmeniz gereken tek satır paroladır.

Postgres aynı makinede loopback üzerinden dinleme yaptığı sürece ssl_mode = "disable" kullanımı doğrudur, çünkü bu trafik makine dışına çıkmaz. Veritabanını başka bir sunucuya taşırsanız ayarı require olarak değiştirin, aksi takdirde parola ağ üzerinden açık metin olarak iletilir.

[db] altındaki parola satırını oluşturduğunuz role uygun şekilde düzenleyin, ardından servis hesabını oluşturun ve dosyanın erişimini diğer tüm kullanıcılar için kapatın.

sudo useradd --system --home-dir /var/lib/listmonk --create-home --shell /usr/sbin/nologin listmonk
sudo chown -R root:listmonk /etc/listmonk
sudo chmod 640 /etc/listmonk/config.toml

Artık dosyayı yalnızca servis hesabı okuyabilir, diğer kullanıcıların erişimi engellenmiştir.

sudo -u listmonk cat /etc/listmonk/config.toml > /dev/null && echo readable
stat -c '%U:%G %a' /etc/listmonk/config.toml

İlk komut readable çıktısını verir. İkinci komut ise root:listmonk 640 çıktısını verir. Aynı cat işlemini deneyen yetkisiz başka bir hesap Permission denied hatası alır; hedeflenen durum budur. Bu dosya veritabanı parolanızı açık metin olarak tutar ve bir sunucuda genellikle birden fazla kullanıcı hesabı bulunur. Aynı mantık çalıştırdığınız tüm servisler için geçerlidir; bu nedenle en az yetkili servis kullanıcıları konusunu inceleyin ve her yerde uygulayın.

--install ile şemayı oluşturun

--install tabloları oluşturur ve varsayılan ayarları ekler. İlk yönetici girişini ortam değişkenleri ile ayarlayın; böylece panel erişilebilir hale gelmeden önce hesap mevcut olur.

sudo -u listmonk env LISTMONK_ADMIN_USER=admin \
  LISTMONK_ADMIN_PASSWORD='another-long-random-password' \
  listmonk --config /etc/listmonk/config.toml --install --yes

--yes onay istemini yanıtlar. Otomatize etmeden önce istemi bir kez okuyun; çünkü --install ilk kurulum aracıdır ve mevcut bir Listmonk şemasını siler. Canlı bir veritabanında ikinci kez çalıştırmak abonelerinizi yok eder. İki kez çalışabilecek herhangi bir betikte, tablolar zaten mevcut olduğunda hiçbir işlem yapmayan --install --idempotent --yes komutunu kullanın. Yeni bir sürümle gelen şema değişiklikleri --install ile değil, her zaman --upgrade ile uygulanır.

Sonucu tarayıcıdan değil, veritabanı tarafından kontrol edin.

sudo -u postgres psql -d listmonk -c '\dt'
sudo -u postgres psql -d listmonk -tAc "SELECT username FROM users;"

Birincisi, aralarında subscribers, lists, campaigns, templates ve bounces bulunan Listmonk tablolarını listeler. İkincisi ise admin çıktısını verir. İkincisinden boş bir sonuç dönmesi, ortam değişkenlerinin sürece ulaşmadığı anlamına gelir; bu durumda panel, ilk kullanıcıyı tarayıcı üzerinden oluşturmanızı isteyecektir.

Listmonk uygulamasını systemd altında çalıştırma

/etc/systemd/system/listmonk.service dosyasını oluşturun.

[Unit]
Description=Listmonk newsletter and mailing list manager
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple
User=listmonk
Group=listmonk
WorkingDirectory=/var/lib/listmonk
ExecStart=/usr/bin/listmonk --config /etc/listmonk/config.toml
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true

[Install]
WantedBy=multi-user.target

WorkingDirectory, Listmonk dosya sistemi medya yükleme yolu dahil olmak üzere göreli yolları bu dizine göre çözümlediği için önemlidir. After=postgresql.service yalnızca başlatma sırasını düzenler, Postgres'in bağlantıları kabul etmesini beklemez; bu nedenle Restart=on-failure, Listmonk'un çok erken başlatıldığı ve bağlantı kuramadığı durumları kapsar.

sudo systemctl daemon-reload
sudo systemctl enable --now listmonk
ss -ltnp | grep 9000
curl -sI http://127.0.0.1:9000/

ss, 127.0.0.1:9000 değerini LISTEN durumunda göstermelidir. curl herhangi bir HTTP durum satırı döndürüyorsa sunucu yanıt veriyor demektir. curl işleminin Connection refused ile başarısız olması, sürecin başlatma sırasında sonlandığı anlamına gelir ve journalctl -u listmonk -n 50 --no-pager bunun nedenini açıklar. enable --now kısmının yeniden başlatma sonrasında da kalıcı olduğunu unutmayın; elle başlatılan bir süreç, bir sonraki çekirdek yükseltmesinden sonra kaybolacaktır.

Nginx ve TLS katmanını öne yerleştirin

Listmonk, loopback üzerinde düz HTTP ile çalışır; bu nedenle TLS (transport layer security) sonlandırma işlemini nginx yapar ve istekleri iletir.

server {
    listen 443 ssl;
    server_name lists.example.com;

    client_max_body_size 25m;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Abone içe aktarma ve medya yükleme işlemleri dosya gönderimi içerdiğinden client_max_body_size değerinin artırılması gerekir; nginx, 413 Request Entity Too Large ile 1 MB üzerindeki tüm istekleri varsayılan olarak reddeder. Sertifikayı, listen 443 ssl satırlarını ve 80 numaralı porttan yönlendirmeyi sizin yerinize otomatik olarak oluşturan certbot ile alın: adımlar nginx için Let's Encrypt sertifika rehberi içerisinde yer almaktadır. 80 ve 443 numaralı portları açın; proxy, servise loopback üzerinden eriştiği için 9000 numaralı portu kapalı tutun. Güvenlik duvarı henüz yapılandırılmadıysa ufw güvenlik duvarı temelleri ile başlayın.

Ardından yönetim panelini açın ve Settings altındaki root URL değerini https://lists.example.com olarak ayarlayın. Yeni kurulumlarda bu değer http://localhost:9000 olarak gelir ve Listmonk, e-postalara eklediği her abonelikten çıkma bağlantısı ile medya URL'sine bu değeri yazar. Ayarı değiştirmeden önce bir kampanya gönderirseniz, her alıcı kendi makinesine işaret eden bağlantılar alır. Bu bağlantılar alıcı tarafında çalışmaz ve spam filtreleri için yapılandırmasını tamamlayamamış bir gönderici izlenimi yaratır.

SMTP bağlantısı, config.toml dosyasında yer almıyor

config.toml içerisinde bir SMTP bölümü aradığınızda bulamazsınız. E-posta ayarları veritabanında, settings tablosunda tutulur ve bu ayarları yönetim panelinde Ayarlar ve SMTP altında düzenlersiniz. Oluşturulan dosyanın kısa kalmasının ve SMTP değişikliğinin yeniden başlatma gerektirmemesinin nedeni budur.

SMTP sunucusunun kendisi için iki makul seçenek mevcuttur. İtibar yönetimini tamamen kendi elinize aldığınız ve başlı başına bir proje olan kendi sunucunuzu çalıştırabilirsiniz: Mailcow ile kendi posta sunucunuzu çalıştırma rehberi bu sürecin neleri kapsadığını açıklar. Alternatif olarak, Listmonk'u bir işlemsel (transactional) aktarıcıya yönlendirip IP itibarı sorumluluğunu başka bir tarafa bırakabilirsiniz.

Her iki durumda da STARTTLS ile 587 numaralı portu veya örtük TLS ile 465 numaralı portu kullanın. 25 numaralı giden portu kullanmayı planlamayın. Çoğu VPS sağlayıcısı, yeni hesaplarda bu portu varsayılan olarak engeller. Engellenmiş bir 25 numaralı port, tıpkı askıda kalmış bir bağlantı gibi davranır; paketler reddedilmek yerine düşürüldüğü için istemci hızlı bir hata almak yerine zaman aşımını bekler.

Güvenmeden önce test edin. Bir liste oluşturun, kendi adresinizi abone olarak ekleyin ve tek alıcılı bir kampanya gönderin. Gelen iletiyi açın ve tüm başlıkları (headers) okuyun. Alıcı taraf tarafından eklenen Authentication-Results başlığı, SPF ve DKIM doğrulamalarının başarılı olup olmadığını size bildirir.

Teslim edilebilirlik işin tamamıdır

Listmonk iletiyi oluşturur, listeyi takip eder ve postayı teslim eder. Postanın gelen kutusuna ulaşıp ulaşmayacağına dair her karar, gönderici IP adresi ve gönderici alan adını kullanan alıcı sağlayıcı tarafından verilir. Yeni bir VPS IP adresinin hiçbir geçmişi yoktur ve hiçbir geçmiş, tüm büyük posta kutusu sağlayıcıları tarafından hafif şüpheli olarak değerlendirilir.

Dört şey isteğe bağlı değildir:

• Alan adınız adına gönderim yapmasına izin verilen ana bilgisayarı belirten bir SPF (sender policy framework) TXT kaydı.
• Listmonk yerine posta sunucusu tarafından imzalanan ve TXT kaydı olarak yayınlanan bir DKIM (domainkeys identified mail) anahtarı.
• İlk ikisi başarısız olduğunda alıcılara ne yapmaları gerektiğini söyleyen bir DMARC (domain based message authentication, reporting and conformance) kaydı.
• Listmonk'un okuduğu bir geri dönüş (bounce) posta kutusu; böylece postayı reddeden adresler sürekli yeniden denenmek yerine listeden çıkarılır.

Ardından başlangıçta yavaş gönderim yapın. Hiç posta göndermemiş bir alan adının aniden bir saat içinde on bin ileti teslim etmesi, ele geçirilmiş bir hesabın tam olarak davranış şeklidir, bu nedenle bu şekilde filtrelenir. En etkileşimli abonelerinizle başlayın ve hacmi günler içinde artırın.

Her şablonun ayrıca çalışan bir abonelikten çıkma bağlantısına ihtiyacı vardır. Bir Listmonk şablonunda bu {{ UnsubscribeURL }} şeklindedir ve kampanya gövdesi {{ template "content" . }} ifadesinin bulunduğu yere yerleşir; bu ifade her şablonda tam olarak bir kez yer almalıdır. Abonelikten çıkma bağlantısı olmayan bir kampanya, abonelikten çıkmalar yerine spam şikayetleri doğurur ve şikayetler, haftalarca uğraşarak oluşturduğunuz gönderim itibarını kaybetmenin en hızlı yoludur.

Yedeklemeler ve geri yükleme için gerekenler

Sunucudan dışarı çıkarılması gereken iki temel öğe vardır: veritabanı dökümü ve config.toml. Kampanyalara görsel yüklüyorsanız medya dizinini de buna ekleyin.

sudo -u postgres pg_dump -Fc listmonk > listmonk-$(date +%F).dump

Söz konusu döküm; aboneleri, kampanyaları, şablonları ve SMTP kimlik bilgileri dahil tüm ayarları içerir; bu nedenle dosyayı şifreleyin ve sunucu dışında saklayın. Yedekleme zamanlaması çözülmüş bir sorundur: uzak depolama alanına şifreli restic yedekleri konusuna bakın. config.toml birkaç satırdan oluşur ancak veritabanı parolasını içerdiği için aynı şekilde korunmalıdır.

Yükseltmeler belirli bir sırayı takip eder. Servisi durdurun, döküm alın, /usr/bin içindeki ikili dosyayı değiştirin, listmonk --config /etc/listmonk/config.toml --upgrade komutunu çalıştırın ve ardından servisi başlatın. Şema geçişleri yalnızca ileriye doğru çalışır, bu nedenle aldığınız döküm geri dönüş için tek yolunuzdur.

Listmonk neden başlatılamıyor?

Öncelikle journalctl -u listmonk -n 50 --no-pager ile günlük kayıtlarını inceleyin. Neredeyse tüm başlatma hataları [db] bloğundaki tek bir satırda belirtilir.

pq: password authentication failed for user "listmonk" hatası, [db] dosyasındaki parolanın Postgres rolü ile eşleşmediği anlamına gelir. pq ön eki, Postgres sürücüsünün sunucunun reddini bildirdiğini gösterir; yani yapılandırma dosyası doğru okunmuş ancak kimlik bilgileri hatalı girilmiştir. sudo -u postgres psql -c "ALTER USER listmonk WITH PASSWORD 'new-password';" ile rolü sıfırlayın ve aynı dizgiyi dosyaya girin.

pq: database "listmonk" does not exist hatası, [db] içindeki database değerinin mevcut bir veritabanını işaret etmediği anlamına gelir. sudo -u postgres psql -l komutu, sunucuda halihazırda bulunan veritabanlarını listeler; yanlışlıkla yazdığınız yazım hatasını burada görebilirsiniz.

--install sırasında alınan permission denied hatası, rolün bağlantı kurabildiğini ancak veritabanının sahibi olmadığını, bu nedenle tablo oluşturamadığını gösterir. sudo -u postgres psql -c "ALTER DATABASE listmonk OWNER TO listmonk;" ile yetkilendirmeyi düzeltin ve kurulumu tekrar çalıştırın.

Servis hiç başlamıyor ve günlük kayıtlarında yapılandırma dosyası belirtiliyor. listmonk kullanıcısı olarak çalışan bir süreç, 600 izinleriyle bırakılmış root:root konumundaki bir config.toml dosyasını açamaz. stat -c '%U:%G %a' /etc/listmonk/config.toml komutu root:listmonk 640 çıktısını vermeli ve dosyanın bulunduğu dizin root:listmonk 750 olmalıdır.

Panel çalışıyor ancak posta ulaşmıyor. Bu bir başlatma sorunu değildir. Öncelikle Ayarlar ve SMTP yapılandırmasını, ardından posta sunucusunun her deneme için döndürdüğü hatayı kaydeden yönetici panelindeki kampanya günlüğünü kontrol edin.

FAQ

Listmonk kullanmak için kendi posta sunucuma ihtiyacım var mı?

Hayır. Listmonk bir posta sunucusu değildir. Postalarınızı kabul edip iletecek bir sunucu için SMTP kimlik bilgilerine ihtiyaç duyar; bu bir işlemsel (transactional) aktarıcı veya kendi çalıştırdığınız bir posta sunucusu olabilir. Bu kimlik bilgilerini admin panelindeki Settings ve SMTP altında yapılandırın. Posta ayarları veritabanında tutulduğu için bu ayarları config.toml içinde yapmayın. Çoğu VPS sağlayıcısı yeni hesaplarda 25 numaralı giden portu engellediğinden, STARTTLS ile 587 numaralı portu veya örtük TLS ile 465 numaralı portu kullanın.

Kampanyamdaki bağlantılar neden localhost:9000 adresine yönlendiriyor?

Kök URL ayarı, kurulum varsayılanı olan http://localhost:9000 değerinde kalmıştır. Listmonk, bir kampanya gönderildiği anda bu değeri abonelikten çıkma bağlantılarına ve medya URL'lerine yazar. Admin panelinde Settings kısmını açın, kök URL'yi gerçek HTTPS adresinizle değiştirin ve kaydedin. Hali hazırda gönderilmiş iletiler düzeltilemez; bu nedenle gerçek bir listeye gönderim yapmadan önce kendinize bir test kampanyası gönderin ve içindeki abonelikten çıkma bağlantısına tıklayarak kontrol edin.

--install komutunu tekrar çalıştırmak abonelerimi siler mi?

Evet. --install ilk kurulum aracıdır ve mevcut Listmonk şemasını siler; --yes ise sizi uyaracak olan istemi kaldırır. İki kez çalışabilecek herhangi bir betikte, tablolar zaten mevcutsa hiçbir işlem yapmayan --install --idempotent --yes kullanın. Yeni bir sürümdeki şema değişikliklerini uygulamak için servisi durdurun, bir pg_dump alın ve ardından --upgrade komutunu çalıştırın.

Listmonk neden listmonk kullanıcısı için parola kimlik doğrulamasının başarısız olduğunu söylüyor?

/etc/listmonk/config.toml dosyasındaki [db] bloğunda yer alan parola, aynı isimli Postgres rolüyle eşleşmiyor. Günlük kaydındaki satır pq: password authentication failed for user "listmonk" şeklindedir ve pq, Postgres sürücüsünün sunucudan gelen reddi ilettiğini gösterir; bu da yapılandırma dosyasının bulunduğunu ve okunduğunu ifade eder. Rolün parolasını sudo -u postgres psql -c "ALTER USER listmonk WITH PASSWORD 'new-password';" ile sıfırlayın, aynı karakter dizisini yapılandırma dosyasına yazın ve ardından sudo systemctl restart listmonk komutunu çalıştırın.