Suppressions API

Suppressions API מנהל, לכל סביבת עבודה, את רשימות החסימה של כתובות אימייל ומספרי טלפון שאליהם Joryio לא תשלח. חסימה היא שער קשיח: כל עוד מזהה מסוים חסום בערוץ, כל הודעה אליו באותו ערוץ תדולג - ללא תלות בקמפיין או במסע שמנסה להגיע אליו.

ה־API הזה משקף את המסך Audience → Suppression Lists בלוח הבקרה. השתמשו בו כדי לבדוק אילו נמענים חסומים, לייבא רשימה קיימת של כתובות לא תקינות מפלטפורמה אחרת, לכבד בקשות הסכמה מהמערכות שלכם או להסיר חסימה לאחר פתרון החזרה קשה.

כל נקודות הקצה בעמוד זה יחסיות לכתובת הבסיס: https://api-eu1.joryio.com - ראו סקירת API.

אימות

כל בקשה מאומתת באמצעות מפתח API בעל ההרשאה המתאימה ליכולת המסירה, או באמצעות סשן של לוח הבקרה (JWT). נתוני החסימה מוגבלים לסביבת העבודה - מפתח יכול לראות ולערוך רק את הרשימות בסביבת העבודה שלו.

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

הרשאות לכל נקודת קצה

הערוץ קובע איזו הרשאה נדרשת. נקודות קצה של אימייל דורשות email_suppression:*; נקודות קצה של SMS ושל WhatsApp דורשות sms_suppression:*.

Endpoint	ערוץ אימייל	ערוץ SMS / WhatsApp
`GET /suppressions`	`email_suppression:read`	`sms_suppression:read`
`GET /suppressions/{identifier}`	`email_suppression:read`	`sms_suppression:read`
`POST /suppressions`	`email_suppression:write`	`sms_suppression:write`
`POST /suppressions/hard-bounce`	`email_suppression:write`	- (אימייל בלבד)
`POST /suppressions/import`	`email_suppression:write`	`sms_suppression:write`
`DELETE /suppressions/{identifier}`	`email_suppression:write`	`sms_suppression:write`

מושגי יסוד

קראו את החלק הזה לפני שאתם קוראים לנקודות הקצה לכתיבה - שאר ה־API מובן רק לאחר שההבחנה בין reason ל־source ברורה.

`reason` (למה) מול `source` (מאיפה זה הגיע)

לכל שורת חסימה יש שני שדות בלתי תלויים:

reason - למה המזהה חסום. אחד מ־unsubscribe, hard_bounce, complaint, manual.
source - מהיכן הגיעה החסימה (המקור שלה). אחד מ־delivery, api, import או מקור הסכמה כגון unsubscribe_link.

השדות בלתי תלויים זה בזה. אותו reason יכול להגיע ממקורות שונים - hard_bounce שנצפה בצינור השליחה שלנו נושא source: "delivery", ואילו hard_bounce שאתם מדווחים עליו דרך ה־API הזה נושא source: "api". השדה reason מגדיר את המשמעות מבחינת יכולת מסירה או הסכמה; source מגדיר עד כמה אפשר לסמוך על המקור והאם הוא נספר במדדי המוניטין שלכם.

סיבות הסכמה לעומת סיבות של יכולת מסירה

ארבעת ערכי reason מתחלקים לשתי משפחות שמתנהגות אחרת:

משפחה	Reasons	משמעות	שורד re-subscribe?
הסכמה (Consent)	`unsubscribe`, `manual`	הנמען (או אתם, בשמו) ביקש לא לקבל פנייה.	לא - הצטרפות מחדש מנקה אותה.
יכולת מסירה	`hard_bounce`, `complaint`	הכתובת או המספר אינם פעילים, או שהנמען סימן אותנו כספאם.	כן - נשמר גם אם הנמען מצטרף מחדש.

