Subscriptions API

Subscriptions API הוא ממשק ההסכמה של Joryio. הוא מנהל, לכל איש קשר, את מצב ה־opt-in/opt-out בכל ערוץ הודעות (אימייל, SMS, WhatsApp, פוש ו־Viber), חברות ברשימות הרשמה (קטגוריות הסכמה או נושאים), מצב החזרות באימייל והיסטוריית ביקורת מלאה של שינויי ההסכמה.

העמוד מכסה שלושה משאבים:

הסכמה של איש קשר - /subscriptions/contacts/...: קריאה ושינוי של הסכמת הערוצים והרשימות של איש קשר בודד.
רשימות הרשמה - /lists: יצירה וניהול של הרשימות עצמן, כולל פעולות חברות באצווה.
עמוד העדפות מתארח - /subscriptions/hosted-page: עריכת העמוד המתארח של מרכז ההעדפות בסביבת העבודה.

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

אימות

כל בקשה דורשת אימות באמצעות מפתח API (אפשר להשתמש גם בטוקן JWT של סשן לוח הבקרה):

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

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

Endpoint	Scope
`GET /subscriptions/contacts/:userId`	`compliance:read`
`PUT /subscriptions/contacts/:userId/channels/:channel`	`compliance:write`
`POST /subscriptions/contacts/:userId/clear-bounce`	`compliance:write`
`GET /subscriptions/contacts/:userId/lists`	`compliance:read`
`POST /subscriptions/contacts/:userId/lists/:listId`	`compliance:write`
`DELETE /subscriptions/contacts/:userId/lists/:listId`	`compliance:write`
`GET /subscriptions/contacts/:userId/history`	`compliance:read`
`GET /subscriptions/contacts/:userId/channels/:channel/status`	`compliance:read`
`GET /subscriptions/contacts/:userId/email-valid`	`compliance:read`
`POST /lists`	`settings:write`
`GET /lists`, `GET /lists/:listId`, `GET /lists/:listId/stats`	`settings:read`
`GET /lists/:listId/members`	`compliance:read`
`PUT /lists/:listId`, `DELETE /lists/:listId`, `POST /lists/:listId/restore`	`settings:write`
`POST /lists/:listId/members/bulk`, `DELETE /lists/:listId/members/bulk`	`settings:write`
`GET /subscriptions/hosted-page/preference-center`, `POST /subscriptions/hosted-page/preview`	`settings:read`
`PUT /subscriptions/hosted-page/preference-center`	`settings:write`

מושגי יסוד

מזהה איש הקשר

כל נתיב /subscriptions/contacts/:userId מקבל את מזהה איש הקשר הפנימי של Joryio - ה־id שמוחזר מה־Users API - ולא את ה־userId החיצוני שאתם שולחים באירועים. המזהה חייב להיות ObjectId של 24 תווים הקסדצימליים (או UUID); כל ערך אחר נדחה עם 400 Bad Request.

רישום כבר בזמן היצירה

אפשר לצרף איש קשר לרשימות כבר בקריאה שיוצרת אותו: POST /users מקבל מערך subscriptions אופציונלי (הצטרפות בקריאה אחת) - ראו Users API. נקודות הקצה העצמאיות בעמוד זה הן הדרך לנהל הסכמה לאחר היצירה: הגדירו הסכמה לערוץ באמצעות PUT /subscriptions/contacts/:userId/channels/:channel וחברות ברשימה באמצעות POST /subscriptions/contacts/:userId/lists/:listId. הרשמות בזמן היצירה לעולם אינן מבטלות opt-out קיים - הצטרפות מפורשת מחדש חייבת להתבצע באמצעות POST /subscriptions/contacts/:userId/lists/:listId.

ערוצים

קיימים חמישה ערוצי הרשמה: email, sms, whatsapp, push, viber. כל ערך ערוץ אחר מחזיר 400 Bad Request.

ערכי סטטוס

סטטוס	תיאור
`optedIn`	הצטרפות מפורשת (למשל אישור double opt-in)
`subscribed`	מנוי (single opt-in / ברירת מחדל)
`unsubscribed`	ביטל הרשמה

