​

Kampanyayı uçtan uca gönderin

​

1. Ön koşullar

• campaigns:write scope’una sahip bir API anahtarı. Aşağıdaki tüm okumalar (hedef kitle önizleme, dry-run, istatistikler) campaigns:read de kabul eder, ancak başlatma eylemleri write gerektirir. Anahtarları panoda Settings → API keys altında oluşturun veya düzenleyin.
• Node SDK (isteğe bağlı). cURL yerine SDK sekmelerini tercih ediyorsanız npm install @devotel-orbit/node.
• Kanalınız için gönderim kimliği. SMS/MMS için doğru kayıtlara sahip bir numara veya gönderici havuzu (ABD A2P için 10DLC gerekir); WhatsApp için bağlı bir WABA; e-posta için doğrulanmış bir gönderici alan adı.
• Onaylı bir hedef kitle kaynağı. Bir kişi listesi, canlı bir segment, alıcı adreslerinden oluşan bir CSV, harici bir CRM kitlesi (HubSpot listesi / Salesforce raporu) veya elle seçilmiş bir dizi kişi kimliği. Hedef kitleler opt-in olmuş alıcılardan gelmelidir — suppression ve abonelikten çıkma işleme, göndericiye bırakılmayıp gönderim anında zorunlu olarak uygulanır.

​

2. Taslak kampanyayı oluşturun

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retail promo — summer sale",
    "type": "blast",
    "channel": "sms",
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "message_template": "Hi {{first_name}}, early access to our summer sale starts now: 25% off through Sunday. Reply STOP to opt out.",
    "send_time_optimization": "fixed"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const campaign = await orbit.campaigns.create({
  name: "Retail promo — summer sale",
  channel: "sms",
  message_template:
    "Hi {{first_name}}, early access to our summer sale starts now: 25% off through Sunday. Reply STOP to opt out.",
});

​

3. Hedef kitleyi bağlayın ve doğrulayın

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/audience/preview" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "channel": "sms"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// No typed helper wraps this endpoint — the SDK index
// ([/sdks](/sdks#node)) routes uncovered endpoints through
// the generic `request()` escape hatch.
const preview = await orbit.request("POST", "/campaigns/audience/preview", {
  audience_type: "list",
  audience_id: "list_summerVIPs",
  channel: "sms",
});

​

4. Kişiselleştirme ve yerel ayar

• Token’lar çeviri boyunca olduğu gibi korunur.
• Tek opt-out talimatı tam olarak bir kez kalır (operatör gerekliliği).

​

5. Uçuş öncesi: dry-run çalıştırın

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/dry-run" \
  -H "X-API-Key: $ORBIT_API_KEY"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const report = await orbit.request(
  "POST",
  `/campaigns/${"cmp_abc123"}/dry-run`,
);
// Same escape hatch as the audience preview above — no body needed.

• audience.total_in_audience — brüt eşleşen sayısı.
• audience.suppressed / opted_out / unreachable — net projeksiyon kohortları (suppression listesi, kanal başına opt-out’lar, kanal adresinin eksikliği).
• audience.held_out — variables.campaign_holdout_percent ayarlıysa artırılışklık kontrol kohortuna ayrılan alıcılar; teslimden hariçtir.
• audience.deliverable — başlatmanın deneyeceği tam net sayı.
• cost.unit_price_cents / cost.total_cents — gönderim yolunun kullandığı çözümleyicinin üzerinden fiyatlanır; böylece sayı, yuvarlama payıyla cüzdan düşüşüyle eşleşir.
• cost.balance_cents / cost.sufficient — cüzdan kontrolü; yeşil bir dry-run, yeşil bir başlatma bakiye kapısı anlamına gelir.
• quiet_hours.skipped_estimate ve quiet_hours.window — alıcı yerel saatine göre quiet hours’tan öngörülen atlama oranı ve değerlendirilen çözümlenmiş pencere.
• channel_waterfall — birincil kanal ve kanallar arası yedek biçimi; böylece göndermeye basmadan önce RCS → SMS (veya kurduğunuz zincir her neyse) doğrulanabilir.
• warnings[] — engellemeyen sorunlar (kanal için kayıtlı sağlayıcı yok, quiet hours pencereyi tamamen kapatıyor, …) sert hatalardan ayrı çizilir.

• Onaylar. Organizasyonunuz amir onayı gerektiriyorsa başlatma (POST /campaigns/:id/send) göndermek yerine bekleyen onay durumu döndürür; onaycı kuyruğu GET /campaigns/approvals/pending, organizasyon varsayılanları GET/PUT /campaigns/approvals/settings altındadır.
• Sağlayıcı hazır oluşu. Dry-run, liste hijyenini ve sağlayıcı kaydını uyarıları üzerinden örtük olarak denetler — yapılandırılmış sağlayıcısı olmayan bir kanal, gönderimde hata vermek yerine orada görünür.

​

6. Başlatın ve gönderim biçimini seçin