חסימה מסיבות של יכולת מסירה היא מצב טכני של הכתובת, ולא העדפה - לכן הצטרפות מחדש של הנמען אינה מסירה אותה. החסימה מוסרת רק בפעולה מפורשת של מפעיל: DELETE /suppressions/{identifier}, הפעולה "clear bounce" בלוח הבקרה או שינוי כתובת האימייל של איש הקשר.

אי אפשר להמציא החזרה

נתיבי הכתיבה הרגילים - POST /suppressions ו־POST /suppressions/import - מגבילים את reason ל־manual או unsubscribe. הם אינם יכולים ליצור שורת hard_bounce או complaint. החזרה היא אירוע שהפלטפורמה צופה בו, ולא טענה שלקוח יכול למסור ללא בקרה.

הנתיב היחיד שמאפשר לדווח על החזרה הוא POST /suppressions/hard-bounce; גם אז השורה מסומנת source: "api", כדי שלא תתבלבל עם החזרה שצפינו בה בעצמנו.

רק החזרות אמיתיות משפיעות על המוניטין שלכם

שיעור ההחזרות המדווח של החשבון ומדדי יכולת המסירה והמוניטין סופרים רק החזרות עם source: "delivery" - אלה שצינור השליחה שלנו צפה בהן בשכבת SMTP. חסימה שדווחה דרך ה־API (source: "api") או יובאה (source: "import") חוסמת שליחה למזהה, אך אינה מנפחת את שיעור ההחזרות המדווח. כך אפשר לטעון מראש כתובות שידוע שאינן פעילות ולהגן על מוניטין השולח בלי לעוות את המדד שמנסים להגן עליו.

החסימה חלה לפי הכתובת או המספר

חסימה ממופה לפי כתובת האימייל המנורמלת או מספר הטלפון בכל סביבת עבודה - לא לפי רשומת איש קשר. לכן חסימה של כתובת אחת מכסה כל איש קשר כפול שחולק אותה. חסמו את jane@example.com פעם אחת, וכל אנשי הקשר עם הכתובת הזו ייחסמו באימייל בכל סביבת העבודה.

טבלת עזר ל־reason / source

ערכי `reason`

`reason`	משפחה	נוצר על ידי
`unsubscribe`	הסכמה	קישור opt-out של נמען, `POST /suppressions`, `POST /suppressions/import`
`manual`	הסכמה	פעולת מפעיל, `POST /suppressions`, `POST /suppressions/import`
`hard_bounce`	יכולת מסירה	צינור השליחה שלנו, `POST /suppressions/hard-bounce`
`complaint`	יכולת מסירה	צינור השליחה שלנו (לולאות משוב)

ערכי `source`

`source`	משמעות	נספר למוניטין?
`delivery`	נצפה בצינור השליחה או הקבלה שלנו (החזרה או תלונה אמיתית).	כן
`api`	הוצהר דרך ה־REST API הזה.	לא
`import`	נטען דרך `POST /suppressions/import` (הגירה באצווה).	לא
`unsubscribe_link` (ומקורות הסכמה אחרים)	שינוי הסכמה ביוזמת הנמען.	לא

הצגת חסימות

מחזיר רשימה עם עימוד של מזהים חסומים בערוץ.

Endpoint

GET /suppressions

פרמטרי שאילתה

פרמטר	סוג	ברירת מחדל	תיאור
`channel`	string	-	`email`, `sms`, או `whatsapp`. חובה.
`reason`	string	-	מסנן אופציונלי: `unsubscribe`, `hard_bounce`, `complaint` או `manual`.
`limit`	number	`100`	שורות לעמוד (לכל היותר `1000`).
`offset`	number	`0`	היסט לעימוד.

דוגמת בקשה

curl -X GET "https://api-eu1.joryio.com/suppressions?channel=email&reason=hard_bounce&limit=50" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "items": [
    {
      "identifier": "dead-address@example.com",
      "channel": "email",
      "identifierType": "email",
      "reason": "hard_bounce",
      "source": "delivery",
      "scope": "global",
      "listId": null,
      "createdAt": "2026-06-30T12:04:11.000Z"
    },
    {
      "identifier": "jane@example.com",
      "channel": "email",
      "identifierType": "email",
      "reason": "unsubscribe",
      "source": "unsubscribe_link",
      "scope": "group",
      "listId": "grp_newsletter",
      "createdAt": "2026-07-02T09:20:00.000Z"
    }
  ],
  "total": 214,
  "limit": 50,
  "offset": 0
}

