Geliştirici API'si

Genel Bakış

Nudgen Geliştirici API’si, çalışma alanınız için komut dosyaları, dahili araçlar ve AI aracılarına öngörülebilir bir REST arayüzü sağlar. Çalışma alanı kaynaklarını yönetmek için Kişisel Erişim Belirteci (PAT) kullanın. Ekip tetikleyici API anahtarını yalnızca arka ucunuzdan Ömür Boyu bir kampanyayı tetiklemek için kullanın.

Bu neden önemlidir

Pazarlama ve etkinlik odaklı elde tutma iş akışlarını, bir kontrol paneli oturumunu paylaşmadan otomatikleştirebilirsiniz. PAT’ler, çalışma alanı yönetiminin geri alınabilir olmasını sağlarken dar bir Ekip tetikleme anahtarı, bir üretim hizmetinin geniş çalışma alanı erişimi olmadan olayla tetiklenen bir uyarı göndermesine olanak tanır.

Temel URL

Ortamınız için uygulama URL’sini bir kez ayarlayın ve her örnekte kullanın. Üretimde yaygın olarak https://app.nudgen.net kullanılır; yerel geliştirme genellikle http://localhost:3000 kullanır.

export NUDGEN_APP_URL="https://app.nudgen.net"

Kimlik Doğrulaması

Kişisel Erişim Jetonu

Ayarlar → API Anahtarları bölümünde bir PAT oluşturun. Kişiler, kampanya yönetimi, marka ayarları ve yapay zeka oluşturmak için bunu kullanın.

Authorization: Bearer $NUDGEN_PAT

PAT’ler yalnızca bir kez gösterilir. Bunları güvenli bir şekilde saklayın ve Ayarlar → API Anahtarları’ndan eski veya açığa çıkmış jetonları iptal edin.

Ekip tetikleyici API anahtarı

Bir Ekip tetikleyici API anahtarı ndg_team_ ile başlar ve dar campaigns:trigger kapsamına sahiptir. Yalnızca Ömür Boyu kampanyaları tetikleyebilir; PAT bunları tetikleyemez. Yalnızca çalışma alanı sahipleri ve yöneticiler bu anahtarları oluşturabilir, döndürebilir veya iptal edebilir. Varsayılan olarak bir anahtarın süresi 90 gün sonra dolar. Süresi dolmayan bir anahtar oluşturmak için expiresInDays’yi null olarak ayarlayın.

curl -X POST "$NUDGEN_APP_URL/api/v1/settings/team-api-keys" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"name":"Order service production","expiresInDays":90}'

201 yanıtı key düz metnini tam olarak bir kez içerir. Bunu sunucu tarafındaki bir gizli yöneticiye kaydedin. Daha sonraki yanıtlar yalnızca keyPrefix’yi ortaya çıkarıyor.

Yöntem	Uç nokta	Açıklama
`POST`	`/api/v1/settings/team-api-keys`	Bir Ekip tetikleyici API anahtarı oluşturun.
`GET`	`/api/v1/settings/team-api-keys`	Ekip tetikleyici API anahtarlarını listeleyin.
`POST`	`/api/v1/settings/team-api-keys/:id`	Etkin, süresi dolmamış bir anahtarı döndürün.
`DELETE`	`/api/v1/settings/team-api-keys/:id`	Bir anahtarı iptal edin.

REST uç noktaları

Kimlik ve çalışma alanı

Yöntem	Uç nokta	Açıklama
`GET`	`/api/v1/user/me`	Kimliği doğrulanmış kullanıcıyı alın.
`GET`	`/api/v1/teams`	Belirteç sahibinin kullanabileceği çalışma alanlarını listeleyin.

Kişiler

Yöntem	Uç nokta	Açıklama
`GET`	`/api/v1/contacts`	`page`, `limit`, `search`, `tags` ve `status` filtrelerine sahip kişileri listeleyin.
`POST`	`/api/v1/contacts/add`	Bir kişi oluşturun.
`GET`	`/api/v1/contacts/:id`	Bir kişi bulun.
`PATCH`	`/api/v1/contacts/:id`	Bir kişiyi güncelleyin.
`DELETE`	`/api/v1/contacts/:id`	Bir kişiyi silin.