• Throttle. throttle_rate (mesaj/sn) gönderim hızını sınırlar — platform varsayılanı 50 msg/sn; açık bir 0 da varsayılan demektir.
• Akıllı gönderim. send_time_optimization: "recipient-optimal", her alıcıyı etkileşim profillerinden sonraki en iyi zaman penceresine planlar ve teslimi sonraki 24 saate yayar. Önce POST /campaigns/:id/preview-smart-send ile önizleyin; örnek için kişi başına önerilen zamanları ve bir next_best_channel ipucu döndürür. Zamanlamanın kendisinin işe yarayıp yararmadığını ölçmek için variables.smart_send_holdout_pct ile alıcı başına hold-out kohortuna opting-in yapın — bkz. adım 7.
• Kanal önizleme. Kampanyanın kanalı hâlâ açıksa, POST /messages/route-preview ile bir alıcı örneği üzerinde doğrulayın — akıllı yönlendiricinin önerisi, yedek zinciri, mesaj başına maliyet ve etkileşim puanı; hiçbir şey gönderilmez. Zinciri gönderim için devreye almak isterseniz (böylece uç bir hata ilk kanalda durmak yerine basamaklar) aynı isteğe cascade_policy geçin — mesaj başına politika biçimini akıllı gönderim yedek zincirleri rehberi kapsar. Akıllı rota önizleme rehberi uç noktayı ve gönderim hattı desenini anlatır.
• Gönderim penceresi. send_window: { start_local_hour, end_local_hour }, yerel saati pencerenin dışına düşen alıcıları erteler — quiet hours’tan farklı olarak (olumsuz bir filtre) alıcı başına olumlu bir penceredir.

​

7. İzleyin ve ölçün

​

8. Kampanya webhook’larına abone olun

• campaign.created / campaign.updated / campaign.deleted
• campaign.started / campaign.paused / campaign.resumed / campaign.cancelled / campaign.completed
• campaign.drip_step.sent / campaign.drip_step.completed / campaign.drip.completed

​

9. Sorun giderme

• Hedef kitle sıfıra çözülüyor. Hedef kitle önizlemesini channel geçerek yeniden çalıştırın; net projeksiyon, kitleyi hangi kohortun boşalttığını söyler (tümü suppressed, tümü opt-out, ulaşılabilir adres yok). Kampanyayı değil listeyi veya kanal adres kapsamasını düzeltin.
• Dry-run kırmızı uyarılar gösteriyor. warnings[] girdileri açıktır — “no provider registered”, kanalın yapılandırılmış gönderim kimliği yok demektir; “quiet hours fully closed”, çözümlenmiş pencerenin her yerel saati reddettiği demektir; “insufficient balance”, cost.sufficient: false demektir. Uyarıyı temizleyin ve dry-run’ı yeniden çalıştırın.
• Başlatma 402 veya bekleyen onay biçimi döndürüyor. Bakiye kontrolü başarısız oldu veya onay iş akışı açık — ya cüzdanı doldurun ya da POST /campaigns/approvals/:id/approve bekleyin.
• Journey kampanyası paused durumuna takıldı. Bir kampanya, credit_cap_usd_cents’e ulaştığında veya bozuk bir drip adım koşulunda otomatik duraklar. GET /campaigns/:id/stats inceleyin, engelleyiciyi temizleyin, ardından POST /campaigns/:id/resume. Duraklatılmış journey’ler kayıt durumunu korur; sürdürmek, kaldıkları yerden devam eder.
• Akıllı gönderim teslimleri fazla seyreltiyor. recipient-optimal, gönderimleri bilinçli olarak 24 saate yayar. Tek parti gerekiyorsa send_time_optimization: "fixed" ayarlayın ve alıcılar saat dilimlerine yayılıyorsa send_window kullanın.

​

Çalışılmış örnek: perakende promosyonu, taslaktan analize

1. Taslağı oluşturun.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retail promo — summer sale",
    "type": "blast",
    "channel": "sms",
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "message_template": "Hi {{first_name}}, early access to our summer sale: 25% off through Sunday. Reply STOP to opt out.",
    "send_time_optimization": "recipient-optimal",
    "throttle_rate": 100,
    "variables": { "campaign_holdout_percent": 10 },
    "credit_cap_usd_cents": 50000
  }'

2. Hedef kitleyi önizleyin.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/audience/preview" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience_type": "list", "audience_id": "list_summerVIPs", "channel": "sms" }'

3. Dry-run çalıştırın.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/dry-run" \
  -H "X-API-Key: $ORBIT_API_KEY"

4. Akıllı gönderim zamanlarını önizleyin (isteğe bağlı).

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/preview-smart-send" \
  -H "X-API-Key: $ORBIT_API_KEY"

5. Başlatın.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/send" \
  -H "X-API-Key: $ORBIT_API_KEY"

6. Yaşam döngüsü olaylarına abone olun (campaign.started, campaign.completed) ve teslimler biriktikçe istatistikleri okuyun.
7. Ölçün. Gönderim tamamlandıktan sonra:

curl "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/holdout-lift" \
  -H "X-API-Key: $ORBIT_API_KEY"
curl "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/roas" \
  -H "X-API-Key: $ORBIT_API_KEY"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const campaign = await orbit.campaigns.create({
  name: "Retail promo — summer sale",
  channel: "sms",
  message_template:
    "Hi {{first_name}}, early access to our summer sale: 25% off through Sunday. Reply STOP to opt out.",
});
const id = campaign.data.id;

// Attach the audience plus the fields the typed helper doesn't carry
// (holdout percent, spend cap, throttle) via a partial update.
await orbit.request("PUT", `/campaigns/${id}`, {
  audience_type: "list",
  audience_id: "list_summerVIPs",
  type: "blast",
  send_time_optimization: "recipient-optimal",
  throttle_rate: 100,
  variables: { campaign_holdout_percent: 10 },
  credit_cap_usd_cents: 50000,
});

const preview = await orbit.request("POST", "/campaigns/audience/preview", {
  audience_type: "list",
  audience_id: "list_summerVIPs",
  channel: "sms",
});

const dryRun = await orbit.request("POST", `/campaigns/${id}/dry-run`);

// Launch — the typed helper auto-generates an idempotency key.
await orbit.campaigns.send(id);

const lift = await orbit.request("GET", `/campaigns/${id}/holdout-lift`);
const roas = await orbit.request("GET", `/campaigns/${id}/roas`);