בדיקת מזהה בודד

בודק אם מזהה בודד חסום בערוץ.

Endpoint

GET /suppressions/{identifier}

פרמטר הנתיב {identifier} הוא כתובת האימייל או מספר הטלפון, מקודדים ל־URL.

פרמטרי שאילתה

פרמטר	סוג	ברירת מחדל	תיאור
`channel`	string	-	`email`, `sms`, או `whatsapp`. חובה.

דוגמת בקשה

curl -X GET "https://api-eu1.joryio.com/suppressions/dead-address@example.com?channel=email" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה - חסום

{
  "suppressed": true,
  "identifier": "dead-address@example.com",
  "reason": "hard_bounce",
  "source": "delivery",
  "scope": "global",
  "listId": null,
  "createdAt": "2026-06-30T12:04:11.000Z"
}

תגובה - לא חסום

{
  "suppressed": false
}

הוספת חסימה

מוסיף חסימה מטעמי הסכמה או חסימה ידנית. השתמשו בכך כדי לכבד opt-out שהגיע אליכם דרך המערכות שלכם (פנייה לתמיכה, דגל ב־CRM או שינוי במרכז ההעדפות שלכם).

Endpoint

POST /suppressions

גוף הבקשה

שדה	סוג	חובה	תיאור
`channel`	string	כן	`email`, `sms`, או `whatsapp`.
`identifier`	string	כן	כתובת אימייל או מספר טלפון לחסימה.
`reason`	string	לא	`manual` (ברירת מחדל) או `unsubscribe`. מוגבל - כל ערך אחר נדחה.
`scope`	string	לא	`global` (ברירת מחדל) או `group`.
`listId`	string	לא	חובה כאשר `scope` הוא `group`: הקבוצה או הרשימה שעליה החסימה חלה.

ה־source של שורה שנוצרת כאן נרשם תמיד כ־api. נקודת הקצה הזו אינה יכולה ליצור hard_bounce או complaint.

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/suppressions \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "identifier": "jane@example.com",
    "reason": "unsubscribe",
    "scope": "group",
    "listId": "grp_newsletter"
  }'

תגובה

{
  "identifier": "jane@example.com",
  "channel": "email",
  "identifierType": "email",
  "reason": "unsubscribe",
  "source": "api",
  "scope": "group",
  "listId": "grp_newsletter",
  "createdAt": "2026-07-11T08:15:00.000Z"
}

דיווח על החזרה קשה

רושם החזרה קשה עבור כתובת אימייל. זהו הנתיב היחיד ב־API שמאפשר לדווח על חסימה בשל יכולת מסירה, והוא נפרד ומוגבל בכוונה.

למה נקודת הקצה הזו נפרדת

בדרך כלל Joryio צופה בהחזרה בזמן השליחה; הקורא אינו אמור להכריז עליה. הפרדת הדיווח על החזרה מנתיבי ההוספה והייבוא הרגילים מונעת יצירה שגויה או רשלנית של נתונים כאלה.
מכיוון שאתם מדווחים על ההחזרה במקום שאנחנו נצפה בה, השורה מסומנת source: "api". היא חוסמת שליחה בדיוק כמו החזרה אמיתית, אך אינה מתבלבלת עם החזרה שראינו בעצמנו ואינה נספרת בשיעור ההחזרות המדווח או במדדי מוניטין השולח.
הוא אימייל בלבד. אין מקבילה לטלפון - אי־מסירה ב־SMS/WhatsApp ממודלת אחרת.

Endpoint

POST /suppressions/hard-bounce

גוף הבקשה

שדה	סוג	חובה	תיאור
`identifier`	string	כן	כתובת האימייל שחזרה בהחזרה קשה.

