Suppressions API

Το Suppressions API διαχειρίζεται τις ανά χώρο εργασίας λίστες διευθύνσεων email και αριθμών τηλεφώνου στις οποίες το Joryio δεν θα στείλει. Μια καταστολή είναι απόλυτη πύλη: όσο ένα αναγνωριστικό είναι κατεσταλμένο σε ένα κανάλι, κάθε μήνυμα προς αυτό στο συγκεκριμένο κανάλι παραλείπεται, ανεξάρτητα από το ποια καμπάνια ή ποιο journey προσπαθεί να το προσεγγίσει.

Αυτό το API αντικατοπτρίζει την επιφάνεια Κοινό → Λίστες καταστολής του dashboard. Χρησιμοποιήστε το για να ελέγξετε ποιοι είναι κατεσταλμένοι, να μεταφέρετε μια υπάρχουσα λίστα νεκρών διευθύνσεων από άλλη πλατφόρμα, να τιμήσετε ένα αίτημα συγκατάθεσης από τα δικά σας συστήματα ή να άρετε μια καταστολή αφού επιλυθεί ένα hard bounce.

Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com - δείτε Επισκόπηση API.

Έλεγχος ταυτότητας

Κάθε αίτημα ελέγχεται είτε με κλειδί API που φέρει το σχετικό scope παραδοσιμότητας είτε με συνεδρία dashboard (JWT). Τα δεδομένα καταστολής ισχύουν ανά χώρο εργασίας - ένα κλειδί βλέπει και επεξεργάζεται μόνο τις λίστες του δικού του χώρου εργασίας.

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

Scopes ανά endpoint

Το κανάλι καθορίζει ποιο scope απαιτείται. Τα endpoints email χρειάζονται το scope email_suppression:*· τα endpoints SMS και WhatsApp χρειάζονται το scope sms_suppression:*.

Endpoint	Κανάλι email	Κανάλι 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`	- (μόνο email)
`POST /suppressions/import`	`email_suppression:write`	`sms_suppression:write`
`DELETE /suppressions/{identifier}`	`email_suppression:write`	`sms_suppression:write`

Βασικές έννοιες

Διαβάστε αυτή την ενότητα πριν καλέσετε τα endpoints εγγραφής - το υπόλοιπο 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) σας λέει πόσο να την εμπιστευτείτε και αν προσμετράται στις μετρικές φήμης σας.

Λόγοι συγκατάθεσης και λόγοι παραδοσιμότητας

Οι τέσσερις λόγοι χωρίζονται σε δύο οικογένειες με διαφορετική συμπεριφορά:

Οικογένεια	Λόγοι	Σημασία	Επιβιώνει μιας επανεγγραφής;
Συγκατάθεση	`unsubscribe`, `manual`	Ο παραλήπτης (ή εσείς, εκ μέρους του) ζήτησε να μην ενοχλείται.	Όχι - ένα νέο opt-in την καθαρίζει.
Παραδοσιμότητα	`hard_bounce`, `complaint`	Η διεύθυνση/ο αριθμός είναι νεκρός ή μας επισήμανε ως spam.	Ναι - παραμένει ακόμη κι αν ο παραλήπτης επανεγγραφεί.

Μια καταστολή παραδοσιμότητας είναι τεχνικό γεγονός για τη διεύθυνση, όχι προτίμηση, οπότε η επανεγγραφή του παραλήπτη δεν την αίρει. Αίρεται μόνο με ρητή ενέργεια χειριστή: DELETE /suppressions/{identifier}, «καθαρισμό bounce» στο dashboard, ή αλλαγή της επαφής σε νέα διεύθυνση email.

Δεν μπορείτε να κατασκευάσετε bounce

Οι συνήθεις διαδρομές εγγραφής - POST /suppressions και POST /suppressions/import - περιορίζουν το reason σε manual ή unsubscribe. Είναι φυσικά αδύνατο να δημιουργήσουν γραμμή hard_bounce ή complaint. Ένα bounce είναι κάτι που η πλατφόρμα παρατηρεί, όχι κάτι που ένας πελάτης δηλώνει ελαφρά τη καρδία.

Η μόνη διαδρομή που μπορεί να δηλώσει bounce είναι το POST /suppressions/hard-bounce, και ακόμη και τότε η γραμμή σφραγίζεται με source: "api", ώστε να μη συγχέεται ποτέ με bounce που είδαμε εμείς.

Μόνο τα πραγματικά bounces αγγίζουν τη φήμη σας

Το αναφερόμενο ποσοστό bounce του λογαριασμού σας και οι μετρικές παραδοσιμότητας/φήμης μετρούν μόνο τα bounces με source: "delivery" - αυτά που παρατήρησε η δική μας γραμμή αποστολής στο επίπεδο SMTP. Μια καταστολή δηλωμένη μέσω API (source: "api") ή εισηγμένη (source: "import") αποκλείει την αποστολή προς το αναγνωριστικό, αλλά δεν διογκώνει το αναφερόμενο ποσοστό bounce σας. Έτσι μπορείτε να προστατεύσετε τη φήμη αποστολέα σας προφορτώνοντας γνωστές νεκρές διευθύνσεις, χωρίς να μολύνετε την ίδια τη μετρική που προσπαθείτε να προστατεύσετε.

Η καταστολή ακολουθεί τη διεύθυνση / τον αριθμό

Μια καταστολή έχει κλειδί την κανονικοποιημένη διεύθυνση email ή τον αριθμό τηλεφώνου, ανά χώρο εργασίας - όχι μια εγγραφή επαφής. Μία κατεσταλμένη διεύθυνση καλύπτει επομένως κάθε διπλότυπη επαφή που τη μοιράζεται. Καταστείλετε το jane@example.com μία φορά, και όλες οι επαφές με αυτή τη διεύθυνση αποκλείονται στο email, σε όλο τον χώρο εργασίας.

Αναφορά 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`	Παραδοσιμότητα	Τη δική μας γραμμή αποστολής (feedback loops)

