Μηνύματα

Στείλτε εξερχόμενα email, δείτε μηνύματα σε εισερχόμενα, ανακτήστε μεμονωμένο μήνυμα και διαγράψτε μηνύματα.

ⓘ

Όλα τα requests απαιτούν την κεφαλίδα x-api-key. Το base URL για κάθε endpoint είναι https://api.agentsend.io.

Το Αντικείμενο Μηνύματος

Κάθε endpoint που επιστρέφει μήνυμα επιστρέφει αυτή τη δομή.

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": [],
  "subject": "Hello from AgentSend",
  "bodyText": "This email was sent by an AI agent.",
  "bodyHtml": "<p>This email was sent by an AI agent.</p>",
  "delivery": "email",
  "status": "delivered",
  "attachments": [],
  "messageIdHeader": "<msg_01hx9k2v...@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

Πεδίο	Τύπος	Περιγραφή
`id`	string (uuid)	Μοναδικό αναγνωριστικό μηνύματος.
`inboxId`	string (uuid)	Τα εισερχόμενα στα οποία ανήκει αυτό το μήνυμα.
`threadId`	string (uuid)	Το νήμα στο οποίο ανήκει αυτό το μήνυμα.
`direction`	enum	`outbound` για απεσταλμένα μηνύματα, `inbound` για ληφθέντα μηνύματα.
`fromAddress`	string	Η διεύθυνση email αποστολέα.
`toAddresses`	string[]	Διευθύνσεις email κύριων παραληπτών.
`ccAddresses`	string[]	Διευθύνσεις email παραληπτών CC.
`subject`	string	Γραμμή θέματος email.
`bodyText`	string \| null	Σώμα απλού κειμένου.
`bodyHtml`	string \| null	Σώμα HTML.
`delivery`	enum	`email` όταν το AgentSend παρέδωσε το μήνυμα στο SES, `dry-run` όταν αυτό το περιβάλλον προσομοίωσε την παράδοση χωρίς πραγματική αποστολή mail.
`status`	enum	Τρέχουσα κατάσταση παράδοσης. Μία από τις: `queued`, `sending`, `sent`, `delivered`, `failed`, `bounced`, `complained`, `received`.
`attachments`	AttachmentMeta[]	Πίνακας αντικειμένων metadata συνημμένων (id, filename, contentType, size).
`messageIdHeader`	string	Η τιμή κεφαλίδας `Message-ID` κατά RFC 5322.
`createdAt`	string (ISO 8601)	Πότε δημιουργήθηκε το μήνυμα.

Αποστολή Μηνύματος

POST /inboxes/{inboxId}/messages

Στείλτε ένα εξερχόμενο email από ένα inbox. Το μήνυμα μπαίνει σε ουρά άμεσα και επιστρέφει 202 Accepted μαζί με το νέο αντικείμενο Message. Ελέγξτε το delivery για να δείτε αν το περιβάλλον έστειλε πραγματικό mail (email) ή μόνο το προσομοίωσε (dry-run). Ενημερώσεις κατάστασης παράδοσης είναι διαθέσιμες μέσω webhooks ή με polling του GET /messages/{id}.

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

Παράμετρος	Τύπος	Περιγραφή
`inboxId` απαιτείται	string (uuid)	Το ID του inbox από το οποίο θα σταλεί.

Σώμα Request

Παράμετρος	Τύπος	Περιγραφή
`to` απαιτείται	string[]	Μία ή περισσότερες διευθύνσεις email παραληπτών.
`subject` απαιτείται	string	Γραμμή θέματος email. Μέγιστο 998 χαρακτήρες.
`cc`	string[]	Διευθύνσεις email παραληπτών CC.
`bcc`	string[]	Διευθύνσεις email παραληπτών BCC. Οι διευθύνσεις BCC δεν είναι ορατές σε άλλους παραλήπτες.
`bodyText`	string	Σώμα απλού κειμένου. Πρέπει να παρέχεται τουλάχιστον ένα από τα `bodyText` ή `bodyHtml`.
`bodyHtml`	string	Σώμα HTML. Το AgentSend δημιουργεί αυτόματα εναλλακτικό κείμενο αν παρέχεται μόνο HTML.
`threadId`	string (uuid)	Επισυνάψτε αυτό το μήνυμα σε υπάρχον νήμα. Αν παραλειφθεί, δημιουργείται νέο νήμα.
`attachmentIds`	string[] (uuid)	IDs προ-ανεβασμένων συνημμένων προς ενσωμάτωση. Ανεβάστε αρχεία πρώτα μέσω του API Συνημμένων.

Παράδειγμα Request

javascript

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.AGENTSEND_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: ["customer@example.com"],
      cc: ["manager@example.com"],
      subject: "Your order is confirmed",
      bodyText: "Hi, your order #1234 has been confirmed.",
      bodyHtml: "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
      attachmentIds: ["att_01hx9k2v3w4x5y6z7a8b9c0d"],
    }),
  }
);

const message = await res.json();
console.log(message.id, message.status); // "msg_...", "queued"

Απάντηση — 202 Accepted

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": ["manager@example.com"],
  "subject": "Your order is confirmed",
  "bodyText": "Hi, your order #1234 has been confirmed.",
  "bodyHtml": "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
  "delivery": "email",
  "status": "queued",
  "attachments": [
    {
      "id": "att_01hx9k2v3w4x5y6z7a8b9c0d",
      "filename": "invoice.pdf",
      "contentType": "application/pdf",
      "size": 204800
    }
  ],
  "messageIdHeader": "<msg_01hx9k2v3w4x5y6z7a8b9c0d@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