ערכי הסטטוס הם camelCase - optedIn, לא opted_in. איש קשר ללא סטטוס רשום לערוץ נחשב מנוי מבחינת שערי השליחה ("אין רשומה" אינו opt-out).

שינויי הסכמה נרשמים ומשוכפלים

כל כתיבה דרך ה־API הזה נרשמת ביומן ביקורת ההרשמות של איש הקשר (עם המקור, כתובת ה־IP, ה־user agent וזהות מפתח ה־API או המנהל שביצע את הפעולה), וניתנת לשליפה דרך נקודת הקצה להיסטוריה. בנוסף, ביטולי הרשמה משוכפלים לרשימות חסימה לפי מזהה - ביטול הרשמה ב־SMS או ב־WhatsApp חל לפי מספר הטלפון, וביטול הרשמה באימייל חל לפי הכתובת בכל סביבת העבודה, כך שגם אנשי קשר כפולים שחולקים את המזהה מכוסים. ראו Suppressions API.

הסכמה של איש קשר

קבלת ההרשמות של איש קשר

מחזיר את מצב ההסכמה לכל ערוץ של איש הקשר, יחד עם החברות שלו ברשימות.

Endpoint

GET /subscriptions/contacts/:userId

פרמטרים בנתיב

פרמטר	סוג	תיאור
`userId`	string	מזהה איש הקשר ב-Joryio

דוגמת בקשה

curl -X GET https://api-eu1.joryio.com/subscriptions/contacts/665f1c2ab3d4e5f6a7b8c9d0 \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "channels": {
    "email": {
      "status": "subscribed",
      "optInDate": "2026-05-14T09:21:07.000Z",
      "optInSource": "api",
      "consentText": "Send me product updates",
      "isValid": true,
      "bounceType": null,
      "bounceCount": 0
    },
    "sms": {
      "status": "unsubscribed",
      "optOutDate": "2026-06-02T18:40:00.000Z",
      "optInSource": "preference_center"
    }
  },
  "lists": [
    {
      "_id": "665f2e11aa22bb33cc44dd55",
      "organizationId": "org-uuid",
      "workspaceId": "ws-uuid",
      "contactId": "665f1c2ab3d4e5f6a7b8c9d0",
      "listId": "3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b",
      "channel": "email",
      "status": "subscribed",
      "subscribedAt": "2026-05-14T09:21:07.000Z",
      "optInSource": "api",
      "createdAt": "2026-05-14T09:21:07.000Z",
      "updatedAt": "2026-05-14T09:21:07.000Z"
    }
  ]
}

ערוצים שאין לאיש הקשר מצב רשום עבורם פשוט אינם מופיעים ב־channels. ערוץ האימייל כולל גם את שדות ההחזרה (isValid, bounceType, bounceCount, lastBounceAt). lists מחזיר את 500 רשומות החברות הראשונות של איש הקשר.

מחזיר 404 Not Found אם איש הקשר אינו קיים בסביבת העבודה.

עדכון הרשמה לערוץ

מגדיר את סטטוס ההסכמה של איש קשר לערוץ אחד.

Endpoint

PUT /subscriptions/contacts/:userId/channels/:channel

פרמטרים בנתיב

פרמטר	סוג	תיאור
`userId`	string	מזהה איש הקשר ב-Joryio
`channel`	string	`email`, `sms`, `whatsapp`, `push` או `viber`

גוף הבקשה

שדה	סוג	חובה	תיאור
`channel`	string	כן	חייב להתאים לערוץ שבנתיב (אם הם שונים - הערך שבנתיב גובר)
`status`	string	כן	`optedIn`, `subscribed` או `unsubscribed`
`source`	string	לא	מקור השינוי, למשל `api`, `preference_center` (ברירת מחדל `api`)
`consentText`	string	לא	טקסט ההסכמה שהוצג בעת ה־opt-in (נשמר לצורכי ציות)
`reason`	string	לא	סיבה בטקסט חופשי, שנשמרת ברשומת הביקורת