Τιμές `source`

`source`	Σημασία	Προσμετράται στη φήμη;
`delivery`	Παρατηρήθηκε από τη δική μας γραμμή αποστολής/λήψης (πραγματικό bounce ή καταγγελία).	Ναι
`api`	Δηλώθηκε μέσω αυτού του REST API.	Όχι
`import`	Φορτώθηκε μέσω `POST /suppressions/import` (μαζική μετάβαση).	Όχι
`unsubscribe_link` (και άλλες πηγές συγκατάθεσης)	Αλλαγή συγκατάθεσης με πρωτοβουλία του παραλήπτη.	Όχι

Λίστα καταστολών

Επιστρέφει μια σελιδοποιημένη λίστα κατεσταλμένων αναγνωριστικών σε ένα κανάλι.

Endpoint

GET /suppressions

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`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 διεύθυνση email ή ο αριθμός τηλεφώνου.

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`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	Ναι	Διεύθυνση email ή αριθμός τηλεφώνου προς καταστολή.
`reason`	string	Όχι	`manual` (προεπιλογή) ή `unsubscribe`. Περιορίζεται - οποιαδήποτε άλλη τιμή απορρίπτεται.
`scope`	string	Όχι	`global` (προεπιλογή) ή `group`.
`listId`	string	Όχι	Απαιτείται όταν το `scope` είναι `group`: η ομάδα/λίστα στην οποία ισχύει η καταστολή.

Το source μιας γραμμής που δημιουργείται εδώ καταγράφεται πάντα ως api. Αυτό το endpoint δεν μπορεί να δημιουργήσει 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"
}

Δήλωση hard bounce

Καταγράψτε ένα hard bounce για μια διεύθυνση email. Είναι η μόνη διαδρομή του API που μπορεί να δηλώσει καταστολή παραδοσιμότητας, και είναι σκόπιμα ξεχωριστή και περιορισμένη.

Γιατί αυτό το endpoint είναι ξεχωριστό

