API anahtarları ve web kancaları

Mail Merge, geliştiriciler ve kod yazmayanlar için bir REST API ve giden web kancaları sunmaktadır. Bir API anahtarı ile betikleriniz web uygulamasının yaptığı her şeyi yapabilir: hesabınızı okuyabilir, şablonları ve kişileri listeleyebilir, kampanyalar gönderebilir ve alıcılarını takip edebilir. Bir web kancası ile Mail Merge, bir kampanya bittiğinde veya bir alıcı açtığında, tıkladığında, yanıt verdiğinde, geri döndüğünde veya abonelikten çıktığında sizin uç noktanızı çağırır. Böylece bir CRM, bir elektronik tablo veya bir Slack kanalı yoklama yapmadan senkronize kalır.

Her ikisi de web uygulamasında Ayarlar → Geliştiriciler altında bulunur ve Profesyonel planın bir parçasıdır (bkz. Fiyatlandırma). Mail Merge ile kod yazmak yerine bir yapay zeka asistanından konuşmayı tercih ederseniz, bunun yerine MCP sunucusunu kullanın: aynı özellikleri araçlar olarak ortaya koymakta ve her planda kullanılabilmektedir.

API anahtarları

Anahtar oluşturma

1. Ayarlar → Geliştiriciler → API anahtarları açın ve Anahtar oluştur seçeneğini tıklayın.
2. Kullanılacağı yere göre adlandırın (Zapier, CRM senkronizasyonu), böylece daha sonra doğru olanı iptal edebilirsiniz.
3. Anahtarı kopyalayın. Yalnızca bir kez gösterilir: Mail Merge yalnızca bunun bir karmasını tutar. Kaybederseniz, iptal edin ve yeni bir tane oluşturun.

Hesap başına en fazla 10 anahtar olabilir. Bir anahtarı iptal etmek, onunla yapılan her isteği hemen başarısız kılar; satır listeden kaybolur.

Kimlik doğrulama

Anahtarı, kartta gösterilen temel URL’ye karşı her istekte Bearer token olarak gönderin:

curl https://merge.email/api/v1/me \
  -H "Authorization: Bearer mm_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Bir anahtar, onu oluşturan hesap olarak hareket eder, tıpkı oturum açmış bir oturum gibi: aynı Google izni, aynı günlük kota, aynı plan sınırları. Ayrı bir “API kullanıcısı” yoktur.

Uç noktalar

API, web uygulamasının kullandığı aynı /v1 yüzeyidir, bu nedenle ekranda yapabileceğiniz her şeyin arkasında bir uç nokta vardır. İntegrasyonların en çok ulaştığı olanlar:

Çağrı	Ne yapar
GET /v1/me	Hesap: plan, günlük kota (maksimum, kullanılan, kalan), saat dilimi, şablon meta verileri.
GET /v1/templates · GET /v1/templates/{templateId}	Kaydedilmiş şablonlarınız; gövde şablon başına yüklenir.
GET /v1/contacts · POST /v1/contacts	Kişi defteri (limit / cursor → nextCursor ile sayfalandırılmış).
POST /v1/campaigns	Google Sheet’ten bir kampanya gönderin, planlayın veya otopilot yapın. Gövde, kampanya oluşturucunun gönderdiği aynı olandır: sayfa, alıcı sütunu, konu ve gövde {{merge tags}} ile ve gönderme seçenekleri.
GET /v1/campaigns · GET /v1/campaigns/{campaignId}/recipients	Kampanyalarınız ve her alıcının durumu (gönderilen, okunan, tıklanan, yanıtlanan, geri dönen, abonelikten çıkan).
POST /v1/campaigns/{campaignId}/status	Çalışan bir kampanyayı duraklatın, devam ettirin veya durdurun.
POST /v1/recipients/verify	E-posta doğrulayıcı.

İstek ve yanıt gövdeleri JSON’dur. Tam yazılı yüzey sunucudan OpenAPI belgesi olarak oluşturulur; istemci oluşturucu için şemaya ihtiyacınız varsa bizimle iletişime geçin.

Hatalar ve hız sınırı

Hatalar, gerçek HTTP durumlarıdır ve bir zarfla gelir:

{ "error": { "code": "professional_plan_required", "message": "API access is a Professional plan feature" } }

Durum	code	Anlamı
401		Bilinmeyen veya iptal edilmiş anahtar, ya da hesabın Google erişiminin yeniden bağlanması gerekiyor.
403	professional_plan_required	Anahtarın hesabı artık Profesyonel planda değil. Anahtarlar indirgeme sırasında silinmez; plan geri geldiğinde yeniden çalışırlar.
429	rate_limited	Bir anahtarda dakikada 600 istekten fazla. Bir dakika bekleyin ve yeniden deneyin.
400 / 404 / 409	bad_request, not_found, conflict, …	İsteğin kendisi, düzeltilecek şeyi söyleyen bir mesajla.

Hız sınırı, her API sunucu örneğinde anahtar başına sayılır, bu nedenle etkili tavan “dakikada yaklaşık 600”dür: buna çarpmak üzere tasarlamayın.

Web kancaları

Uç nokta ekleme

