API limitlerini ve kullanımını anlayın

Mailsoftly API'sinin hız sınırlarını, RateLimit yanıt başlıklarını, istek ve çağrı başına üst sınırları ve hesabınızın nerede durduğunu gösteren Kullanım ve limitler kartını okuyun.

Kendi bilgisayarınızda sorunsuz çalışan bir entegrasyonun pazartesi sabahı dokuzda hata vermeye başlaması neredeyse her zaman bir hatadan değil, bir üst sınıra çarpmaktan kaynaklanır. Mailsoftly bu sınırların hepsini açıkça yayınlar ve her yanıt, sizi ilgilendiren sınıra ne kadar yaklaştığınızı söyler.

Bu sayfa referans niteliğinde: iki hız sınırı kovası, kalan hakkınızı taşıyan başlıklar, bir isteğin aşamayacağı boyutlar, uzun bir listede nasıl sayfa sayfa ilerleyeceğiniz ve aynı bilgileri tek satır kod yazmadan gösteren ekran.

İki kova ve ikisi de kimlik bilgisi başına

Sınırlar adrese göre değil, kimlik bilgisine göre sayılır. Entegrasyonunuz tek bir sunucudan çalışır ve o adresi kimseyle paylaşmaz; büyük bir kurumsal ağ ya da bir vekil sunucu ise aynı adresi onlarca şirketle paylaşır. Kimlik bilgisi başına saymak, iki durumun da sizin sorununuz olmamasını sağlar: her API anahtarının kendi bütçesi vardır, yetkilendirdiğiniz her uygulamanın da.

İki kova var.

  • İstekler: beş dakikada 600. Okuma dahil her uç nokta bu kovadan düşer.
  • Gönderimler: saatte 600. Yalnızca gerçekten bir şey yola çıkaran çağrılar, yani send_email, schedule_email ve start_ab_test. Taslak oluşturma, düzenleme, zamanlama bilgileri ve kişi güncellemeleri bu kovada değildir; yani yoğun bir içe aktarma gönderim hakkınızı yiyemez.

Bir gönderim çağrısı bilerek iki kez sayılır: bir kez istek kovasından, bir kez gönderim kovasından. Ayrıca tüm kimlik bilgilerinin toplamı için tek adresten beş dakikada 3.000 isteklik bir emniyet sınırı vardır; geçerli bir anahtarı hiç olmayan bir çağıranı sınırlayan da odur.

Not

Sınırlar app.mailsoftly.com/api/v3 altındaki her şeyi ve kendi bağlayıcılarımızın istek gönderdiği adı geçen webhook adreslerini kapsar. Ayarlar bölümünde Gelişmiş başlığı altındaki Webhook’lar sayfasından oluşturduğunuz yakalama adresini kapsamaz. Onu neyin koruduğunu Webhook uç noktasıyla veri alın anlatıyor.

Mailsoftly geliştirici dokümantasyonunun hız sınırları bölümünde iki kova ve RateLimit yanıt başlıkları

Kalan hakkı yanıttan okuyun

Çağrıları elle saymanız gerekmez. API’den dönen her yanıt üç başlık taşır.

  • RateLimit-Limit, kovanın büyüklüğü
  • RateLimit-Remaining, kovadan geriye ne kaldığı
  • RateLimit-Reset, pencerenin yeniden başlamasına kaç saniye kaldığı

Gönderim uç noktaları kendi kovaları için aynı üçlüyü ekler: RateLimit-Send-Limit, RateLimit-Send-Remaining ve RateLimit-Send-Reset. Başlıklar kimlik doğrulaması çalışmadan önce eklenir; yani 401 ya da 403 yanıtı bile bu başlıkları taşır.

Sınırı aşarsanız 429 Too Many Requests alırsınız: yanında bir Retry-After başlığı, aynı RateLimit-* takımı ve standart hata biçiminde bir JSON gövde gelir. Retry-After saniye cinsindendir ve tam o kadar beklemek yeterlidir; daha erken denemek yalnızca bir istek daha harcar.

RateLimit-Remaining değerini okuyup azaldığında yavaşlayan bir istemci 429 yanıtını hiç görmez. Sayıyı yayınlamamızın sebebi de bu.

İpucu

Bir hafta boyunca RateLimit-Remaining değerini kendi istek sayınızla birlikte kaydedin. İkisi tutmuyorsa şirketinizde aynı anahtarı kullanan başka bir şey var demektir; bunu bir kesintiye dönüşmeden önce öğrenmek iyidir.