הערוץ הוא email באופן משתמע. השורה נרשמת עם reason: "hard_bounce" ו־source: "api".

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/suppressions/hard-bounce \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "no-such-mailbox@example.com"
  }'

תגובה

{
  "identifier": "no-such-mailbox@example.com",
  "channel": "email",
  "identifierType": "email",
  "reason": "hard_bounce",
  "source": "api",
  "scope": "global",
  "listId": null,
  "createdAt": "2026-07-11T08:20:00.000Z"
}

ייבוא באצווה

טוען רשימת חסימה קיימת - למשל בעת הגירה מפלטפורמה אחרת.

Endpoint

POST /suppressions/import

גוף הבקשה

שדה	סוג	חובה	תיאור
`channel`	string	כן	`email`, `sms`, או `whatsapp`.
`entries`	array	כן	עד `5000` אובייקטים, כל אחד `{ identifier, reason? }`.

ה־reason של כל רשומה מוגבל ל־manual (ברירת מחדל) או unsubscribe; כל ערך אחר מומר ל־manual. כל שורה מיובאת נרשמת עם source: "import". כמו בנקודת הקצה להוספה, הייבוא אינו יכול ליצור החזרה או תלונה.

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/suppressions/import \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "entries": [
      { "identifier": "old-dead-1@example.com" },
      { "identifier": "opted-out@example.com", "reason": "unsubscribe" },
      { "identifier": "old-dead-2@example.com" }
    ]
  }'

תגובה

{
  "channel": "email",
  "received": 3,
  "imported": 3,
  "skipped": 0,
  "source": "import"
}

הסרת חסימה (unsuppress)

מסיר חסימה כדי ש־Joryio תוכל לשלוח שוב למזהה.

Endpoint

DELETE /suppressions/{identifier}

פרמטרי שאילתה

פרמטר	סוג	ברירת מחדל	תיאור
`channel`	string	-	`email`, `sms`, או `whatsapp`. חובה.

אזהרה

פעולה זו מסירה את כל שורות החסימה של המזהה בערוץ בסביבת העבודה הזו - כולל שורת יכולת מסירה מסוג hard_bounce או complaint. זו הסרה מכוונת בידי מפעיל או דרך ה־API: הסרת חסימה של כתובת היא הדרך לנקות החזרה קשה שנפתרה. הסירו חסימה בשל יכולת מסירה רק לאחר שווידאתם שהבעיה הבסיסית תוקנה, אחרת אתם מסתכנים בשליחה לכתובת שאינה פעילה ובפגיעה במוניטין השולח.

דוגמת בקשה

curl -X DELETE "https://api-eu1.joryio.com/suppressions/no-such-mailbox@example.com?channel=email" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "identifier": "no-such-mailbox@example.com",
  "removed": 2
}

removed הוא מספר שורות החסימה שנמחקו (מזהה יחיד יכול לשאת בו־זמנית שורת הסכמה ברמת group ושורת יכולת מסירה ברמת global).

הגירת רשימת חסימה קיימת

כשאתם עוברים ל־Joryio מפלטפורמת אימייל או SMS אחרת, הביאו איתכם את רשימת החסימה כבר ביום הראשון, כדי שהשליחה הראשונה לא תגיע שוב לכתובות שאתם כבר יודעים שאינן פעילות או שביקשו opt-out.

ייבאו את כל הרשימה דרך POST /suppressions/import. הרשומות מגיעות כ־manual (או unsubscribe אם תתייגו אותן), עם source: "import". הן חוסמות שליחה ומגינות על מוניטין השולח כבר בשליחה הראשונה - בלי לנפח את שיעור ההחזרות המדווח, מפני ששורות מיובאות לעולם אינן נספרות למוניטין.
רק אם אתם צריכים שהכתובות האלה ידווחו כהחזרות - למשל כדי לשמור על רציפות אנליטיקת ההחזרות לאורך ההגירה - דווחו עליהן אחת־אחת באמצעות POST /suppressions/hard-bounce. הן עדיין יסומנו source: "api", ולכן יחסמו שליחה ויופיעו כהחזרות ברשימת החסימה בלי להיספר כהחזרות שאנחנו צפינו בהן.

