Αναφορά API

Το REST API του AgentSend. Όλα τα requests και responses χρησιμοποιούν JSON. Base URL: https://api.agentsend.io.

Επισκόπηση

Το API του AgentSend είναι ένα REST API που δίνει στους πράκτορές σας προγραμματιστική πρόσβαση σε εισερχόμενα, μηνύματα, νήματα, webhooks, τομείς, συνημμένα και ρυθμίσεις λογαριασμού. Κάθε σώμα request και response είναι JSON.

Όλα τα endpoints API είναι διαθέσιμα κάτω από το base URL:

base url

https://api.agentsend.io

ⓘ

Για τοπική ανάπτυξη, το API είναι διαθέσιμο στο http://localhost:3000 όταν τρέχει ο διακομιστής τοπικά.

Αυθεντικοποίηση

Το API του AgentSend υποστηρίζει δύο μεθόδους αυθεντικοποίησης. Χρειάζεστε μόνο μία ανά request.

Bearer Token

Περάστε το κλειδί API σας ως Bearer token στην κεφαλίδα Authorization. Αυτή είναι η προτιμώμενη μέθοδος για server-side requests.

curl

curl https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>"

Κεφαλίδα API Key

Εναλλακτικά, περάστε το κλειδί API σας απευθείας στην κεφαλίδα x-api-key.

curl

curl https://api.agentsend.io/inboxes \
  -H "x-api-key: <your-api-key>"

⚠

Κρατήστε το κλειδί API σας μυστικό. Ποτέ μην το εκθέσετε σε client-side code ή μην το κάνετε commit σε version control. Χρησιμοποιήστε μεταβλητές περιβάλλοντος για να το περάσετε στην εφαρμογή σας.

Μορφή Request

Στείλτε σώματα request ως JSON και συμπεριλάβετε κεφαλίδα Content-Type: application/json σε όλα τα requests που έχουν σώμα.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Agent"}'

Σελιδοποίηση

Τα endpoints που επιστρέφουν λίστες υποστηρίζουν τις παραμέτρους query limit και offset για σελιδοποίηση. Το προεπιλεγμένο limit είναι 20.

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`limit`	integer	`20`	Μέγιστος αριθμός στοιχείων προς επιστροφή. Μέγιστο 100.
`offset`	integer	`0`	Αριθμός στοιχείων προς παράλειψη πριν την επιστροφή αποτελεσμάτων.

Όλες οι απαντήσεις λίστας περιλαμβάνουν πίνακα data και αρίθμηση total όλων των αντίστοιχων εγγραφών:

json — paginated response

{
  "data": [ /* array of objects */ ],
  "total": 142
}

Για να ανακτήσετε την επόμενη σελίδα, αυξήστε το offset κατά την τιμή του limit. Για παράδειγμα, για να λάβετε τη σελίδα 3 με μέγεθος σελίδας 20: ?limit=20&offset=40.

Χειρισμός Σφαλμάτων

Τα σφάλματα επιστρέφουν σώμα JSON με ένα αντικείμενο error που περιέχει έναν machine-readable code, ένα human-readable message και το HTTP status.

json — error response

{
  "error": {
    "code": "INBOX_NOT_FOUND",
    "message": "No inbox found with that ID.",
    "status": 404
  }
}

Κοινά HTTP status codes που επιστρέφει το API:

Status	Σημασία
`400`	Bad Request — λείπουν απαιτούμενα πεδία ή περιέχονται μη έγκυρες τιμές στο σώμα request.
`401`	Unauthorized — δεν δόθηκε κλειδί API ή το κλειδί δεν είναι έγκυρο.
`403`	Forbidden — το κλειδί API δεν έχει δικαίωμα να εκτελέσει αυτή την ενέργεια.
`404`	Not Found — ο αιτούμενος πόρος δεν υπάρχει.
`409`	Conflict — ο πόρος υπάρχει ήδη ή το request συγκρούεται με την τρέχουσα κατάσταση.
`429`	Too Many Requests — έχετε ξεπεράσει το rate limit σας. Καθυστερήστε και δοκιμάστε ξανά.
`500`	Internal Server Error — κάτι πήγε στραβά από την πλευρά του AgentSend.

Rate Limiting

Όλα τα endpoints API έχουν rate limit για την προστασία της σταθερότητας της πλατφόρμας. Όταν ξεπεράσετε το όριο, το API επιστρέφει απάντηση 429 Too Many Requests.

Κάθε απάντηση API περιλαμβάνει κεφαλίδες rate limit ώστε να μπορείτε να παρακολουθείτε τη χρήση σας:

Κεφαλίδα	Περιγραφή
`X-RateLimit-Limit`	Μέγιστος αριθμός requests που επιτρέπονται στο τρέχον παράθυρο.
`X-RateLimit-Remaining`	Αριθμός requests που απομένουν στο τρέχον παράθυρο.
`X-RateLimit-Reset`	Unix timestamp όταν μηδενίζει το παράθυρο rate limit.

💡

Χρησιμοποιήστε exponential backoff κατά την επαναπροσπάθεια μετά από απάντηση 429. Περιμένετε τον χρόνο που υποδεικνύεται από το X-RateLimit-Reset πριν στείλετε επιπλέον requests.

Idempotency

Τα POST requests μπορούν να περιλαμβάνουν κεφαλίδα Idempotency-Key για ασφαλή επαναπροσπάθεια requests χωρίς δημιουργία διπλότυπων πόρων. Αν ληφθεί request με το ίδιο κλειδί idempotency εντός του παραθύρου idempotency, επιστρέφεται η αρχική απάντηση αντί να δημιουργηθεί νέος πόρος.

curl

curl -X POST https://api.agentsend.io/inboxes \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-request-id-abc123" \
  -d '{"displayName": "Support Agent"}'

Ενότητες API

Περιηγηθείτε στην πλήρη αναφορά για κάθε πόρο:

📩

Εισερχόμενα

Δημιουργήστε, ενημερώστε και διαγράψτε εισερχόμενα πρακτόρων. Δείτε όλα τα εισερχόμενα στον λογαριασμό σας.

✉

Μηνύματα

Στείλτε εξερχόμενα email και δείτε ληφθέντα μηνύματα για ένα εισερχόμενο.

💬

Νήματα

Δείτε και διαχειριστείτε νήματα συνομιλίας ομαδοποιημένα κατά θέμα και συμμετέχοντες.

🔌

Webhooks

Εγγράψτε endpoints για να λαμβάνετε ειδοποιήσεις events σε πραγματικό χρόνο.

🌐

Τομείς

Προσθέστε προσαρμοσμένους τομείς αποστολής και διαχειριστείτε την επαλήθευση DNS.

⚙

Λογαριασμός

Ανακτήστε λεπτομέρειες λογαριασμού, διαχειριστείτε κλειδιά API και δείτε τη χρήση.

📎

Συνημμένα

Ανεβάστε αρχεία και επισυνάψτε τα σε εξερχόμενα μηνύματα.

← Προηγούμενο Ενσωματώσεις Επόμενο → API: Εισερχόμενα