Mailsoftly hız sınırı referansında RateLimit yanıt başlıkları ve 429 yanıtının içeriği

Boyut üst sınırlarının altında kalın

Üç üst sınır, isteği ne sıklıkla gönderdiğinizle değil biçimiyle ilgilidir ve her biri isteği sessizce kırpmak yerine reddeder.

  • İstek gövdesi en fazla 10 MB olabilir. Daha büyüğü, Mailsoftly gövdeyi okumaya başlamadan 413 ile reddedilir. Hata mesajı ya yükü bölmenizi ya da toplu kişi yüklemesi için içe aktarma uç noktasını kullanmanızı söyler.
  • Dizi parametrelerinin çağrı başına üst sınırı vardır. Bir add_contacts_to_contact_list çağrısı en fazla 1.000 kişi alır. Bir assign_tags_to_contact çağrısı en fazla 100 etiket alır. Bir create_emails çağrısı en fazla 50 taslak alır ve her taslak en fazla 30.150 alıcı ile 20 ek taşır.
  • Üst sınırı aşarsanız 413 döner ve gövdedeki max_items alanı aştığınız sınırı yazar; böylece istemci parti boyunu deneme yanılmayla değil, doğrudan uyarlar.

Reddetmek bilinçli bir tercih. 1.001’inci kişiyi sessizce düşüren bir çağrı, size tamam görünen ama tamam olmayan bir liste bırakırdı.

Dikkat

Büyük bir kişi yüklemesinin yeri tek tek yazma döngüsü değil, import_contacts uç noktasıdır. İçe aktarma sihirbazıyla aynı arka plan işini çalıştırır, kendi sütun eşleştirmenizle tek bir CSV alır; iş sürerken get_import ve list_imports ilerlemeyi bildirir.

Mailsoftly geliştirici dokümantasyonunda bir uç noktanın dizi parametreleri ve sınırları

Listeyi tek seferde istemek yerine sayfalayın

Liste uç noktaları 1’den başlayan page ve per_page parametrelerini alır. Kişi listeleri sayfa başına 500 satıra kadar, diğer bütün listeler 100 satıra kadar çıkar.

İki parametreden birini gönderdiğinizde yanıt bir zarfa dönüşür:

  • page ve per_page, gönderdiğiniz haliyle geri döner
  • total, sorgunun arkasındaki toplam sayı
  • has_more, döngü koşulunuz. Değeri doğru olduğu sürece devam edin.

Bir kişi listesini iki parametreyi de göndermeden çağırırsanız, eski entegrasyonların beklediği düz dizi biçimi korunur ve 10.000 satırla sınırlanır. O biçim de kendi hakkında doğruyu söyler: X-Total-Count her yanıtta bulunur, dizi kırpıldıysa ek olarak X-Truncated: true başlığı ve ikinci sayfayı gösteren bir Bağlantı başlığı gelir.

Yeni entegrasyonlar her zaman sayfalamalı çalışmalı. Düz dizi biçimi bir kısayol değil, sayfalama gelmeden önce yazılmış koda verilmiş bir uyumluluk sözüdür.

Mailsoftly geliştirici dokümantasyonunun sayfalama bölümünde page ve per page parametreleri

Başlık okumadan hesabın nerede durduğunu görün

Bu sayıya ihtiyaç duyan herkes kod yazmıyor. Ayarlar bölümünü açın, Gelişmiş başlığına, oradan API sayfasına gidin; anahtar listesinin altında Kullanım ve limitler başlıklı bir kart durur.

Üç kutu vardır: altında dünkü toplamla birlikte Bugünkü API çağrıları, 600 / 5 dk yazan İstek limiti ve 600 / saat yazan Gönderim limiti. Altlarındaki tek satır gerisini açık açık yazar: listeler sayfa başına en fazla 500 satır döndürür, toplu çağrılar en fazla 1.000 öğe alır ve 10 MB üzerindeki istekler reddedilir.

Çağrı sayısı, şirketinizin o gün yaptığı bütün API ve webhook çağrılarını bütün anahtarlar üzerinden toplayarak sayar. Bu da onu, hesabını veremediğiniz trafiği yakalamanın en hızlı yolu yapar; o trafik genellikle bir saldırı değil, birinin unuttuğu bir anahtardır.