עבור רוב ההגירות, שלב 1 לבדו הוא הבחירה הנכונה: הוא עוצר את השליחות ושומר על מדדי המוניטין שלכם נקיים.

תגובות שגיאה

כל השגיאות משתמשות במבנה הסטנדרטי - אין אוסף נפרד של קודי שגיאה לקריאה ממוכנת; השתמשו בקוד המצב של HTTP יחד עם השדה message. ראו תגובת שגיאה בסקירת ה־API. כשלי תיקוף (400) מוסיפים מערך errors עם הודעה לכל שדה שנכשל:

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-07-12T09:00:00.000Z",
  "path": "/suppressions",
  "errors": [
    "reason must be one of the following values: manual, unsubscribe"
  ]
}

שימו לב: ה־API הזה אוכף הרשאות מדויקות לפי ערוץ. מפתח API שמחזיק רק בהרשאת ה־SMS יקבל 403 כשהוא ניגש לחסימות אימייל (ולהפך):

{
  "statusCode": 403,
  "message": "API key missing required scope 'email_suppression:write' for channel 'email'",
  "timestamp": "2026-07-12T09:00:00.000Z",
  "path": "/suppressions"
}

אימות​

הרשאות לכל נקודת קצה​

מושגי יסוד​

reason (למה) מול source (מאיפה זה הגיע)​

סיבות הסכמה לעומת סיבות של יכולת מסירה​

אי אפשר להמציא החזרה​

רק החזרות אמיתיות משפיעות על המוניטין שלכם​

החסימה חלה לפי הכתובת או המספר​

טבלת עזר ל־reason / source​

ערכי reason​

ערכי source​

הצגת חסימות​

Endpoint​

פרמטרי שאילתה​

דוגמת בקשה​

תגובה​

בדיקת מזהה בודד​

Endpoint​

פרמטרי שאילתה​

דוגמת בקשה​

תגובה - חסום​

תגובה - לא חסום​

הוספת חסימה​

Endpoint​

גוף הבקשה​

דוגמת בקשה​

תגובה​

דיווח על החזרה קשה​

למה נקודת הקצה הזו נפרדת​

Endpoint​

גוף הבקשה​

דוגמת בקשה​

תגובה​

ייבוא באצווה​

Endpoint​

גוף הבקשה​

דוגמת בקשה​

תגובה​

הסרת חסימה (unsuppress)​

Endpoint​

פרמטרי שאילתה​

דוגמת בקשה​

תגובה​

הגירת רשימת חסימה קיימת​

תגובות שגיאה​

הצעדים הבאים​

אימות

הרשאות לכל נקודת קצה

מושגי יסוד

`reason` (למה) מול `source` (מאיפה זה הגיע)

סיבות הסכמה לעומת סיבות של יכולת מסירה

אי אפשר להמציא החזרה

רק החזרות אמיתיות משפיעות על המוניטין שלכם

החסימה חלה לפי הכתובת או המספר

טבלת עזר ל־reason / source

ערכי `reason`

ערכי `source`

הצגת חסימות

Endpoint

פרמטרי שאילתה

דוגמת בקשה

תגובה

בדיקת מזהה בודד

Endpoint

פרמטרי שאילתה

דוגמת בקשה

תגובה - חסום

תגובה - לא חסום

הוספת חסימה

Endpoint

גוף הבקשה

דוגמת בקשה

תגובה

דיווח על החזרה קשה

למה נקודת הקצה הזו נפרדת

Endpoint

גוף הבקשה

דוגמת בקשה

תגובה

ייבוא באצווה

Endpoint

גוף הבקשה

דוגמת בקשה

תגובה

הסרת חסימה (unsuppress)

Endpoint

פרמטרי שאילתה

דוגמת בקשה

תגובה

הגירת רשימת חסימה קיימת

תגובות שגיאה

הצעדים הבאים