curl -X POST "$NUDGEN_APP_URL/api/v1/contacts/add" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"email":"nathan@example.com","name":"Nathan Nguyen","tags":["api-test"]}'

Tek seferlik ve damlama kampanyaları

Yöntem	Uç nokta	Açıklama
`GET`	`/api/v1/campaigns`	Etkin çalışma alanındaki kampanyaları listeleyin.
`POST`	`/api/v1/campaigns`	Bir kampanya taslağı veya planlanmış kampanya oluşturun.
`GET`	`/api/v1/campaigns/:id`	Kampanya ayrıntılarını alın.
`PUT`	`/api/v1/campaigns/:id`	Mevcut bir kampanyayı güncelleyin.
`POST`	`/api/v1/campaigns/:id/launch`	Şimdi başlatın veya tek seferlik veya damlama kampanyası planlayın.
`GET`	`/api/v1/campaigns/:id/stats`	Teslimat, açma, tıklama, geri dönme ve şikayet istatistiklerini alın.
`GET`	`/api/v1/campaigns/:id/progress`	Kampanya gönderme ilerlemesini alın.
`GET`	`/api/v1/campaigns/:id/recipients`	Kampanya alıcılarını listeleyin.
`POST`	`/api/v1/campaigns/test-send`	Kontrol paneli gönderme istatistikleri olmadan bir test e-postası gönderin.

Bir kampanya başlatmak, gerçek e-postayı planlar. Gelen kutusu önizlemeleri için /api/v1/campaigns/test-send kullanın.

Ömür boyu kampanyalar

Ömür boyu kampanyalar etkinlikle tetiklenir: kabul edilen her tetikleyici en fazla bir yürütme oluşturur ve sağlanan kişiye bir uyarı gönderir. Kontrol paneli iş akışı ve değişken sözleşme kılavuzu için Ömür Boyu kampanyaları kullanma konusuna bakın.

Ömür Boyu kampanya oluşturun

draft olarak Ömür Boyu kampanyalar oluşturun. sendNow: true, status: "active" veya status: "scheduled" göndermeyin; bunun yerine kampanyayı yaşam döngüsü uç noktasıyla etkinleştirin.

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "name": "Order confirmation",
  "type": "lifetime",
  "status": "draft",
  "goal": "Confirm an order and direct the customer to its details.",
  "subject": "Your order {{data.order_id}} was received",
  "html": "<p>Hello {{contact.firstName}},</p><p>Order {{data.order_id}} totals {{data.total}} VND.</p><p><a href=\"{{data.order_url}}\">View your order</a></p>",
  "link": "https://example.com/orders",
  "variableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ],
  "generatedVariableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ]
}
JSON

variableManifest, 100’e kadar data.* değişkenini tanımlar. Konuda veya HTML’de kullanılan her data.* jetonunu içermelidir. Varsayılanlar bildirilen türle eşleşmelidir ve HTML href’de kullanılan bir değişken url türüne sahip olmalıdır. E-posta içeriği oluşturduğunuzda eşleşen generatedVariableManifest’yi kaydedin. Geçerli bildirimden farklıysa veya gerekli bildirilen parametreler e-postada yoksa Ndgen etkinleştirmeyi engeller.

Yaşam döngüsünü değiştirin

Yöntem	Uç nokta	Kimlik Doğrulama	Açıklama
`PATCH`	`/api/v1/campaigns/:campaignId/lifecycle`	PAT	Bir Ömür Boyu kampanyayı `active`, `paused` veya `archived` olarak değiştirin.

curl -X PATCH "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/lifecycle" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"status":"active"}'

Geçerli geçişler draft → active → paused → active ve active|paused → archived’dir. Duraklatma veya arşivleme, hâlâ pending veya queued olan yürütmeleri iptal eder ve bunların kota rezervasyonlarını serbest bırakır. Zaten işlenmekte olan bir yürütme yine de gönderilebilir.

Bir uyarıyı tetikleyin

