> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Vazgeçme ve Bastırma Listeleri
> Orbit'in vazgeçmiş alıcıları kanallar arasında nasıl bastırdığını, bir bastırma listesini satır başına sonuçlar ve yinelenenleri ayıklama ile CSV'den nasıl toplu içe aktaracağınızı ve zorlamayı nasıl doğrulayacağınızı, içe aktarım hatalarını nasıl tanılayacağınızı ve bir bastırmayı güvenle nasıl geri alacağınızı açıklar.
# Vazgeçme ve Bastırma Listeleri
Bir **bastırma listesi**, tekrar asla mesaj göndermemeniz gereken adresler
kümesidir — STOP yanıtı veren, abonelikten çıkan, geri dönen veya şikayette
bulunan kişiler. Bunu onurlandırmak her düzenlenmiş kanalda yasal bir
gerekliliktir ve Orbit bunu sert bir gönderi kapısı olarak ele alır:
bastırılmış bir adres, kampanyadan, kişi içe aktarımından veya API
çağrısından bağımsız olarak gönderimden önce atılır.
Bu sayfa bastırmanın nasıl çalıştığını, mevcut bir bastırma listesini —
örneğin başka bir platformdan geçiş yaparken — tek bir CSV yüklemeyle
**toplu içe aktarma**yı ve
[defterin dışa aktarılmasını](#export-the-suppression-list) denetim için
kapsar.
Aşağıdaki tüm uç noktalar
`https://api.orbit.devotel.io/api/v1/compliance` kökündedir.
***
## Bastırma nasıl gerçekleşir
Bir adres, çeşitli yollarla bastırma listesine düşer:
* Bir kişi SMS/WhatsApp'ta bir **STOP anahtar sözcüğü** ile yanıt verir.
* Bir kişi [Tercih Merkezi](/compliance/send-gates#preference-center) üzerinden vazgeçer.
* [Consent API](/compliance/consent-management) (`opt_in: false`)
üzerinden bir vazgeçme kaydedersiniz.
* Bir listeyi **toplu içe aktarırsınız** (bu sayfa).
Her girişin bir **kanal kapsamı** vardır. Tam kapsam kümesi: `all`,
`sms`, `voice`, `whatsapp`, `email`, `push`, `telegram`, `messenger`,
`rcs`.
Kapsamın nasıl seçildiği giriş noktasına bağlıdır:
* **Toplu CSV içe aktarımı** kapsamı her satırın adres türünden çıkarır:
telefon ve WhatsApp adresleri varsayılan olarak `all` kapsamına girer —
bir telefon numarasındaki STOP sinyali o numarada ulaşılabilen tüm
kanalları bastırır — e-posta adresleri ise `email` kapsamına alınır.
Bir `channel` sütunu bunu satır başına geçersiz kılar (bkz.
[Toplu CSV içe aktarımı](#bulk-csv-import)).
* **Consent API ve Tercih Merkezi** her zaman `all` kapsamını bastırır;
kaydedilen tanımlayıcının telefon numarası mı yoksa e-posta adresi mi
olduğuna bakılmaksızın. Bu giriş noktalarından birinden gelen bir
vazgeçme, kişiyi her kanaldan kaldırır.
Bir telefon numarası nasıl bastırılırsa bastırılsın, ses ve arayıcı
kapıları onu onurlandırır: herhangi bir kanaldan vazgeçen bir numara,
mesajların yanında çağrıları da almaktan kesilir. Mekanizma giriş
noktasına göre farklıdır. **Toplu CSV içe aktarımı** ayrıca telefon
satırlarını DNC listesine yansıtır ve eşleşen kişileri işaretler.
**STOP anahtar sözcüğü**, **Tercih Merkezi** veya **Consent API**
vazgeçmesi bunun yerine `all` kapsamıyla kaydedilir; ses ve arayıcı
kapıları bunu bastırma listesinden doğrudan okur — çağrı yine bloklanır
ama ayrı bir DNC listesi satırı veya kişi işareti yazılmaz.
***
## Toplu CSV içe aktarımı
`POST /compliance/suppression-list/import`, bir CSV dosyasının
`multipart/form-data` yüklemesini kabul eder. Bir yönetici (admin) veya
sahip (owner) anahtarı gerektirir ve 5 istek/dakika ile hız sınırlıdır.
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/suppression-list/import \
-H "Authorization: Bearer $ORBIT_API_KEY" \
-F "file=@suppressions.csv" \
-F "default_country=US" \
-F "default_reason=migrated_from_legacy_platform" \
-F "dry_run=false"
```
### Form alanları
| Alan | Tür | Notlar |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `file` | dosya | **Gerekli.** Tek bir CSV, ≤ 25 MB, ≤ 100.000 satır. |
| `default_country` | string | ISO-3166-1 alpha-2. Ulusal biçimdeki telefon numaralarını E.164'e normalleştirmek için kullanılır. |
| `default_reason` | string | Kabul edilen her satıra uygulanır (≤ 512 karakter). |
| `dry_run` | boolean | `true` olduğunda yalnızca ayrıştırır ve sınıflandırır — veritabanı yazması yok. Dosyayı işlemeden önce önizlemek için kullanın. |
### CSV biçimi
İlk satır başlıktır. Sütun adları **büyük/küçük harfe duyarsız** ve
**konumdan bağımsızdır**; yaygın takma adlar kabul edilir:
| Mantıksal sütun | Kabul edilen başlıklar |
| ----------------------------------- | ------------------------------------------ |
| Telefon | `phone`, `phonenumber`, `mobile`, `msisdn` |
| E-posta | `email`, `emailaddress`, `mail` |
| WhatsApp ID | `wa_id`, `whatsapp`, `whatsappid` |
| Neden (isteğe bağlı) | `reason`, `note`, `notes` |
| Kanal (isteğe bağlı geçersiz kılma) | `channel` |
Her satır telefon / e-posta / wa\_id'den **en az birini** içermelidir. Tek
bir satır birden fazla adres türü taşıyabilir — her biri kendi bastırma
girişini üretir. Örnek:
```csv theme={null}
phone,email,reason
+14155550101,,replied STOP
,jordan@example.com,unsubscribed via email
+442071838750,sam@example.co.uk,complaint
```
Bir `channel` sütunu varsa o satır için varsayılan kapsamı geçersiz kılar
ve yukarıda listelenen kapsam değerlerinden biri olmalıdır.
### Satır başına sonuçlar
Yanıt, satır başına sonuçları raporlar. Kabul edilen satırlar yazılır;
diğerleri sınıflandırılır, asla sessizce atılmaz.
```json theme={null}
{
"data": {
"run_id": "supimp_4d…",
"total_rows": 1000,
"accepted": 950,
"duplicates": 30,
"intra_file_duplicates": 15,
"invalid": 5,
"errors": [
{ "status": "invalid", "reason": "invalid_phone", "raw_line": 42 }
],
"by_channel": { "all": 800, "email": 150 },
"file_sha256": "9b2e…"
},
"meta": { "request_id": "…", "timestamp": "2026-06-08T12:00:00.000Z" }
}
```
| Sayaç | Anlam |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `accepted` | Bastırma listesine yeni yazılan satırlar. |
| `intra_file_duplicates` | Bu aynı dosya **içinde** önceki bir `(channel, address)` değerini tekrarlayan satırlar. |
| `duplicates` | **Önceki** bir içe aktarımdan zaten bastırılmış olan satırlar (atlandı, işlem yok). |
| `invalid` | Doğrulamayı geçemeyen satırlar — bkz. `errors[]`. |
| `by_channel` | Kanal kapsamına göre gruplandırılmış kabul sayımları. |
| `file_sha256` | Denetim için kaydedilen yükleme içerik karması. |
İki yinelenen sayaç **bilerek ve ayrı olarak** rapor edilir:
`intra_file_duplicates`, az önce yüklediğiniz dosya içindeki
tekrarlardır; `duplicates` ise önceki içe aktarımlardan zaten
listenizdeydi. İkisi de hata değildir ve ikisi de sessizce yutulmaz —
ikisi de sayılır ki mutabakatınız tutsun.
### Doğrulama nedenleri
Her `errors[]` girişi, düzeltip yeniden yükleyebilmeniz için dost bir
`reason` ve kaynak `raw_line` taşır:
| `reason` | Neden |
| ------------------ | ----------------------------------------------- |
| `missing_address` | Satırda telefon, e-posta veya wa\_id yoktu. |
| `invalid_phone` | Telefon E.164'e normalleştirilemedi. |
| `invalid_email` | E-posta RFC-5321 biçim doğrulamasını geçemedi. |
| `invalid_wa_id` | WhatsApp ID geçerli bir E.164 numarası değildi. |
| `row_too_long` | Bir hücre 4.096 karakteri aştı. |
| `too_many_columns` | Satırda 32'den fazla sütun vardı. |
### Sınırlar
| Sınır | Değer |
| ------------------------- | ---------------------------------------------------------------------------- |
| Maks dosya boyutu | 25 MB |
| İstek başına maks satır | 100.000 |
| Maks hücre uzunluğu | 4.096 karakter |
| Satır başına maks sütun | 32 |
| Maks neden uzunluğu | 512 karakter |
| Sunucu tarafı zaman aşımı | 60 sn (kısmi bir içe aktarım, o ana kadar işlenen sayımlarla `408` döndürür) |
100.000 satırı aşan hacimler için dosyayı bölün ve toplu işler hâlinde
içe aktarın — yinelenen algılama, örtüşen aralıkları yeniden içe
aktarmayı güvenli kılar.
### İçe aktarım başarısız olduğunda
Hataları iki düzeyde tanılayın: **HTTP düzeyi reddetmeler** (hiçbir şey
yazılmaz) ve **satır düzeyi sınıflandırmalar** (dosya kabul edilir ama
belirli satırlar edilmez).
HTTP düzeyi reddetmeleri:
| Durum | Anlam | Nasıl düzeltilir |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400 NO_FILE` | Multipart gövdesinde `file` parçası yok. | CSV'yi multipart `file` alanı olarak ekleyin. |
| `400 MULTIPLE_FILES` | Birden fazla dosya eklendi. | İstek başına tek CSV gönderin. |
| `400 CSV_PARSE_ERROR` | Bozuk tırnaklama — kapatılmamış bir `"` veya eksik başlık satırı. | RFC-4180 CSV (UTF-8) olarak yeniden dışa aktarın; her tırnağın kapanış eşi olduğunu denetleyin. |
| `400 MULTIPART_PARSE_FAILED` | Gövde geçerli multipart/form-data değildi. | `Content-Type: multipart/form-data` ayarlayın ve gövdeyi önceden kodlamayın. |
| `408 IMPORT_TIMEOUT` | Çalışma 60 saniyelik bütçeyi aştı. Yanıt, zaten bastırılmış satırları adlandırır; kalanlar bastırılmaz. | Kalanı daha küçük dosyalara bölüp yeniden çalıştırın — zaman aşımından önce bastırılan satırlar `duplicates` olarak raporlanır. |
| `413 PAYLOAD_TOO_LARGE` | Dosya 25 MB'ı aşıyor. | Her biri 25 MB altında dosyalara bölün. |
| `413 TOO_MANY_ROWS` | Ayrıştırılan dosya 100.000 satırı aşıyor. | Her biri ≤ 100.000 satır olan dosyalara bölün. |
| `415 UNSUPPORTED_MEDIA_TYPE` | Yükleme bir CSV değildi (`.xlsx` dışa aktarmak yaygın tetikleyicidir). | CSV (UTF-8) olarak yeniden dışa aktarın. |
| `422 MISSING_ADDRESS_COLUMN` | Başlık satırında tanınabilir adres sütunu yok. | Başlık olarak `phone`, `email`, `wa_id`'den en az birini ekleyin (takma adlar [CSV biçimi](#csv-format) altında listelenir). |
| `422 VALIDATION_ERROR` | İsteğe bağlı bir form alanı doğrulamayı geçemedi. | `default_country`'nin 2 harfli ISO kodu ve `default_reason`'in ≤ 512 karakter olduğunu denetleyin. |
| `429` | Bir dakikada 5'ten fazla içe aktarım isteği. | Pencerenin kapanmasını bekleyin, sonra yeniden deneyin — dürtmek yerine toplu işleri kuyruğa alın. |
Satır düzeyi sınıflandırmalar (başarılı bir içe aktarıma eşlik eden
`errors[]` girişleri) nedenlere şöyle karşılık gelir:
| `reason` | Neden | Nasıl düzeltilir |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `missing_address` | Satırda telefon, e-posta veya wa\_id yoktu — ya da `channel` geçersiz kılması izin verilen kapsamlardan biri değildi. | En az bir adres hücresi doldurun; `channel` sütununu yukarıda listelenen kapsam değerleriyle sınırlayın. |
| `invalid_phone` | Telefon E.164'e normalleştirilemedi. | Numarayı düzeltin veya ulusal biçimdeki numaraların ayrıştırılması için `default_country` geçin. |
| `invalid_email` | E-posta RFC-5321 biçim doğrulamasını geçemedi (veya 254 karakteri aştı). | Adresi düzeltin; sürüklenebilir boşluklar ve eksik bir `@` olağan şüphelilerdir. |
| `invalid_wa_id` | WhatsApp ID geçerli bir E.164 numarası değildi. | Alıcının MSISDN'sini E.164 biçiminde kullanın (baştaki `+` isteğe bağlı). |
| `row_too_long` | Bir hücre 4.096 karakteri aştı. | Hücreyi kısaltın — genellikle yanlış sütuna yapıştırılmış bir bloğa denk gelir. |
| `too_many_columns` | Satırda 32'den fazla sütun vardı. | Tek bir ayraçla yeniden dışa aktarın; bir hücre içindeki tırnaksız virgüller onu hayalet sütunlara böler. |
Yalnızca ilk 100 `errors[]` girişi tam ayrıntıyla döndürülür — `invalid`
sayacı her zaman gerçek toplamı yansıtır. Pano sihirbazı (aşağıda)
ortaya çıkan satırları indirilebilir bir `skipped.csv` olarak paketler,
böylece yalnızca başarısız olanları düzeltip yeniden içe aktarabilirsiniz.
### Panodan içe aktarma
Aynı uç nokta, **Ayarlar → Uyumluluk → Vazgeçme listeleri → Bastırma
listesini içe aktar** yolundaki kılavuzlu bir sihirbazla sarmalanır —
aynı CSV sözleşmesi, terminal gerekmez.
1. **CSV dosyası seçin** — 25 MB altında bir `.csv` seçin. Önceden
biçimlendirilmiş bir başlangıç dosyası için iletişim kutusundaki
**Örnek CSV indir** seçeneğini kullanın.
2. **Varsayılanları ayarlayın (isteğe bağlı)** — ulusal biçimdeki
numaraları normalleştirmek için bir `Varsayılan ülke` (ISO alpha-2)
ve her kabul edilen satıra damgalanan serbest metin bir `Neden`.
3. **Önizleme** — içe aktarımı sunucu tarafında bir kuru çalıştırma
olarak çalıştırır: hiçbir şey yazılmaz ve siz işlemeden önce iletişim
kutusu kabul edilen / zaten listede / dosyada tekrar / geçersiz
dökümünü gösterir.
4. **İçe aktarımı onaylayın** — işleyen yazmayı gerçekleştirir. Herhangi
bir satır geçersizse, onları düzeltip yeniden içe aktarmak için
**`skipped.csv`** dosyasını indirin.
Sihirbaz ayrıca dosya türü ve 25 MB denetimlerini istemci tarafında
zorlar, böylece yanlış türde bir dışa aktarım API'ye hiç ulaşmadan
başarısız olur.
***
## Bastırma listesini dışa aktarma
`GET /compliance/suppression-list/export`, bastırma defterini indirir —
yukarıdaki [içe aktarımın](#bulk-csv-import) simetrik karşılığı. Belirli
bir anda hangi adreslerin bastırıldığını bir düzenleyiciye veya denetçiye
kanıtlamak için kullanın; eşleşen kişisi olmayan toplu içe aktarılmış
numaralar dahil.
```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/suppression-list/export?format=csv&status=active" \
-H "Authorization: Bearer $ORBIT_API_KEY" \
-o suppression-list.csv
```
Sorgu parametreleri:
| Parametre | Tür | Notlar |
| ------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `format` | enum | `csv` (varsayılan) veya `json`. |
| `channel` | enum | Tek bir kanal kapsamıyla sınırlayın. |
| `status` | enum | `active` (varsayılan — her gönderi kapısının gerçekten zorladığı küme), `revoked` veya `all`. |
| `from` / `to` | string | `suppressed_at` üzerinde tarih aralığı. Yalın bir `YYYY-MM-DD` tarihi veya RFC-3339 tarih-saati. |
| `limit` | integer | Dahil edilecek satırlar (1–50.000, varsayılan 50.000). |
Her satır `suppression_id`, `channel`, `address`, türetilmiş `status`
(`active` veya `revoked`), `reason`, `source`, `contact_id` (kişisi
olmayan toplu içe aktarılmış adresler için boş), `notes` ve
`suppressed_at` / `revoked_at` / `created_at` zaman damgalarını taşır.
Erişim **sahip** ve **yönetici** anahtarlarıyla sınırlıdır ve her dışa
aktarım çalışması denetim günlüğüne yazılır. Defter 50.000 satırı
aştığında CSV yanıtı bir `X-Export-Truncated: true` başlığı taşır (JSON
eşdeğeri `truncated: true` ayarlar) — kanala göre daraltın veya art arda
tarih pencereleri dışa aktararak kalanı yakalayın.
***
## Bastırmanın etkili olduğunu doğrulama
Güvenin ama doğrulayın: bir içe aktarımdan (veya herhangi bir vazgeçme
olayından) sonra, listeyi bir kampanyaya teslim etmeden önce gönderi
kapısının adresi gerçekten engellediğini doğrulayın.
1. **Bastırılmış adrese bir test mesajı gönderin.** Bastırılmış bir
alıcıya doğrudan API gönderimi, HTTP 422 ve `RECIPIENT_OPTED_OUT`
hata koduyla eşzamanlı olarak başarısız olur. [Kum havuzu
modunda](/sandbox/magic-numbers) hiçbir taşıyıcıya dokunulmaz ve
bakiye düşülmez; `8` ile biten herhangi bir alıcı ayrıca simüle
edilmiş `blocked` teslimat makbuzuna çözümlenir, bu da aynı engelin
taşıyıcı tarafı görünümüdür.
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
-H "X-API-Key: $ORBIT_SANDBOX_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+14155550101", "from": "+15005550101", "body": "gate check"}'
```
```json theme={null}
{
"error": {
"code": "RECIPIENT_OPTED_OUT",
"message": "Recipient has opted out of this channel"
}
}
```
Aynı adrese bir kampanya gönderimi, tasarım gereği farklı davranır:
alıcı sessizce atlanır (`status: "skipped"`, `reason: "opted_out"`)
böylece toplu iş ilerlemeye devam eder — hata beklemek yerine
kampanyanın alıcı başına raporunu denetleyin.
2. **Girişin defterde olduğunu doğrulayın.** Yukarıdaki
[sorguyla](#export-the-suppression-list) dışa aktarın (`status=active`
varsayılandır) ve adresin beklenen `channel` kapsamıyla göründüğünü
denetleyin. Dışa aktarım, her gönderi kapısının okuduğu gerçeğin
kaynağıdır — satır orada `active` ise, engel dikidir.
İki denetim farklı soruları yanıtlar: 1. adım zorlamayı kanıtlar (kapı
ateşlenir), 2. adım kapsamı kanıtlar (giriş, istediğiniz kanalla vardır).
***
## Bastırmayı kaldırma (yeniden katılım)
Bir adresi geri getirmek için [Consent
API](/compliance/consent-management) üzerinden yeni bir katılım
(`opt_in: true`) kaydedin. Bu, eşleşen bastırma girişini iptal eder ve
STOP engelini kaldırır. Belgeli, yeni bir izin olayı olmadan önceden
bastırılmış bir kişiye asla yeniden mesaj göndermeyin.
**Engelin kaldırıldığını doğrulama.** `status=revoked` ile dışa aktarın
ve adresi bulun: satır denetim için hâlâ oradadır, `status: revoked` ve
bir `revoked_at` zaman damgasıyla — bastırma geçmişi asla silinmez,
yalnızca iptal edilir. Ardından [Bastırmanın etkili olduğunu
doğrulama](#verify-a-suppression-took-effect) bölümündeki gibi adrese
küçük bir test mesajı gönderin: başarılı bir gönderim
(`RECIPIENT_OPTED_OUT` yok) kapının artık iptal edilmiş geçmişe
ateşlenmediğini doğrular. İki denetim de geçene kadar adresi hâlâ
engelli sayın.
***
## İlgili başvurular
* [İzin Yönetimi](/compliance/consent-management) — kanal başına izni
kaydedin ve arayın.
* [Send Gates](/compliance/send-gates) — sessiz saatler, DNC, RND, RMD,
acil durdurma ve tercih merkezi.
* [DSAR](/compliance/dsar) — `delete` / `opt_out` isteklerinin bastırmaya
nasıl ulaştığı.
* [API Başvurusu → Vazgeçmeler](/api-reference/optouts) — vazgeçme ve
bastırma uç nokta şemaları.