דוגמת בקשה

curl -X PUT https://api-eu1.joryio.com/subscriptions/contacts/665f1c2ab3d4e5f6a7b8c9d0/channels/email \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "status": "unsubscribed",
    "source": "preference_center",
    "reason": "User requested via support ticket"
  }'

תגובה

אובייקט ה־channels המעודכן והמלא של איש הקשר:

{
  "email": {
    "status": "unsubscribed",
    "optOutDate": "2026-07-12T10:15:00.000Z",
    "optInSource": "preference_center",
    "isValid": true,
    "bounceType": null,
    "bounceCount": 0
  },
  "sms": {
    "status": "subscribed",
    "optInDate": "2026-05-14T09:21:07.000Z"
  }
}

הערות התנהגות

opt-in (optedIn / subscribed) בערוץ האימייל מנקה מצב זמני של החזרה רכה, אך לעולם אינו מבטל החזרה קשה - פעולת הסכמה אינה מוכיחה שתיבת דואר שאינה פעילה חזרה לפעול. כדי להסיר החזרה קשה, השתמשו בניקוי מצב ההחזרה.
unsubscribed בערוצי sms או whatsapp משוכפל לרשימת החסימה לפי מספר טלפון (ה־opt-out חל לפי המספר בכל הארגון). שינוי מצב באימייל משוכפל לרשימה לפי כתובת בסביבת העבודה.
השינוי נרשם ביומן הביקורת עם כתובת ה־IP, ה־user agent וזהות המנהל או המפתח שביצע את הפעולה.

ניקוי מצב ההחזרה

מאפס את מצב ההחזרות באימייל של איש הקשר ומסיר את החסימה בשל יכולת מסירה לפי כתובת. זו הדרך המורשית להסיר החזרה קשה; הרשמה מחדש מצד הנמען אינה מסירה אותה.

Endpoint

POST /subscriptions/contacts/:userId/clear-bounce

גוף הבקשה

שדה	סוג	חובה	תיאור
`reason`	string	לא	סיבה בטקסט חופשי, שנשמרת ברשומת הביקורת

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/subscriptions/contacts/665f1c2ab3d4e5f6a7b8c9d0/clear-bounce \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Mailbox restored, confirmed with customer" }'

תגובה

{ "success": true }

מנקה את bounceType, bounceCount ו־lastBounceAt, ומחזיר את isValid ל־true. נוסף על כך, הפעולה מוחקת את שורות ה־hard_bounce וה־complaint של הכתובת מרשימת החסימה של סביבת העבודה, כך שהניקוי חל על כל אנשי הקשר הכפולים שחולקים את הכתובת.

קבלת הרשמות לרשימות

מחזיר את כל רשומות החברות של איש הקשר ברשימות, בין שההרשמה בהן פעילה ובין שבוטלה.

Endpoint

GET /subscriptions/contacts/:userId/lists

דוגמת בקשה

curl -X GET https://api-eu1.joryio.com/subscriptions/contacts/665f1c2ab3d4e5f6a7b8c9d0/lists \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

[
  {
    "_id": "665f2e11aa22bb33cc44dd55",
    "organizationId": "org-uuid",
    "workspaceId": "ws-uuid",
    "contactId": "665f1c2ab3d4e5f6a7b8c9d0",
    "listId": "3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b",
    "channel": "email",
    "status": "subscribed",
    "subscribedAt": "2026-05-14T09:21:07.000Z",
    "optInSource": "api",
    "createdAt": "2026-05-14T09:21:07.000Z",
    "updatedAt": "2026-05-14T09:21:07.000Z"
  }
]

החברות ייחודית לכל שילוב של איש קשר + רשימה + ערוץ: אותו איש קשר יכול להיות מנוי לרשימה ב־email ומבוטל ממנה ב־sms, כשתי רשומות נפרדות.