Ένα bounce είναι φυσιολογικά κάτι που το Joryio παρατηρεί τη στιγμή της αποστολής, όχι κάτι που δηλώνει ο καλών. Το να μένει η δήλωση bounce εκτός των συνηθισμένων διαδρομών προσθήκης/εισαγωγής αποτρέπει την τυχαία ή απρόσεκτη κατασκευή.
Επειδή δηλώνετε εσείς αντί να παρατηρούμε εμείς, η γραμμή σφραγίζεται με source: "api". Αποκλείει την αποστολή ακριβώς όπως ένα πραγματικό bounce, αλλά δεν εκλαμβάνεται ποτέ ως bounce που είδαμε εμείς, και δεν προσμετράται στο αναφερόμενο ποσοστό bounce ή στις μετρικές φήμης αποστολέα.
Είναι μόνο για email. Δεν υπάρχει αντίστοιχο για τηλέφωνα - η μη παράδοση SMS/WhatsApp μοντελοποιείται διαφορετικά.

Endpoint

POST /suppressions/hard-bounce

Σώμα αιτήματος

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`identifier`	string	Ναι	Η διεύθυνση email που έκανε hard bounce.

Το κανάλι είναι σιωπηρά 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". Όπως και το endpoint προσθήκης, η εισαγωγή δεν μπορεί να δημιουργήσει bounce ή καταγγελία.

Παράδειγμα αιτήματος

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"
}

Αφαίρεση καταστολής (άρση)

Αφαιρέστε μια καταστολή, ώστε το Joryio να μπορεί να στείλει ξανά στο αναγνωριστικό.

Endpoint

DELETE /suppressions/{identifier}

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`channel`	string	-	`email`, `sms` ή `whatsapp`. Απαιτείται.

προειδοποίηση

Αυτό αφαιρεί όλες τις γραμμές καταστολής για το αναγνωριστικό στο κανάλι σε αυτόν τον χώρο εργασίας - συμπεριλαμβανομένης μιας γραμμής παραδοσιμότητας hard_bounce ή complaint. Πρόκειται για σκόπιμη άρση από χειριστή/API: η άρση καταστολής μιας διεύθυνσης είναι ακριβώς ο τρόπος με τον οποίο καθαρίζετε ένα επιλυμένο hard bounce. Άρετε μια καταστολή παραδοσιμότητας μόνο όταν γνωρίζετε ότι το υποκείμενο πρόβλημα έχει διορθωθεί, αλλιώς κινδυνεύετε να στείλετε σε νεκρή διεύθυνση και να βλάψετε τη φήμη αποστολέα σας.

Παράδειγμα αιτήματος

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 είναι το πλήθος των γραμμών καταστολής που διαγράφηκαν (ένα μεμονωμένο αναγνωριστικό μπορεί να φέρει ταυτόχρονα μια γραμμή συγκατάθεσης εύρους ομάδας και μια καθολική γραμμή παραδοσιμότητας).

Μετάβαση με υπάρχουσα λίστα καταστολών

Όταν μετακομίζετε στο Joryio από άλλη πλατφόρμα email ή SMS, φέρτε μαζί σας τη λίστα καταστολών σας από την πρώτη μέρα, ώστε η πρώτη σας αποστολή να μην ξαναστείλει σε διευθύνσεις που ήδη γνωρίζετε ότι είναι νεκρές ή απεγγραμμένες.

Εισαγάγετε ολόκληρη τη λίστα μέσω POST /suppressions/import. Οι εγγραφές φτάνουν ως manual (ή unsubscribe αν τις επισημάνετε), με source: "import". Αποκλείουν την αποστολή και προστατεύουν τη φήμη αποστολέα σας στην πρώτη αποστολή - χωρίς να διογκώνουν το αναφερόμενο ποσοστό bounce, επειδή οι εισηγμένες γραμμές δεν προσμετρώνται ποτέ στη φήμη.
Μόνο αν χρειάζεστε συγκεκριμένα αυτές οι διευθύνσεις να αναφέρονται ως bounces - για παράδειγμα, για να διατηρήσετε τα αναλυτικά στοιχεία bounce συνεχή κατά τη μετάβαση - δηλώστε τις μεμονωμένα με POST /suppressions/hard-bounce. Θα σφραγιστούν και πάλι με source: "api", οπότε αποκλείουν την αποστολή και εμφανίζονται ως bounces στη λίστα καταστολών σας, χωρίς να μετρούν ως bounces που παρατηρήσαμε εμείς.