Yöntem	Uç nokta	Kimlik Doğrulama	Açıklama
`POST`	`/api/v1/campaigns/:campaignId/triggers`	Ekip tetikleyici API anahtarı	Bir olay yürütmesi oluşturun ve bir itmeyi sıraya koyun.

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/triggers" \
  -H "Authorization: Bearer $NUDGEN_TEAM_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "eventId": "order_123",
  "eventName": "order.created",
  "occurredAt": "2026-08-23T10:00:00Z",
  "contact": {
    "email": "an@example.com",
    "externalId": "customer_456",
    "name": "An Nguyen",
    "phone": "+84901234567",
    "metadata": { "company": "Nudgen" }
  },
  "data": {
    "order_id": "order_123",
    "total": 490000,
    "order_url": "https://example.com/orders/order_123"
  }
}
JSON

Alan	Tür	Gerekli	Sınırlar ve davranış
`eventId`	dize	Evet	1-128 karakter. Kampanya dahilindeki benzersiz idempotency anahtarı; yeniden denemeler için yeniden kullanın.
`eventName`	dize	Hayır	1-100 karakter, örneğin `order.created`.
`occurredAt`	ISO 8601 tarihsaat	Hayır	Kaynak olayın zamanı.
`contact.email`	e-posta	Evet	Küçük harf. Ndgen, kişiyi e-posta yoluyla oluşturur veya günceller.
`contact.externalId`	dize	Hayır	1-200 karakter uzunluğundadır ve çalışma alanındaki başka bir iletişim e-postasına ait olamaz.
`contact.name`	dize	Hayır	En fazla 200 karakter.
`contact.phone`	dize	Hayır	En fazla 50 karakter.
`contact.metadata`	nesne	Hayır	Ek kişi profili verileri.
`data`	nesne	Evet	`variableManifest` ile eşleşmelidir; maksimum 32 KiB.

İstek gövdesinin tamamı 64 KiB ile sınırlıdır, JSON sekiz düzeyde yuvalanır ve __proto__, constructor ve prototype gibi güvenli olmayan anahtarlar reddedilir. Yeni bir tetikleyici, { "execution": { "id": "...", "status": "queued" }, "duplicate": false } ile 201 değerini döndürür. eventId’nin yeniden kullanılması, 200 ve duplicate: true ile mevcut yürütmeyi döndürür.

Yürütmelerin listesi

Yöntem	Uç nokta	Kimlik Doğrulama	Açıklama
`GET`	`/api/v1/campaigns/:campaignId/executions`	PAT	Ömür boyu kampanya yürütmelerini listeleyin.

curl "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/executions?limit=25&status=sent&search=an@example.com" \
  -H "Authorization: Bearer $NUDGEN_PAT"

1-100 arasında limit’yi (varsayılan 25), sonraki sayfa için cursor’yi, yürütme durumuna göre filtrelemek için status’yi ve Bir e-posta veya harici kimlikle eşleştirmek için search. Yanıt, executions ve nextCursor’yi içerir.

Hatalar, yeniden denemeler ve hız sınırları

Ömür boyu tetikleyiciler, her Ekip tetikleyici API anahtarı için dakikada 600 isteğe izin verir. Yanıtlar arasında x-ratelimit-limit, x-ratelimit-remaining ve x-ratelimit-reset yer alıyor. 429 yanıtı ayrıca Retry-After’yi de içerir.

Durum	Anlamı	Ne yapmalı
`200`	Yinelenen `eventId`	Döndürülen yürütmeyi kullanın; bir daha göndermeyin.
`201`	Yeni yürütme sıraya alındı	Çalışanın bunu işlemesini bekleyin.
`400`	Geçersiz JSON, gövde veya temel alan	Yükü düzeltin; değiştirmeden tekrar denemeyin.
`401`	Eksik, geçersiz, iptal edilmiş, süresi dolmuş veya kapsamı yanlış belirlenmiş anahtar	Anahtar yapılandırmasını döndürün veya düzeltin.
`402` / `403`	Kota veya abonelik yazma işlemlerini engeller	Kota veya abonelik sorununu çözün. Kota hataları `code`, `required`, `available` ve `checkoutUrl`’yi içerir.
`404`	Kampanya eksik veya anahtarın çalışma alanının dışında	Kampanya kimliğini ve anahtarını kontrol edin.
`409`	Kampanya etkin değil/Ömür boyu değil veya kişi kimliği çakışmaları	Kampanyayı etkinleştirin veya iletişim kimliğini düzeltin.
`413`	Talep 64 KiB’yi aşıyor	Yük boyutunu azaltın.
`415`	Eksik `Content-Type: application/json`	Gerekli başlığı ekleyin.
`422`	`data` değişken bildirimiyle eşleşmiyor	Verileri düzeltin; `details`’yi yollar ve hata kodları açısından inceleyin.
`429`	Oran sınırı aşıldı	`Retry-After`’yi bekleyin, ardından aynı `eventId` ile yeniden deneyin.
`503`	Yürütme kuyruğa alınamadı	Geri çekilme ve aynı `eventId` ile yeniden deneyin.