מצרף איש קשר לרשימה בערוץ אחד. הפעולה אידמפוטנטית - קריאה חוזרת מאשרת מחדש את ההרשמה. זהו גם נתיב ה־opt-in המפורש והמתועד ביומן הביקורת, שבאמצעותו אפשר לצרף מחדש איש קשר שביטל בעבר את הרשמתו לרשימה; הוספה באצווה לעולם אינה עושה זאת.

Endpoint

POST /subscriptions/contacts/:userId/lists/:listId

פרמטרים בנתיב

פרמטר	סוג	תיאור
`userId`	string	מזהה איש הקשר ב-Joryio
`listId`	string	מזהה רשימת ההרשמה (UUID)

גוף הבקשה

שדה	סוג	חובה	תיאור
`channel`	string	כן	`email`, `sms`, `whatsapp`, `push` או `viber`
`source`	string	לא	למשל `api`, `form`, `import`, `preference_center` (ברירת מחדל `api`)
`consentText`	string	לא	טקסט ההסכמה שהוצג בעת ה־opt-in

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/subscriptions/contacts/665f1c2ab3d4e5f6a7b8c9d0/lists/3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "email", "source": "api", "consentText": "Weekly newsletter signup" }'

תגובה

רשומת החברות שנוצרה או עודכנה:

{
  "_id": "665f2e11aa22bb33cc44dd55",
  "organizationId": "org-uuid",
  "workspaceId": "ws-uuid",
  "contactId": "665f1c2ab3d4e5f6a7b8c9d0",
  "listId": "3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b",
  "channel": "email",
  "status": "subscribed",
  "subscribedAt": "2026-07-12T10:20:00.000Z",
  "optInSource": "api",
  "consentText": "Weekly newsletter signup",
  "createdAt": "2026-07-12T10:20:00.000Z",
  "updatedAt": "2026-07-12T10:20:00.000Z"
}

ביטול הרשמת איש קשר מרשימה

מבטל הרשמה של איש קשר מרשימה בערוץ אחד. הערוץ עובר בגוף הבקשה, לא בנתיב.

Endpoint

DELETE /subscriptions/contacts/:userId/lists/:listId

גוף הבקשה

שדה	סוג	חובה	תיאור
`channel`	string	כן	`email`, `sms`, `whatsapp`, `push` או `viber`
`source`	string	לא	למשל `api`, `preference_center` (ברירת מחדל `api`)

דוגמת בקשה

curl -X DELETE https://api-eu1.joryio.com/subscriptions/contacts/665f1c2ab3d4e5f6a7b8c9d0/lists/3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "email", "source": "preference_center" }'

תגובה

{ "success": true }

אם לאיש הקשר לא הייתה רשומת חברות לרשימה + ערוץ אלה, נוצרת בכל זאת רשומת unsubscribed מפורשת - משיכת הסכמה לעולם אינה הולכת לאיבוד בשקט, ושער השליחה יחסום מעתה שליחות רשימה לאיש קשר זה.

קבלת היסטוריית הרשמות

מחזיר את יומן הביקורת של הסכמות איש הקשר, מהחדש לישן.

Endpoint

GET /subscriptions/contacts/:userId/history

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

פרמטר	סוג	ברירת מחדל	תיאור
`limit`	number	`50`	רשומות לעמוד (ערך לא מספרי חוזר לברירת המחדל)
`offset`	number	`0`	היסט עימוד

דוגמת בקשה

curl -X GET "https://api-eu1.joryio.com/subscriptions/contacts/665f1c2ab3d4e5f6a7b8c9d0/history?limit=50&offset=0" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "items": [
    {
      "id": "8a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "organizationId": "org-uuid",
      "workspaceId": "ws-uuid",
      "contactId": "665f1c2ab3d4e5f6a7b8c9d0",
      "channel": "email",
      "listId": null,
      "action": "unsubscribe",
      "previousStatus": "subscribed",
      "newStatus": "unsubscribed",
      "source": "preference_center",
      "ipAddress": "203.0.113.7",
      "userAgent": "Mozilla/5.0 ...",
      "consentText": null,
      "metadata": { "reason": "User requested via support ticket" },
      "createdAt": "2026-07-12T10:15:00.000Z"
    }
  ],
  "total": 12
}

