E-posta akışları, bir web uygulamasının doğru şekilde test edilmesi en zor parçalarından biridir. Kayıt onayları, şifre sıfırlamaları, işlemsel e-postalar, onboarding dizileri — hepsinin doğrulanması için çalışan bir gelen kutusu gerekir.

Bunun için gerçek e-posta adresleri kullanmak kötü bir fikirdir: gelen kutularını kirletir, test e-postalarının gerçek kullanıcılara gönderilmesi riskini taşır ve otomatik testlere ölçeklenmez. Tek kullanımlık ve geçici e-posta adresleri bu üç sorunu da çözer.

Bu rehber, geçici bir gelen kutusuyla hızlı manuel testlerden CI/CD pipeline'larında tam otomatik e-posta doğrulamasına kadar eksiksiz araç setini kapsar.

E-posta Testlerinin Temel Sorunu

Bir e-posta akışı oluşturduğunda şunları doğrulaman gerekir:

E-posta gerçekten gönderildi
Teslim edildi (geri dönmedi veya spam filtrelerine takılmadı)
İçerik doğru (konu, gövde, bağlantılar)
E-postadaki bağlantılar doğru çalışıyor (onay bağlantıları, şifre sıfırlama token'ları)
Bağlantıya tıklandıktan sonra akış doğru şekilde tamamlanıyor

Bunu gerçek e-posta adresleriyle yapmak birkaç sorun yaratır:

Gelen kutusu kirliliği — Ekibinin gelen kutuları yüzlerce test e-postasıyla dolup taşar
Gerçek kullanıcılara yanlışlıkla gönderme — Yanlış yapılandırılmış bir ortam değişkeni ve test e-postaların üretim kullanıcılarına gider
Programatik erişim yok — OAuth veya IMAP yapılandırması olmadan gerçek bir gelen kutusunu CI/CD pipeline'ından okuyamazsın
Yavaş geri bildirim döngüleri — Her test çalışması için gerçek bir gelen kutusunu manuel olarak kontrol etmek ölçeklenmez

E-posta Testleri için Araç Kategorileri

Her biri farklı durumlara uygun dört ana yaklaşım vardır:

1. Genel Tek Kullanımlık Gelen Kutuları (Manuel Testler)

InstantTempEmail, Guerrilla Mail veya 10 Minute Mail gibi hizmetler anında çalışan bir gelen kutusu verir. Bir akışı manuel olarak test ettiğinde ve sadece hızlıca bir doğrulama e-postası almana gerektiğinde bunları kullan.

Ne zaman kullanılır:

Yeni bir e-posta akışının yerel geliştirme testleri
Geliştirme sırasında tek seferlik QA kontrolleri
E-postanın gerçek bir gelen kutusunda nasıl görüntülendiğini test etme

Ne zaman kullanılmaz:

Otomatik testler — bu gelen kutularını bir test paketinde programatik olarak okuyamazsın

2. Geliştirme SMTP Yakalayıcıları (Otomatik, İzole)

Bu araçlar, geliştirme veya staging ortamındaki tüm giden e-postaları yakalar — hiçbir şey gerçek adreslere teslim edilmez. Yakalanan e-postaları bir web arayüzü veya API aracılığıyla incelersin.

Mailtrap en yaygın kullanılandır. Üretim dışı ortamlarda uygulamayı onların SMTP sunucusu üzerinden gönderecek şekilde yapılandırırsın. Tüm e-postalar bir sandbox gelen kutusuna gider.

MailHog kendi kendine barındırılan bir alternatiftir — yerel olarak bir SMTP sunucusu ve web arayüzü çalıştıran hafif bir Go uygulaması. Sıfır maliyet, sıfır harici bağımlılık.

Mailpit daha iyi arayüz ve aktif geliştirmeyle birlikte daha yeni bir MailHog yedeğidir.

3. Genel API Gelen Kutuları (Otomatik, Gelen Kutusu Erişimiyle)

Mailinator gibi hizmetler HTTP API üzerinden erişilebilen genel gelen kutuları sağlar. Uygulamandan testuser@mailinator.com adresine e-posta gönderir, sonra test paketinde API'leri aracılığıyla gelen kutusunu kontrol edersin.

Ne zaman kullanılır:

E-posta içeriğini doğrulaması ve bağlantılara tıklaması gereken uçtan uca testler
OAuth olmadan gelen kutusu erişimine ihtiyaç duyulan CI/CD pipeline'ları
E-posta tetiklemeli akışları test etme (onay → yönlendirme → onboarding)

4. İşlemsel E-posta Test Hizmetleri

Mailtrap (sandbox'tan ayrı test ürünleri), Postmark'ın test modu veya SendGrid'in sandbox modu gibi hizmetler, gerçekten göndermeden tam e-posta gönderme pipeline'ını — API çağrıları, render, teslim edilebilirlik — test eder.

Yerel Geliştirme için MailHog Kurulumu

MailHog, e-posta testlerini yerel olarak kurmanın en kolay yoludur. Tüm giden postaları yakalayan ve bir web arayüzünde görüntüleyen bir SMTP sunucusu çalıştırır.

Docker Compose ile Kurulum

MailHog'u docker-compose.yml dosyana ekle:

services:
  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"   # SMTP portu
      - "8025:8025"   # Web arayüzü portu
    restart: unless-stopped

Uygulamanı MailHog kullanacak şekilde yapılandır

Geliştirme için .env dosyanda:

MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=null

Uygulamanın geliştirmede gönderdiği tüm e-postalar artık MailHog'a gider. http://localhost:8025 adresinden gelen kutusuna eriş.

Bu neden geliştirmede gerçek e-postadan daha iyidir

E-postalar asla makineni terk etmez — gerçek kullanıcılara yanlışlıkla gönderme olmaz
Anlık teslim — gerçek SMTP teslimatını beklemeye gerek yok
Tam e-posta içeriği tarayıcıda görünür — başlıklar, HTML, metin parçaları, ekler
Kimlik doğrulama gerekmez
Test çalışmaları arasında temizlemesi kolay

Mailinator API ile Otomatik E-posta Testleri

E-postaları programatik olarak okuması gereken uçtan uca testler için Mailinator API'si en doğrudan seçenektir.

Ücretsiz katmanın sınırları vardır, ancak ücretli API'leri çoğu ekip için uygun fiyatlıdır.

fetch ile Temel Gelen Kutusu Kontrolü

async function getLatestEmail(inboxName) {
  const response = await fetch(
    `https://mailinator.com/api/v2/domains/mailinator.com/inboxes/${inboxName}`,
    {
      headers: {
        Authorization: process.env.MAILINATOR_API_KEY
      }
    }
  )

  const data = await response.json()

  if (!data.msgs || data.msgs.length === 0) {
    throw new Error(`Gelen kutusunda e-posta bulunamadı: ${inboxName}`)
  }

  return data.msgs[0] // En son e-posta
}

async function getEmailBody(messageId) {
  const response = await fetch(
    `https://mailinator.com/api/v2/domains/mailinator.com/inboxes/test/messages/${messageId}`,
    {
      headers: {
        Authorization: process.env.MAILINATOR_API_KEY
      }
    }
  )

  return response.json()
}

Playwright ile Tam Uçtan Uca Kayıt Testi

import { test, expect } from '@playwright/test'

const TEST_EMAIL = `e2e-test-${Date.now()}@mailinator.com`

test('kullanıcı kaydı ve e-posta onayı', async ({ page }) => {
  // Adım 1: Sitede kayıt ol
  await page.goto('https://staging.uygulamann.com/register')
  await page.fill('[name="email"]', TEST_EMAIL)
  await page.fill('[name="password"]', 'TestPassword123!')
  await page.click('[type="submit"]')

  // "E-postanı kontrol et" sayfasına yönlendirme bekle
  await expect(page).toHaveURL(/check-email/)

  // Adım 2: Onay e-postasını bekle ve getir
  const email = await waitForEmail(TEST_EMAIL.split('@')[0], {
    timeout: 30000,
    subject: 'E-postanı onayla'
  })

  // Adım 3: E-posta gövdesinden onay bağlantısını çıkar
  const confirmUrl = extractConfirmationLink(email.body)
  expect(confirmUrl).toBeTruthy()

  // Adım 4: Onay bağlantısını ziyaret et
  await page.goto(confirmUrl)

  // Adım 5: Başarılı onayı doğrula
  await expect(page).toHaveURL(/dashboard/)
  await expect(page.locator('h1')).toContainText('Hoş geldin')
})

async function waitForEmail(inbox, options = {}) {
  const { timeout = 15000, subject } = options
  const startTime = Date.now()

  while (Date.now() - startTime < timeout) {
    const response = await fetch(
      `https://mailinator.com/api/v2/domains/mailinator.com/inboxes/${inbox}`,
      { headers: { Authorization: process.env.MAILINATOR_API_KEY } }
    )

    const data = await response.json()
    const emails = data.msgs || []

    const match = subject
      ? emails.find(e => e.subject?.includes(subject))
      : emails[0]

    if (match) {
      // Tam e-posta gövdesini getir
      const bodyResponse = await fetch(
        `https://mailinator.com/api/v2/domains/mailinator.com/inboxes/${inbox}/messages/${match.id}`,
        { headers: { Authorization: process.env.MAILINATOR_API_KEY } }
      )
      return bodyResponse.json()
    }

    await new Promise(resolve => setTimeout(resolve, 1000))
  }

  throw new Error(`E-posta ${timeout}ms içinde alınamadı`)
}

function extractConfirmationLink(emailBody) {
  const htmlContent = emailBody.parts?.[0]?.body || ''
  const urlPattern = /https?:\/\/[^\s"'<>]+confirm[^\s"'<>]*/i
  const match = htmlContent.match(urlPattern)
  return match?.[0] || null
}

Test Çalışması Başına Benzersiz Adresler Kullanma

Yaygın bir hata, test çalışmaları arasında aynı test e-posta adresini yeniden kullanmaktır. Eski e-postalar gelen kutusunu kirletir ve testler yanlış e-postayı alabilir.

Desen: Zaman damgası tabanlı benzersiz adresler

// Test çalışması başına benzersiz gelen kutusu oluştur
const testRunId = Date.now()
const email = `registration-test-${testRunId}@mailinator.com`

Desen: Test başına UUID tabanlı

import { randomUUID } from 'crypto'

function testEmail(prefix = 'test') {
  return `${prefix}-${randomUUID().slice(0, 8)}@mailinator.com`
}

// Kullanım
const email = testEmail('registration') // registration-a1b2c3d4@mailinator.com

Bu, her test çalışmasının geçmişi olmayan yeni bir gelen kutusuna sahip olmasını sağlar.

Mailpit Kurulumu (Modern MailHog Yedeği)

Mailpit'in daha iyi arayüzü, aktif geliştirmesi ve MailHog'dan daha fazla özelliği vardır. Yeni kurulumlar için daha iyi seçimdir.

# docker-compose.yml
services:
  mailpit:
    image: axllent/mailpit
    ports:
      - "1025:1025"   # SMTP
      - "8025:8025"   # Web arayüzü
    environment:
      MP_MAX_MESSAGES: 500
      MP_DATABASE: /data/mailpit.db
      MP_SMTP_AUTH_ACCEPT_ANY: 1
      MP_SMTP_AUTH_ALLOW_INSECURE: 1
    volumes:
      - mailpit_data:/data

volumes:
  mailpit_data:

Mailpit ayrıca programatik gelen kutusu erişimi için bir REST API'sine sahiptir; bu da onu Docker Compose ortamındaki otomatik testler için uygun kılar:

// Mailpit API — yerel/CI Docker Compose kurulumlarında kullanım için
async function getMailpitInbox() {
  const response = await fetch('http://localhost:8025/api/v1/messages')
  return response.json()
}

async function deleteAllMessages() {
  await fetch('http://localhost:8025/api/v1/messages', { method: 'DELETE' })
}

Temiz bir durum sağlamak için her test çalışmasının başında deleteAllMessages() ile gelen kutusunu temizle.

Yanlışlıkla Üretim E-postası Göndermeyi Önleme

Bu kritiktir. Staging'i üretim SMTP kimlik bilgilerine yönlendiren yanlış yapılandırılmış bir ortam değişkeni gerçek kullanıcılara gerçek e-postalar gönderir.

Yaklaşım 1: Ortam tabanlı SMTP anahtarlama

// email.config.js
const emailConfig = {
  development: {
    host: 'localhost',
    port: 1025,
    secure: false,
    auth: null
  },
  test: {
    host: 'localhost',
    port: 1025,
    secure: false,
    auth: null
  },
  staging: {
    host: process.env.MAILHOG_HOST || 'mailhog',
    port: 1025,
    secure: false
  },
  production: {
    host: process.env.SMTP_HOST,
    port: 587,
    secure: true,
    auth: {
      user: process.env.SMTP_USER,
      pass: process.env.SMTP_PASS
    }
  }
}

export const smtpConfig = emailConfig[process.env.NODE_ENV] || emailConfig.development

Yaklaşım 2: Üretim dışı ortamlar için alan adı izin listesi

function shouldSendEmail(toAddress) {
  if (process.env.NODE_ENV === 'production') return true

  const allowedTestDomains = [
    'mailinator.com',
    'guerrillamail.com',
    'instanttempemail.com',
    'sirketin.com'  // Dahili test adresleri
  ]

  const domain = toAddress.split('@')[1]
  return allowedTestDomains.includes(domain)
}

Farklı İstemcilerde E-posta Görüntülemesini Test Etme

Yukarıdaki araçlar e-posta teslimini ve içeriğini doğrular, ancak e-postanın farklı istemcilerde nasıl görüntülendiğini doğrulamaz. E-posta HTML'si Gmail, Outlook, Apple Mail ve mobil istemciler arasında farklı davranır.

Görüntüleme testleri için Email on Acid veya Litmus kullan — e-postanın 90'dan fazla istemcide ekran görüntülerini oluştururlar. Her ikisinin de ücretsiz deneme sürümü vardır.

Daha basit kontroller için Mailtrap e-posta önizleme özelliği, e-postanı yaygın istemci bağlamlarında görüntüler.

Sıkça Sorulan Sorular

Otomatik testler için Gmail veya Outlook kullanabilir miyim? Teknik olarak evet, OAuth veya IMAP erişimi kullanarak. Pratikte daha yavaş, kurulumu daha karmaşık ve oran sınırları ile kimlik doğrulama yönetimi getiriyor. Özel araçlar her zaman daha hızlı ve güvenilirdir.

Mailtrap ile MailHog arasındaki fark nedir? Mailtrap barındırılan bir SaaS hizmetidir — e-postalar onların sunucularına gönderilir ve web arayüzlerinde görüntülenebilir. MailHog kendi kendine barındırılır — makinende veya Docker Compose kurulumunda çalışır. MailHog'un sıfır maliyeti vardır ve ortamını terk eden sıfır veri. Mailtrap bir ekipte paylaşması daha kolaydır.

Hassas test verileri için Mailinator kullanmak güvenli mi? Hayır. Mailinator gelen kutuları herkese açıktır — gelen kutusu adını bilen herkes e-postaları okuyabilir. Yalnızca test verisi kullan. Mailinator gelen kutularında asla gerçek kullanıcı verisi kullanma. Özel otomatik testler için bunun yerine Docker Compose kurulumunda MailHog veya Mailpit kullan.

GitHub Actions CI pipeline'ında e-posta akışlarını nasıl test ederim? İş akışı YAML'ındaki services anahtarını kullanarak GitHub Actions iş akışına bir MailHog veya Mailpit hizmeti ekle. Uygulamam localhost:1025'e gönderir ve testlerin yerel API aracılığıyla okur.

jobs:
  test:
    services:
      mailpit:
        image: axllent/mailpit
        ports:
          - 1025:1025
          - 8025:8025

Staging'de gerçek e-posta sağlayıcılarıyla test etmeli miyim? Yalnızca özellikle teslim edilebilirliği test etmen gerekiyorsa (spam puanlama, DKIM/DMARC, gelen kutusu yerleşimi). E-posta akışlarının işlevsel testleri için MailHog gibi yerel bir yakalayıcı daha hızlı ve güvenlidir. Gerçek teslim edilebilirlik kontrollerini ayrıca, daha az sıklıkla, büyük sağlayıcılarda test hesapları kullanarak gerçekleştir.

Geliştiriciler Test için Tek Kullanımlık E-postaları Nasıl Kullanır (Gerçek Örneklerle)