Mailsoftly API’sini kullanın

API anahtarı oluşturun

Ayarlar’ı açın, sol menüde Gelişmiş başlığını bulun ve API satırına tıklayın. Anahtarlarla ilgili her şey bu tek ekranda toplanır. Genel aramaya api anahtarı yazarak da aynı yere gidersiniz.

Sağ üstteki API Anahtarı Oluştur düğmesine basın. Açılan pencere iki şey sorar.

• Bir ad. Anahtarı kullanacak şeyin adını yazın, genel bir şey değil. İleride bir anahtarın hiç kullanılmadığını fark ettiğinizde ya da acele bir iptal gerektiğinde neyin duracağını size bu ad söyler.
• Ne kadar yetki alacağı. Tam erişim önceden seçilidir ve anahtarın API’nin her bölümünü kullanmasına izin verir. Bunun yerine Sınırlı erişim’i seçerseniz yedi izinden oluşan bir liste açılır: kişilerinizi, listelerinizi ve etiketlerinizi okuma; kişi, liste ve etiket oluşturma ve güncelleme; kampanyalarınızı ve raporlarını okuma; kampanya taslağı oluşturma ve düzenleme; kişilerinize kampanya gönderme veya planlama; engelli adres listenize adres ekleme; hesabınızı ve şirket profilinizi okuma.

Anahtarı ekrandayken kopyalayın

Formu gönderdiğinizde Mailsoftly anahtarı size bir kez gösterir. Bunu tam anlamıyla alın: veritabanında anahtarın yalnızca parmak izi tutulur, yani ürünün hiçbir yeri o değeri bir daha gösteremez. Pencerenin dışına tıklamak ya da Esc tuşuna basmak da pencereyi kapatmaz, bu bilinçli bir tercihtir.

Kopyala düğmesiyle kopyalayın, gideceği yere hemen yapıştırın ve ancak ondan sonra Tamamlandı düğmesine basın. Anahtarı kaybederseniz geri getirmenin bir yolu yok; anahtarı iptal edip yenisini oluşturursunuz.

Anahtarın hemen altında bitiş tarihi yazar. Yeni anahtarlar oluşturuldukları günden bir yıl sonra sona erer.

Anahtar listesini derli toplu tutun

API ekranına döndüğünüzde elinizdeki anahtarlar en yeniden başlayarak sıralanır. Her satır dört işe yarar bilgi verir: anahtarın oluşturulma zamanı, bitiş tarihi, son kullanımı ve taşıdığı yetki. Hiç çağrı yapılmamış bir anahtar bunu Hiç kullanılmadı diye açıkça söyler.

Adına tıklayarak bir anahtarı yerinde yeniden adlandırabilirsiniz. Değerini yeniden göremezsiniz; satırda yalnızca ilk birkaç karakteri görünür.

Satırın sonundaki İptal et düğmesi anahtarı kalıcı olarak siler. Sızmış bir anahtar için tek gerçek çözüm bu olduğu için düğme fareyle üstüne gelince beliren bir yerde değil, açıkça duruyor. İptal anında geçerli olur ve o anahtarı kullanan ne varsa hemen hata almaya başlar.

Bitiş tarihi kavramı gelmeden önce oluşturulmuş anahtarlarda Süresiz yazar ve onlar çalışmaya devam eder. Sonrasında verilen her anahtar oluşturulmasından bir yıl sonra durur ve Mailsoftly sizi iki kez uyarır: bitişe 45 gün kala bu ekranda anahtarları ve tarihlerini listeleyen bir şerit belirir, 30 gün kala da yöneticilerinize tek bir mail gider. Anahtar yenilemek şu sırayla yapılır: yeni anahtarı oluşturun, entegrasyonu yeni anahtara çevirin, ancak ondan sonra eskisini iptal edin.

Bu ekranı ekibinizdeki herkes açabilir. Anahtar oluşturmak ve iptal etmek için yönetici olmanız ya da mail işlerindeki yetkinizin yazma olarak ayarlanmış olması gerekir. Üç ayda bir listeyi baştan sona okumak beş dakikanızı alır ve fazlasıyla değer: Bağlı uygulamaları ve API anahtarlarını denetleyin bunu bir rutine dönüştürüyor.

Geliştirici dokümantasyonunu açın

Uç nokta listesi app.mailsoftly.com/developers adresinde durur. Herkese açık bir sayfadır: Mailsoftly hesabı olmayan bir geliştiriciye bağlantıyı gönderebilirsiniz, giriş yapmadan açılır. Ürünün içinden gitmek isterseniz genel aramaya api dokümantasyonu yazmanız yeter.

Sayfada bilmeye değer üç bölüm var.