action הוא אחד מ־subscribe, unsubscribe, resubscribe, bounce, hard_bounce, soft_bounce, complaint, import, api_update. listId מוגדר עבור שינויים ברמת רשימה ו־null עבור שינויים ברמת ערוץ.

בדיקת סטטוס הרשמה לערוץ

בדיקה בוליאנית קלה - האם מותר לשלוח לאיש הקשר בערוץ הזה מבחינת הסכמה?

Endpoint

GET /subscriptions/contacts/:userId/channels/:channel/status

דוגמת בקשה

curl -X GET https://api-eu1.joryio.com/subscriptions/contacts/665f1c2ab3d4e5f6a7b8c9d0/channels/email/status \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{ "subscribed": true }

subscribed הוא true אלא אם איש הקשר unsubscribed במפורש בערוץ - איש קשר ללא סטטוס רשום נחשב מנוי. מזהה איש קשר לא מוכר מחזיר { "subscribed": false } (לא 404).

בדיקת תקינות אימייל

האם כתובת האימייל של איש הקשר ניתנת למסירה, כלומר לא סומנה כלא תקינה בעקבות החזרה קשה?

Endpoint

GET /subscriptions/contacts/:userId/email-valid

דוגמת בקשה

curl -X GET https://api-eu1.joryio.com/subscriptions/contacts/665f1c2ab3d4e5f6a7b8c9d0/email-valid \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{ "valid": true }

valid הוא false רק כאשר החזרה קשה סימנה את הכתובת כלא תקינה. מזהה איש קשר לא מוכר מחזיר { "valid": false } (ולא 404). שימו לב: הערך משקף יכולת מסירה, לא הסכמה - איש קשר שביטל הרשמה אך כתובתו תקינה עדיין מחזיר true.

רשימות הרשמה

רשימות הן קטגוריות הסכמה או נושאים שאנשי קשר יכולים להירשם אליהם (ניוזלטר, עדכוני מוצר וכדומה). הגדרות הרשימות נמצאות תחת /lists; החברות של כל איש קשר מנוהלת באמצעות נקודות הקצה להסכמת איש קשר שלמעלה או באמצעות נקודות הקצה לפעולות באצווה שבהמשך.

יצירת רשימה

Endpoint

POST /lists

גוף הבקשה

שדה	סוג	חובה	תיאור
`name`	string	כן	שם הרשימה (עד 255 תווים, ייחודי בסביבת העבודה)
`description`	string	לא	תיאור (עד 1000 תווים)
`channels`	string[]	לא	הערוצים שהרשימה חלה עליהם (ברירת מחדל `["email"]`)
`isPublic`	boolean	לא	הצגה במרכז ההעדפות (ברירת מחדל `true`)
`type`	string	לא	`marketing` או `transactional` (ברירת מחדל `marketing`)
`requireDoubleOptIn`	boolean	לא	דרישת opt-in מאושר (ברירת מחדל `false`)

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/lists \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Newsletter",
    "description": "Our weekly digest of product updates",
    "channels": ["email"],
    "isPublic": true,
    "type": "marketing",
    "requireDoubleOptIn": false
  }'

תגובה

{
  "id": "3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b",
  "organizationId": "org-uuid",
  "workspaceId": "ws-uuid",
  "name": "Weekly Newsletter",
  "description": "Our weekly digest of product updates",
  "channels": ["email"],
  "isPublic": true,
  "type": "marketing",
  "requireDoubleOptIn": false,
  "isDefault": false,
  "displayOrder": 0,
  "senderId": null,
  "archivedAt": null,
  "createdAt": "2026-07-12T10:30:00.000Z",
  "updatedAt": "2026-07-12T10:30:00.000Z"
}

isDefault מסמן את קטגוריית ה־Marketing שנוצרת אוטומטית כברירת מחדל; senderId מוגדר כאשר הרשימה היא קבוצת הרשמה לפי מספר ב־SMS או ב־WhatsApp, שמשויכת לשולח מסוים.

