E-posta API'si: Geliştiriciler İçin Kapsamlı Rehber (2026)

E-posta API Entegrasyonu: OAuth'tan Gerçek Zamanlı Senkronizasyona

Gerçek dünya bir E-posta API'si entegrasyonu, hedeflediğiniz sağlayıcıdan bağımsız olarak dört aşamayı takip eder. Uygulamaya başlamadan önce bu bölümü bir kontrol listesi olarak okuyun: buradaki herhangi bir adımı atlamak, entegrasyonların geliştirme ortamında çalışıp üretimde bozulmasının en yaygın nedenidir.

OAuth 2.0 Kimlik Doğrulaması

Hem Gmail hem de Microsoft Graph standartını kullanır OAuth 2.0 yetkilendirme kodu akışı. Mekanizmalar aynıdır: kullanıcıyı sağlayıcıya yönlendir, geri arama URL'inde tek seferlik bir kod al, sunucu tarafında kalıcı yenileme jetonu için onu değiştir, ardından her sonraki API çağrısı için kısa ömürlü erişim jetonları oluşturmak için bu yenileme jetonunu kullan.

• Sağlayıcının yetkilendirme uç noktasına sizi yönlendir client_id, yönlendirme_url'si, ve istenen kapsam.
• Kullanıcı izinleri verir, sağlayıcı sizi tek seferlik bir URL'ye yönlendirir kod parametre.
• Sunucularınız bunu değiştirir kod için erişim_belirteci (1 saat ömürlü) ve bir yenileme_belirteci gizli bir kanal üzerinden POST ile.
• Saklayın yenileme_belirteci sunucu tarafında güvenli bir şekilde, beklemedeyken şifrelenmiş. Yeni erişim belirteçlerini otomatik olarak oluşturmak için kullandığınız uzun ömürlü kimlik bilgisi budur.

E-posta Gönder ve Al

Kimlik doğrulandıktan sonra, sonraki iki işlem tipik E-posta API kullanımının 'ini kapsar:% gelen kutusu getiriliyor ve mesaj gönderiyor. Unipile'ın birleşik API'si ile her ikisi de Gmail, Outlook ve IMAP genelinde tek bir uç nokta kümesi aracılığıyla aynı şekilde çalışır.

# Bağlı bir gelen kutusundan en son 50 e-postayı al
curl --request GET \
  --url 'https://api.unipile.com/api/v1/emails?limit=50&folder=inbox' \
  --header 'X-API-KEY: YOUR_API_KEY'

# Düz metin e-posta gönder
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_id": "YOUR_ACCOUNT_ID",
    "subject": "Hello from Unipile",
    "body": "Hello, this is a plain text email",
    "to": [{"display_name":"John Doe","identifier":"john@example.com"}]
  }'

Unipile ayrıca geliştiricilerin beklediği tipik gelişmiş gönderme özelliklerini de destekler: EKLER (birden çok dosya içeren çok parçalı form verisi), özel üstbilgiler dizileri geçirme X- ön ekli başlıklar), konuya yanıtla (orijinal mesajın) provider_id), Görünen Adı Geçersiz Kıl, izin verilen gönderen takma adları ve açık / bağlantı takibi Gerçek zamanlı webhook olaylarıyla. Bunların her biri, protokol anlaşması gerektirmeden istek gövdesindeki tek bir alana karşılık gelir.

# Ekler + özel başlıklar + izleme ile gönder
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --form 'account_id=YOUR_ACCOUNT_ID' \
  --form 'subject=Taslak sözleşme' \
  --form 'body=Lütfen ekteki v3 belgesini bulun.' \
  --form 'to=[{"identifier":"sarah@acme.com"}]' \
  --form 'attachments=@/path/to/contract.pdf' \
  --form 'attachments=@/path/to/appendix.png' \
  --form 'custom_headers=[{"name":"X-Campaign-ID","value":"q1-outreach"}]' \
  --form 'tracking_options={"opens":true,"links":true,"label":"q1-outreach"}'

Tüm gönderme seçenekleri ve sağlayıcıya özgü davranışları kapsayan eksiksiz bir geliştirici başvurusu için, lütfen belgelerimize bakın. e-posta gönderme API kılavuzu.

Gerçek Zamanlı E-posta Senkronizasyonu

E-posta entegrasyonunun en karmaşık ve en çok yanlış anlaşılan kısmı gelen kutusu senkronizasyonudur. Sağlam bir e-posta senkronizasyonu uygulamanın üç ayrı aşaması vardır: ilk senkronizasyon, artımlı senkronizasyon ve gerçek zamanlı webhook bildirimleri. Herhangi birini atlamak, ilk gün çalışan ve ölçekte bozulan bir entegrasyonla sonuçlanır.

İlk günden yenilemeleri planlayın: Gmail Pub/Sub izleme abonelikleri 7 gün sonra sona erer ve yenilenmesi gerekir. E-posta kaynaklarındaki Microsoft Graph abonelikleri en fazla yaklaşık 3 gün sonra sona erer. Arka plan işi altyapınıza abonelik yenilemeyi dahil edin önce aksi takdirde entegrasyonunuz sessizce olayları almaya devam etmeyecektir.

Web Kancaları ve Etkinlikler

Webhook'lar, modern bir E-posta API'sinin, sormak zorunda kalmadan, arka ucunuza bir şeylerin gerçek zamanlı olarak gerçekleştiğini bildirme biçimidir. Yoklama yerine /mesajlar Her 30 saniyede bir (pahalı ve yavaş), bir kez abone olursunuz ve sağlayıcı her yeni e-posta geldiğinde, okunduğunda, yanıtlandığında veya silindiğinde uç noktanıza bir JSON yükü gönderir.

Genellikle abone olduğunuz etkinlikler şunlardır: mail_received (gelen kutusuna yeni bir mesaj düştü), posta_gönderildi (giden bir ileti başarıyla teslim edildi), e_posta_açıldı (alıcı açtı, izleme etkinse), e_posta_bağlantısı_tıklandı (alıcı izlenen bağlantıya tıkladı) ve hesap_durumu (Bağlı posta kutusunun yeniden kimlik doğrulaması gerekiyor, örn. parola değişikliğinden sonra). Her olay, aşağı akış sistemlerinizin ek API çağrıları yapmadan tepki vermesi için yeterli bağlam taşır.