• Alanlara göre gruplanmış etkileşimli bir kaynak: kimlik doğrulama, kişiler, kişi listeleri, etiketler, özel alanlar, mailler, abonelikten çıkanlar ve diğerleri. Bir uç noktayı açtığınızda parametrelerini, örnek isteği, örnek yanıtı ve hazır kod örneklerini görürsünüz.
• app.mailsoftly.com/developers/openapi.json adresindeki makine tarafından okunabilen tanım dosyası. Sayfada İndir OpenAPI Spec bağlantısının arkasında duruyor. Çoğu API istemcisinin ve kod üreticisinin istediği dosya budur ve elle yazılmaz, çalışan uygulamadan üretilir.
• MCP Belgeler adında ikinci bir sekme. Bir asistanı hesabınıza bağlamak içindir ve kendi rehberi vardır: Yapay zeka asistanınızı MCP ile bağlayın.

Okurken şuna dikkat edin: listede hem hazır olan hem de planlanan uç noktalar bulunur. Açıklaması Coming Soon ile başlayan uç noktalar henüz hazır değildir ve çağrıya yanıt vermez. Otomasyonlar, formlar, açılış sayfaları ve SMS kampanyaları bugün bu grupta.

Mailsoftly geliştirici dokümantasyonunu açın

İstekleri kimlik doğrulamayla gönderin

Her çağrı app.mailsoftly.com/api/v3 adresine gider ve anahtarınızı Yazarization başlığında taşır. Anahtarı ham haliyle, başına Bearer koymadan gönderin. Bir API anahtarı için kimlik doğrulamanın tamamı bu kadar.

Bir şey ters gittiğinde ne döndüğünü baştan bilmek hata ayıklamayı kısaltır.

• Yazarization başlığı hiç yoksa 401 ve Missing Yazarization Information mesajı döner.
• Tanımadığımız bir anahtar 401 Unauthorized döner. Bitiş tarihi geçmiş bir anahtar ise 401 Token expired döner; bu ikisi bilerek farklı mesajlardır.
• Sınırlı bir anahtar, izin listesinde olmayan bir uç noktayı çağırırsa 403 döner ve yanıtın gövdesi hangi iznin gerektiğini yazar; böylece tahmin etmek yerine anahtarı düzeltirsiniz.
• Eksik ya da geçersiz bir alan 422 döner. Bütün hata yanıtları aynı biçimdedir: durum alanı error ve düz bir açıklama.

Tek bir hız sınırı var ve oldukça geniş: aynı adresten beş dakikada 300 istek. Sınırı aşarsanız 429 alırsınız ve Retry-After başlığı ne kadar bekleyeceğinizi söyler.

İlk çağrınızı yapın

İşte baştan sona işe yarar bir sıra: listelerinizden birine tek bir kişi eklemek. Kişileri, listeleri ve etiketleri okuma ve oluşturma izinleri olan bir anahtar gerekir.

• Listeyi bulun. /api/v3/get_contact_lists adresine GET gönderin. Yanıtta her genel listeyi kimliği, adı ve kişi sayısıyla görürsünüz. İstediğiniz listenin kimliğini not edin.
• Kişiyi arayın. /api/v3/search_Kişiler adresine, email değeri kişinin adresi olacak şekilde GET gönderin. Eşleşme tamdır, kısmi arama değil; yani boş yanıt gerçekten o adresin sizde olmadığı anlamına gelir.
• Kişiyi oluşturun ya da güncelleyin. /api/v3/create_or_update_contact adresine, gövdesinde email, first_name ve last_name taşıyan bir POST gönderin. contact_id göndermezseniz yeni kişi oluşturulur. Aramanın döndürdüğü contact_id değerini gönderirseniz o kişi güncellenir.
• Kişiyi listeye ekleyin. /api/v3/add_contact_to_contact_list adresine contact_id ve contact_list_id ile POST gönderin. Zaten listede olan birini eklemek hata değil, bilgilendirme mesajı döndürür; yani önceden üyelik kontrolü yapmanıza gerek yok.

Bu sıradaki tuzak üçüncü adımda. create_or_update_contact mail adresine bakarak eşleştirme yapmaz. contact_id yoksa her zaman yeni kayıt oluşturur ve sizde zaten bulunan bir adresi oluşturmaya çalışmak birleştirme değil, doğrulama hatası verir. Önce aradığınızda bu tuzağa hiç düşmezsiniz.

Bir çağrı çalıştıktan sonra kalanı aynı kalıptan gider: aynı adres, aynı başlık, aynı hata biçimi. Kişilerden başlayın; okuma tarafı beklediğiniz gibi çalışmadan gönderim uç noktalarına uzanmayın.