Για τις περισσότερες μεταβάσεις, το βήμα 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 επιβάλλει scopes ακριβείας καναλιού. Ένα κλειδί API που κατέχει μόνο το scope SMS παίρνει 403 όταν αγγίζει καταστολές email (και αντίστροφα):

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

Έλεγχος ταυτότητας​

Scopes ανά endpoint​

Βασικές έννοιες​

reason (γιατί) και source (από πού προήλθε)​

Λόγοι συγκατάθεσης και λόγοι παραδοσιμότητας​

Δεν μπορείτε να κατασκευάσετε bounce​

Μόνο τα πραγματικά bounces αγγίζουν τη φήμη σας​

Η καταστολή ακολουθεί τη διεύθυνση / τον αριθμό​

Αναφορά reason / source​

Τιμές reason​

Τιμές source​

Λίστα καταστολών​

Endpoint​

Παράμετροι query​

Παράδειγμα αιτήματος​

Απόκριση​

Έλεγχος ενός αναγνωριστικού​

Endpoint​

Παράμετροι query​

Παράδειγμα αιτήματος​

Απόκριση - κατεσταλμένο​

Απόκριση - μη κατεσταλμένο​

Προσθήκη καταστολής​

Endpoint​

Σώμα αιτήματος​

Παράδειγμα αιτήματος​

Απόκριση​

Δήλωση hard bounce​

Γιατί αυτό το endpoint είναι ξεχωριστό​

Endpoint​

Σώμα αιτήματος​

Παράδειγμα αιτήματος​

Απόκριση​

Μαζική εισαγωγή​

Endpoint​

Σώμα αιτήματος​

Παράδειγμα αιτήματος​

Απόκριση​

Αφαίρεση καταστολής (άρση)​

Endpoint​

Παράμετροι query​

Παράδειγμα αιτήματος​

Απόκριση​

Μετάβαση με υπάρχουσα λίστα καταστολών​

Αποκρίσεις σφαλμάτων​

Επόμενα βήματα​

Έλεγχος ταυτότητας

Scopes ανά endpoint

Βασικές έννοιες

`reason` (γιατί) και `source` (από πού προήλθε)

Λόγοι συγκατάθεσης και λόγοι παραδοσιμότητας

Δεν μπορείτε να κατασκευάσετε bounce

Μόνο τα πραγματικά bounces αγγίζουν τη φήμη σας

Η καταστολή ακολουθεί τη διεύθυνση / τον αριθμό

Αναφορά reason / source

Τιμές `reason`

Τιμές `source`

Λίστα καταστολών

Endpoint

Παράμετροι query

Παράδειγμα αιτήματος

Απόκριση

Έλεγχος ενός αναγνωριστικού

Endpoint

Παράμετροι query

Παράδειγμα αιτήματος

Απόκριση - κατεσταλμένο

Απόκριση - μη κατεσταλμένο

Προσθήκη καταστολής

Endpoint

Σώμα αιτήματος

Παράδειγμα αιτήματος

Απόκριση

Δήλωση hard bounce

Γιατί αυτό το endpoint είναι ξεχωριστό

Endpoint

Σώμα αιτήματος

Παράδειγμα αιτήματος

Απόκριση

Μαζική εισαγωγή

Endpoint

Σώμα αιτήματος

Παράδειγμα αιτήματος

Απόκριση

Αφαίρεση καταστολής (άρση)

Endpoint

Παράμετροι query

Παράδειγμα αιτήματος

Απόκριση

Μετάβαση με υπάρχουσα λίστα καταστολών

Αποκρίσεις σφαλμάτων

Επόμενα βήματα