הצגת כל הרשימות

Endpoint

GET /lists

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

פרמטר	סוג	ברירת מחדל	תיאור
`includeArchived`	string	`false`	העבירו `true` כדי לכלול רשימות בארכיון

דוגמת בקשה

curl -X GET "https://api-eu1.joryio.com/lists?includeArchived=false" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

מערך של אובייקטי רשימה (באותו מבנה כמו יצירת רשימה), מהחדש לישן, עד 200 רשימות.

קבלת רשימה

GET /lists/:listId

מחזיר את אובייקט הרשימה. 404 Not Found אם הרשימה אינה קיימת או שהיא בארכיון.

עדכון רשימה

PUT /lists/:listId

גוף הבקשה: כל תת־קבוצה של השדות שמתוארים תחת יצירת רשימה (name, description, channels, isPublic, type, requireDoubleOptIn). מחזיר את אובייקט הרשימה המעודכן.

העברת רשימה לארכיון

DELETE /lists/:listId

מחיקה רכה - הפעולה מגדירה את archivedAt ושומרת את רשומות החברות. היא מחזירה 204 No Content. כדי לשחזר, השתמשו ב:

POST /lists/:listId/restore

שמחזיר את אובייקט הרשימה המשוחזר.

קבלת חברי רשימה

Endpoint

GET /lists/:listId/members

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

פרמטר	סוג	ברירת מחדל	תיאור
`channel`	string	-	מסנן אופציונלי: `email`, `sms`, `whatsapp`, `push`, `viber`
`status`	string	-	מסנן אופציונלי: `subscribed` או `unsubscribed`
`limit`	number	`50`	רשומות לעמוד
`offset`	number	`0`	היסט עימוד

דוגמת בקשה

curl -X GET "https://api-eu1.joryio.com/lists/3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b/members?channel=email&status=subscribed&limit=50" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "members": [
    {
      "_id": "665f2e11aa22bb33cc44dd55",
      "contactId": "665f1c2ab3d4e5f6a7b8c9d0",
      "listId": "3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b",
      "channel": "email",
      "status": "subscribed",
      "subscribedAt": "2026-05-14T09:21:07.000Z",
      "optInSource": "api",
      "organizationId": "org-uuid",
      "workspaceId": "ws-uuid",
      "createdAt": "2026-05-14T09:21:07.000Z",
      "updatedAt": "2026-05-14T09:21:07.000Z"
    }
  ],
  "total": 1234
}

קבלת סטטיסטיקות רשימה

Endpoint

GET /lists/:listId/stats

דוגמת בקשה

curl -X GET https://api-eu1.joryio.com/lists/3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b/stats \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "total": 1500,
  "byChannel": {
    "email": 1180,
    "sms": 120,
    "whatsapp": 0,
    "push": 0,
    "viber": 0
  },
  "subscribed": 1300,
  "unsubscribed": 200
}

byChannel סופר חברויות שאינן מבוטלות לכל ערוץ.

הוספת חברים באצווה

מוסיף עד 10,000 אנשי קשר לרשימה בערוץ אחד בקריאה בודדת.

Endpoint

POST /lists/:listId/members/bulk

גוף הבקשה

שדה	סוג	חובה	תיאור
`contactIds`	string[]	כן	מזהי אנשי קשר ב-Joryio (עד 10,000)
`channel`	string	כן	`email`, `sms`, `whatsapp`, `push` או `viber`
`source`	string	לא	נשמר כ־`optInSource` של החברות

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/lists/3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b/members/bulk \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["665f1c2ab3d4e5f6a7b8c9d0", "665f1c2ab3d4e5f6a7b8c9d1"],
    "channel": "email",
    "source": "import"
  }'

תגובה

{ "added": 2, "updated": 0, "skippedUnsubscribed": 0 }