Not

Karttaki sayı şirketin tamamının çağrılarını sayar ama istek limiti anahtar başına işler. Sınıra takılan bir entegrasyon kendi bütçesini doldurduğu için takılır; yoğun çalışan bir meslektaşınızın betiği sizin çağrınızın reddedilme sebebi olamaz.

Mailsoftly API ekranındaki Kullanım ve limitler kartında bugünkü çağrılar istek limiti ve gönderim limiti

Sınıra takılan bir entegrasyonu düzeltin

429 yanıtları görünmeye başladığında şu dört değişiklik neredeyse her durumu çözer, hem de bu sırayla.

1. Körlemesine yeniden denemek yerine başlığı okuyun. RateLimit-Remaining azaldığında hızınızı düşürün; 429 geldiğinde de hemen tekrar denemek yerine Retry-After saniyesi kadar bekleyin. Sıkı bir yeniden deneme döngüsü, reddedilen tek bir çağrıyı yüz çağrıya dönüştürür. 2. Sayfalayın. 500 kişilik tek bir istek, bir istek harcar. Kişi başına bir istek gönderirseniz beş yüz istek harcarsınız. 3. Üst sınırların altında partileyin. Kişileri listeye 1.000’erli, etiketleri 100’erli ekleyin; kişi başına bir çağrı göndermeyin. 4. Toplu yüklemeleri içe aktarma uç noktasına taşıyın. Tek çağrıda giden bir CSV, satır satır ilerleyen bir döngünün bir dakikada boşalttığı kovayı tüketemez.

Bunların hiçbiri değilse, bakılacak bir sonraki şey anahtarın başka kimde olduğudur. Her entegrasyona kendi anahtarını verirseniz soru kendiliğinden yanıtlanır; Bağlı uygulamaları ve API anahtarlarını denetleyin bunu üç aylık bir alışkanlığa dönüştürüyor.

Sınırlar, onları sonradan keşfedin diye değil, tasarımınızı onlara göre yapın diye yayınlanır. Kalan hakkı okuyun, partilenebilecek olanı partileyin; bir entegrasyon yıllarca tek bir 429 görmeden çalışabilir.

Bir hesabın API trafiğini yayınlanmış limitlerle karşılaştırmak için kullanılan Kullanım ve limitler kartı

Sık sorulan sorular

Mailsoftly API’sinde kalan kullanım hakkımı nasıl takip edebilirim?

Mailsoftly API’sinde kalan kullanım hakkınızı, her API yanıtında dönen özel başlıklar üzerinden takip edebilirsiniz. Yanıtta yer alan RateLimit-Remaining değeri, ilgili kova için kaç hakkınız kaldığını gösterir. Ayrıca RateLimit-Reset başlığı, pencerenin yeniden başlayacağı saniyeyi belirtir. Bu başlıkları düzenli olarak kontrol ederek sınırınıza yaklaşmadan önlem alabilirsiniz.

Mailsoftly API’sinde bir isteğin boyutunu veya gönderilecek kişi sayısını artırabilir miyim?

Hayır, Mailsoftly API’sinde belirli üst sınırlar vardır ve bunlar aşılamaz. Örneğin, bir istek gövdesi en fazla 10 MB olabilir, bir add_contacts_to_contact_list çağrısı en fazla 1.000 kişi alır. Bu sınırları aşarsanız istekleriniz 413 hatası ile reddedilir ve hata mesajında aşılan değer belirtilir. Büyük yüklemeler için toplu içe aktarma uç noktasını kullanmanız önerilir.

Mailsoftly hesabımda yapılan tüm API çağrılarını tek bir ekranda görebileceğim bir yer var mı?

Evet, Mailsoftly hesabınızda Ayarlar bölümünde Gelişmiş başlığı altındaki API sayfasında, anahtar listesinin hemen altında Kullanım ve limitler başlıklı bir kart bulunur. Bu kartta bugünkü toplam API çağrılarınızı, istek ve gönderim limitlerinizi ve ilgili açıklamaları topluca görebilirsiniz. Böylece hesabınızın genel API trafiğini kolayca takip edebilirsiniz.

Kendi hesabınızda denemeye hazır mısınız?

Google Workspace veya Microsoft 365 hesabınızla ücretsiz başlayın. Kredi kartı gerekmez.

Sırada ne var