1. Ayarlar → Geliştiriciler → Web kancaları açın ve Web kancası ekle seçeneğini tıklayın.
2. Bir HTTPS URL’si girin (düz http:// reddedilir) ve alması gereken etkinlikleri işaretleyin.
3. Yeni satırda Test gönder seçeneğini tıklayın: Mail Merge bir ping gönderir ve bildirim, uç noktanızın nasıl yanıt verdiğini söyler.

Her uç nokta kendi imza sırrını (whsec_…) alır, satırda kopyalama düğmesiyle gösterilir. Hesap başına en fazla 5 uç nokta olabilir.

Etkinlikler

Etkinlik	Ne zaman	data
campaign.completed	Bir kampanyanın son e-postası işlendi.	campaignId, name, status: "completed", sentCount, campaignSize
campaign.paused · campaign.resumed · campaign.stopped	Bir kampanyayı durdurdunuz, devam ettirdiniz veya durdurdunuz.	campaignId, name, status (paused / active / stopped), sentCount
email.opened	Bir alıcı bir e-postayı açtı, kampanya başına yalnızca ilk kez.	campaignId, recipient, at
email.clicked	Bir alıcı izlenen bir bağlantıyı tıkladı, her tıklama.	campaignId, recipient, at, url
email.replied	Gönderilen bir iş parçacığında yanıt algılandı.	campaignId, recipient, at
email.bounced	Bir geri dönüş algılandı.	campaignId, recipient, at
recipient.unsubscribed	Bir alıcı abonelikten çıkma bağlantısını kullandı, kampanya başına yalnızca ilk kez.	campaignId, recipient, at, method

Açılış ve tıklamalar kampanya için izlemenin açık olmasını gerektirir; yanıtlar ve geri dönüşler, gönderilen her kampanyanın ardından gelen yanıt taramasından gelir.

Teslimat

Mail Merge, abone olan her uç nokta için etkinlik başına bir POST gönderir, JSON gövdesiyle:

{
  "id": "6f1c2d3e-…",
  "event": "email.opened",
  "createdAt": "2026-10-15T14:03:21.512Z",
  "data": { "campaignId": "…", "recipient": "ada@example.com", "at": "2026-10-15T14:03:21.498Z" }
}

ve üç başlık:

Başlık	Değer
X-MailMerge-Event	Etkinlik adı, gövdedeki event ile aynı.
X-MailMerge-Delivery	Teslimat kimliği, id ile aynı. Bir kopyayı yok saymak için kullanın.
X-MailMerge-Signature	sha256= ve ardından ham gövdenin onaltılık HMAC-SHA256’sı, uç noktanın sırrıyla anahtarlanmış.

5 saniye içinde herhangi bir 2xx ile yanıt verin. Bir ağ hatası veya 5xx üzerinde Mail Merge bir kez, 2 saniye sonra yeniden dener; 4xx sizin kararınız olarak alınır ve yeniden denenmez. Aynı teslimat kimliği yeniden denemede gönderilir. Arka arkaya 20 başarısız teslimatdan sonra uç nokta devre dışı bırakılır ve satır bunu söyler: uç noktayı düzeltin, ardından silin ve yeniden ekleyin. Herhangi bir başarılı teslimat sayacı sıfırlar.

Etkinlikler en az bir kez teslim edilir ve garantili bir sırada değildir. Açılışlar özellikle patlamalar halinde gelir (izleme pikselini işleyen her posta istemcisi), bu nedenle işleyicinizi X-MailMerge-Delivery üzerinde veya (event, campaignId, recipient) üzerinde etkisiz hale getirin.

İmzayı doğrulama

Bir yükü güvenmeden önce her zaman doğrulayın. Ham istek gövdesi üzerinde HMAC hesaplayın (JSON ayrıştırmasından önce tam baytlar) ve sabit zamanda karşılaştırın:

// Node.js (Express with `express.raw({ type: "application/json" })`)
import { createHmac, timingSafeEqual } from "node:crypto"

export function verifyMailMergeSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? "")
  return a.length === b.length && timingSafeEqual(a, b)
}

app.post("/mailmerge", (req, res) => {
  if (!verifyMailMergeSignature(req.body, req.get("X-MailMerge-Signature"), process.env.MAILMERGE_WEBHOOK_SECRET)) {
    return res.status(401).end()
  }
  const payload = JSON.parse(req.body)
  // … handle payload.event / payload.data
  res.status(204).end()
})

# Python
import hashlib, hmac

def verify_mailmerge_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Zapier, Make ve n8n

Kod gerekmez: bir Catch Hook (Zapier Webhooks by Zapier), bir Custom webhook (Make) veya bir Webhook tetikleyici düğümü (n8n) oluşturun, verdiği URL’yi uç nokta olarak yapıştırın, etkinlikleri işaretleyin ve Test gönder seçeneğini tıklayın. böylece araç yükü örnekleyebilir. data alanları, bir satırı bir sayfaya eklediğiniz, bir CRM kişisini güncellediğiniz veya Slack’e gönderdiğiniz sonraki adıma eşlediğiniz değişkenler haline gelir. Bu araçlar imzaları kutudan çıkarmaz doğrulamaz; verdikleri URL tahmin edilemez, bu da güvenmeleri gereken korumadır.

Sonraki adımlar

• Yapay zeka ajanları (MCP), bir asistan Mail Merge’i sizin yerine bir betik yerine yönetmelidir.
• Kampanyalar, alıcılar uç noktasındaki durumların ne anlama geldiğini öğrenmek için.
• Fiyatlandırma, Profesyonel planın neleri içerdiğini öğrenmek için.