הוספה באצווה יוצרת חברויות חדשות בלבד. אנשי קשר שכבר נמצאים ברשימה נשארים ללא שינוי, ואנשי קשר שביטלו הרשמה במפורש לעולם אינם מצורפים מחדש בהוספה באצווה - הם נספרים ב־skippedUnsubscribed. צירוף מחדש של איש קשר שביטל את הרשמתו מחייב את הקריאה המפורשת והמתועדת ביומן הביקורת צירוף איש קשר לרשימה. updated הוא תמיד 0 (ונשמר לצורך תאימות לאחור).

הסרת חברים באצווה

מבטל הרשמה של עד 10,000 אנשי קשר מרשימה בערוץ אחד.

Endpoint

DELETE /lists/:listId/members/bulk

גוף הבקשה

שדה	סוג	חובה	תיאור
`contactIds`	string[]	כן	מזהי אנשי קשר ב-Joryio (עד 10,000)
`channel`	string	כן	`email`, `sms`, `whatsapp`, `push` או `viber`

דוגמת בקשה

curl -X DELETE https://api-eu1.joryio.com/lists/3f6c1a2e-9d4b-4f0a-8c7e-1b2d3e4f5a6b/members/bulk \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["665f1c2ab3d4e5f6a7b8c9d0"],
    "channel": "email"
  }'

תגובה

{ "removed": 1 }

ההסרה משנה רשומות חברות קיימות ל־unsubscribed (הרשומות נשמרות לצורך תיעוד הביקורת), ולכן שער השליחה חוסם את אנשי הקשר שהוסרו משליחות עתידיות לרשימה.

עמוד העדפות מתארח

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

קבלת תבנית מרכז ההעדפות

GET /subscriptions/hosted-page/preference-center

תגובה

{
  "type": "preference_center",
  "mode": "default",
  "html": "",
  "redirectUrl": "",
  "designJson": null,
  "updatedAt": null
}

mode הוא אחד מ־default (העמוד המובנה של Joryio), custom (תבנית HTML/Liquid משלכם), dnd (נוצר בעורך החזותי ומפיק את אותו html) או redirect (רישום ה־opt-out ולאחר מכן הפניה אל redirectUrl).

עדכון תבנית מרכז ההעדפות

PUT /subscriptions/hosted-page/preference-center

גוף הבקשה

שדה	סוג	חובה	תיאור
`mode`	string	לא	`default`, `custom`, `dnd` או `redirect`
`html`	string	לא	גוף HTML/Liquid עבור מצב `custom` או `dnd` (עד 100KB); חייב לכלול את המיקום `{{ preferences_form }}`
`redirectUrl`	string	לא	יעד עבור מצב `redirect` (עד 2048 תווים)
`designJson`	object	לא	מצב העורך החזותי שנשמר לצורך עריכה חוזרת (`dnd` בלבד; מנוקה במצבים אחרים)

מחזיר את התבנית שנשמרה באותו מבנה כמו תגובת ה־GET.

תצוגה מקדימה של תבנית

POST /subscriptions/hosted-page/preview

גוף הבקשה: { "html": "..." } - התבנית להצגה עם נתוני דוגמה. תגובה: { "html": "<rendered, sanitized html>" }.

ממשקים קשורים (שאינם בעמוד זה)

נקודות קצה לנמענים - ביטול הרשמה בלחיצה אחת (POST /u/:token) ועמודי ההעדפות המתארחים הם נקודות קצה ציבוריות שמאומתות באמצעות טוקן עבור הנמענים, ולא באמצעות מפתח API.
Web SDK - POST /v1/subscriptions/channel ו־POST /v1/subscriptions/group מאומתות באמצעות מפתח SDK (X-SDK-Key) עבור ממשקי העדפות בצד הלקוח. ראו מדריך ניהול ההרשמות.
Webhooks של ספקים - Webhooks על החזרות ועל מילות מפתח נכנסות ב־SMS (/webhooks/email/..., /webhooks/sms/...) הם אינטגרציות עם ספקים שמאומתות באמצעות חתימה.
חסימות - לרשימת ה"לא לשלוח" ברמת סביבת העבודה יש Suppressions API משלה.

הצעדים הבאים