429, 503 ve ağ hataları için üstel geri çekilme ve aynı eventId ile yeniden deneyin. Kuyruk işi bir yürütme için belirleyici olduğundan, yeniden denemeler yinelenen e-posta oluşturmaz.

Marka ayarları

Yöntem	Uç nokta	Açıklama
`GET`	`/api/v1/settings/brand`	Marka adını, web sitesini, gönderenin e-postasını, logosunu ve tasarım ayarlarını okuyun.
`PATCH`	`/api/v1/settings/brand`	Marka ayarlarını güncelleyin.

Yapay zeka taslak oluşturma

Yöntem	Uç nokta	Açıklama
`POST`	`/api/v1/ai/generate`	Kampanya bağlamından bir e-posta konusu ve HTML taslağı oluşturun.

MCP sunucusu

Ajanınız Model Bağlam Protokolü araçlarını desteklediğinde Nudgen MCP kullanın. MCP, çalışma alanı yönetimi API’leriyle aynı PAT’yi kullanır, ancak Nudgen’i geleneksel HTTP uç noktaları yerine aracı tarafından çağrılabilir araçlar olarak kullanıma sunar.

MCP server setup

Nudgen MCP’yi Claude Code, Cursor, Windsurf, Codex CLI’ye veya genel bir MCP istemcisine yükleyin.

Başlangıç

Kişiler

Kampanyalar

Marka

Panel

Ayarlar

Faturalandırma

Satış ortaklığı

Agents

E-posta Bulucu (Uzantı)

İmza Oluşturucu

Spam Kontrolü

E-posta Teslimat Denetimi

Kavramlar

Sorun Giderme

Güvenlik ve Gizlilik

Yasal

Geliştirici API'si

Genel Bakış

Bu neden önemlidir

Temel URL

Kimlik Doğrulaması

Kişisel Erişim Jetonu

Ekip tetikleyici API anahtarı

REST uç noktaları

Kimlik ve çalışma alanı

Kişiler

Tek seferlik ve damlama kampanyaları

Ömür boyu kampanyalar

Ömür Boyu kampanya oluşturun

Yaşam döngüsünü değiştirin

Bir uyarıyı tetikleyin

Yürütmelerin listesi

Hatalar, yeniden denemeler ve hız sınırları

Marka ayarları

Yapay zeka taslak oluşturma

MCP sunucusu

MCP server setup

​Genel Bakış

​Bu neden önemlidir

​Temel URL

​Kimlik Doğrulaması

​Kişisel Erişim Jetonu

​Ekip tetikleyici API anahtarı

​REST uç noktaları

​Kimlik ve çalışma alanı

​Kişiler

​Tek seferlik ve damlama kampanyaları

​Ömür boyu kampanyalar

​Ömür Boyu kampanya oluşturun

​Yaşam döngüsünü değiştirin

​Bir uyarıyı tetikleyin

​Yürütmelerin listesi

​Hatalar, yeniden denemeler ve hız sınırları

​Marka ayarları

​Yapay zeka taslak oluşturma

​MCP sunucusu

MCP server setup

Genel Bakış

Bu neden önemlidir

Temel URL

Kimlik Doğrulaması

Kişisel Erişim Jetonu

Ekip tetikleyici API anahtarı

REST uç noktaları

Kimlik ve çalışma alanı

Kişiler

Tek seferlik ve damlama kampanyaları

Ömür boyu kampanyalar

Ömür Boyu kampanya oluşturun

Yaşam döngüsünü değiştirin

Bir uyarıyı tetikleyin

Yürütmelerin listesi

Hatalar, yeniden denemeler ve hız sınırları

Marka ayarları

Yapay zeka taslak oluşturma

MCP sunucusu