Λίστα Μηνυμάτων

GET /inboxes/{inboxId}/messages

Επιστρέφει λίστα με σελιδοποίηση των μηνυμάτων ενός inbox, ταξινομημένα κατά createdAt φθίνουσα. Χρησιμοποιήστε το φίλτρο status για ανάκτηση μόνο μηνυμάτων σε συγκεκριμένη κατάσταση παράδοσης — για παράδειγμα, status=received για ανάκτηση εισερχόμενων μηνυμάτων που πρέπει να επεξεργαστεί ο πράκτοράς σας.

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

Παράμετρος	Τύπος	Περιγραφή
`inboxId` απαιτείται	string (uuid)	Το inbox από το οποίο θα δείτε λίστα μηνυμάτων.

Παράμετροι Query

Παράμετρος	Τύπος	Περιγραφή
`limit`	integer	Αριθμός μηνυμάτων προς επιστροφή. Προεπιλογή `20`. Μέγιστο `100`.
`offset`	integer	Αριθμός μηνυμάτων προς παράλειψη για σελιδοποίηση. Προεπιλογή `0`.
`status`	enum	Φιλτράρισμα ανά κατάσταση παράδοσης. Μία από τις: `queued`, `sending`, `sent`, `delivered`, `failed`, `bounced`, `complained`, `received`.

Παράδειγμα Request

javascript

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages?status=received&limit=50`,
  {
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

const { data, total } = await res.json();

for (const msg of data) {
  console.log(msg.fromAddress, msg.subject);
}

Απάντηση — 200 OK

json

{
  "data": [
    {
      "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
      "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
      "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
      "direction": "inbound",
      "fromAddress": "customer@example.com",
      "toAddresses": ["agent@yourdomain.com"],
      "ccAddresses": [],
      "subject": "Re: Your order is confirmed",
      "bodyText": "Thanks! Can I change the delivery address?",
      "bodyHtml": null,
      "status": "received",
      "attachments": [],
      "messageIdHeader": "<abc123@mail.example.com>",
      "createdAt": "2026-04-16T10:45:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Λήψη Μηνύματος

GET /messages/{id}

Ανακτήστε μεμονωμένο μήνυμα με το ID του. Χρησιμοποιήστε αυτό για polling ενημερώσεων κατάστασης παράδοσης μετά την αποστολή.

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

Παράμετρος	Τύπος	Περιγραφή
`id` απαιτείται	string (uuid)	Το ID του μηνύματος προς ανάκτηση.

Παράδειγμα Request

javascript

const res = await fetch(
  `https://api.agentsend.io/messages/${messageId}`,
  {
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

const message = await res.json();
console.log(message.status); // "delivered"

Απάντηση — 200 OK

Επιστρέφει μεμονωμένο αντικείμενο Message.

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": [],
  "subject": "Your order is confirmed",
  "bodyText": "Hi, your order #1234 has been confirmed.",
  "bodyHtml": "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
  "delivery": "email",
  "status": "delivered",
  "attachments": [],
  "messageIdHeader": "<msg_01hx9k2v3w4x5y6z7a8b9c0d@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

Διαγραφή Μηνύματος

DELETE /messages/{id}

Διαγράφει μόνιμα ένα μήνυμα. Αυτή η ενέργεια δεν μπορεί να αναιρεθεί. Η διαγραφή μηνύματος δεν το ανακαλεί — αν το email έχει ήδη αποσταλεί σε παραλήπτες δεν μπορεί να ανακληθεί.

⚠

Η διαγραφή μηνύματος που είναι το μόνο μήνυμα σε ένα νήμα θα διαγράψει και αυτό το νήμα.

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

Παράμετρος	Τύπος	Περιγραφή
`id` απαιτείται	string (uuid)	Το ID του μηνύματος προς διαγραφή.

Παράδειγμα Request

javascript

await fetch(
  `https://api.agentsend.io/messages/${messageId}`,
  {
    method: "DELETE",
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
); // 204 No Content

Απάντηση — 204 No Content

Επιστρέφει κενό σώμα σε επιτυχία.

Καταστάσεις Παράδοσης

Το πεδίο status εξελίσσεται μέσα από τις εξής καταστάσεις για εξερχόμενα μηνύματα. Τα εισερχόμενα μηνύματα φτάνουν με status: "received".

Status	Περιγραφή
`queued`	Το μήνυμα έγινε αποδεκτό και περιμένει να αποσταλεί.
`sending`	Μεταδίδεται αυτή τη στιγμή στον διακομιστή mail του παραλήπτη.
`sent`	Έγινε αποδεκτό από τον διακομιστή mail του παραλήπτη.
`delivered`	Επιβεβαιωμένη παράδοση στο mailbox του παραλήπτη (όπου υποστηρίζεται).
`failed`	Μόνιμη αποτυχία παράδοσης. Ελέγξτε τα events webhook για λεπτομέρειες.
`bounced`	Hard bounce — η διεύθυνση δεν υπάρχει ή ο διακομιστής απέρριψε την παράδοση.
`complained`	Ο παραλήπτης επισήμανε το μήνυμα ως spam.
`received`	Εισερχόμενο μήνυμα που ελήφθη στο inbox.

💡

Εγγραφείτε σε webhooks για να λαμβάνετε μεταβάσεις κατάστασης σε πραγματικό χρόνο αντί να κάνετε polling στο endpoint GET.

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