Users API - יצירת איש הקשר לפני הגדרת ההסכמה
Suppressions API - רשימת ה"לא לשלוח" לפי מזהה
מדריך ניהול ההרשמות - מושגים, שימוש ב-SDK, מילות מפתח, ציות

אימות​

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

מושגי יסוד​

מזהה איש הקשר​

רישום כבר בזמן היצירה​

ערוצים​

ערכי סטטוס​

שינויי הסכמה נרשמים ומשוכפלים​

הסכמה של איש קשר​

קבלת ההרשמות של איש קשר​

Endpoint​

פרמטרים בנתיב​

דוגמת בקשה​

תגובה​

עדכון הרשמה לערוץ​

Endpoint​

פרמטרים בנתיב​

גוף הבקשה​

דוגמת בקשה​

תגובה​

הערות התנהגות​

ניקוי מצב ההחזרה​

Endpoint​

גוף הבקשה​

דוגמת בקשה​

תגובה​

קבלת הרשמות לרשימות​

Endpoint​

דוגמת בקשה​

תגובה​

צירוף איש קשר לרשימה​

Endpoint​

פרמטרים בנתיב​

גוף הבקשה​

דוגמת בקשה​

תגובה​

ביטול הרשמת איש קשר מרשימה​

Endpoint​

גוף הבקשה​

דוגמת בקשה​

תגובה​

קבלת היסטוריית הרשמות​

Endpoint​

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

דוגמת בקשה​

תגובה​

בדיקת סטטוס הרשמה לערוץ​

Endpoint​

דוגמת בקשה​

תגובה​

בדיקת תקינות אימייל​

Endpoint​

דוגמת בקשה​

תגובה​

רשימות הרשמה​

יצירת רשימה​

Endpoint​

גוף הבקשה​

דוגמת בקשה​

תגובה​

הצגת כל הרשימות​

Endpoint​

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

דוגמת בקשה​

תגובה​

קבלת רשימה​

עדכון רשימה​

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

קבלת חברי רשימה​

Endpoint​

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

דוגמת בקשה​

תגובה​

קבלת סטטיסטיקות רשימה​

Endpoint​

דוגמת בקשה​

תגובה​

הוספת חברים באצווה​

Endpoint​

גוף הבקשה​

אימות

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

מושגי יסוד

מזהה איש הקשר

רישום כבר בזמן היצירה

ערוצים

ערכי סטטוס

שינויי הסכמה נרשמים ומשוכפלים

הסכמה של איש קשר

קבלת ההרשמות של איש קשר

Endpoint

פרמטרים בנתיב

דוגמת בקשה

תגובה

עדכון הרשמה לערוץ

Endpoint

פרמטרים בנתיב

גוף הבקשה

דוגמת בקשה

תגובה

הערות התנהגות

ניקוי מצב ההחזרה

Endpoint

גוף הבקשה

דוגמת בקשה

תגובה

קבלת הרשמות לרשימות

Endpoint

דוגמת בקשה

תגובה

צירוף איש קשר לרשימה

Endpoint

פרמטרים בנתיב

גוף הבקשה

דוגמת בקשה

תגובה

ביטול הרשמת איש קשר מרשימה

Endpoint

גוף הבקשה

דוגמת בקשה

תגובה

קבלת היסטוריית הרשמות

Endpoint

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

דוגמת בקשה

תגובה

בדיקת סטטוס הרשמה לערוץ

Endpoint

דוגמת בקשה

תגובה

בדיקת תקינות אימייל

Endpoint

דוגמת בקשה

תגובה

רשימות הרשמה

יצירת רשימה

Endpoint

גוף הבקשה

דוגמת בקשה

תגובה

הצגת כל הרשימות

Endpoint

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

דוגמת בקשה

תגובה

קבלת רשימה

עדכון רשימה

העברת רשימה לארכיון

קבלת חברי רשימה

Endpoint

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

דוגמת בקשה

תגובה

קבלת סטטיסטיקות רשימה

Endpoint

דוגמת בקשה

תגובה

הוספת חברים באצווה

Endpoint

גוף הבקשה