Docs
⌘K
Email ›

List email messages

GET/v1/sandboxes/{id}/email/messages

The sandbox's messages, newest first, a page at a time. It is how a receiver that missed an event catches up: every message that was taken is here, whether or not a webhook was told. A message is kept for 7 days.

RequestTypeScript
  1. import { Agental } from "agental-sdk";
  3. const agental = new Agental();
  4. const sandbox = await agental.sandboxes.get("sbx_2a9a47e50daec64a");
  5. const page = await sandbox.email.list();
Answer200 OK · EmailMessageList
  1. {
  2. "messages": [{
  3. "id": string,
  4. "sandboxId": string,
  5. "direction": "received" | "sent",
  6. "from": string | null,
  7. "to": string,
  8. "subject": string | null,
  9. … 8 more
  10. }],
  11. "nextCursor": string | null,
  12. }

A page of messages.

Path

idrequired
string
 e.g. "sbx_0123456789abcdef"

Query

cursor
string
The nextCursor of the page before. Left out, the newest messages are given.
limit
integer
How many to give. 50 unless it is said.

Headers

Authorizationrequired
Bearer key
An API key that may make this call.

Returns

200 A page of messages.

EmailMessageList2 fields
messages
EmailMessageSummary[]14 fields
id
string
sandboxId
string
direction
receivedsent
from
stringnull
Who the message says it is from: its From header, or where that could not be read, the address the sending server gave.
More Null for a bounce that names nobody.
to
string
The address the message was delivered to.
More This is what it was routed by, and it can differ from the To header a person would see.
subject
stringnull
sizeBytes
integer
The size of the message as it was transmitted, attachments and all.
attachments
object[]3 fields
What is attached, by name and size.
More Their contents are in the raw message. None of it is scanned for anything.
filename
stringnull
contentType
string
sizeBytes
integer
checks
object3 fields
What the mail server made of who sent the message: pass, fail, or none where the sender's domain says nothing.
More Null where it was not checked. A message that passes all three still says nothing of whether its sender means well.
spf
stringnull
dkim
stringnull
dmarc
stringnull
spamScore
numbernull
How much the message looks like spam, where higher is worse.
More Null where it was not scored. Nothing is done about it here: whoever reads the mail decides.
sentByProgram
boolean
True for a bounce, a mailing list's post or an automatic reply: mail no person wrote to this address.
More Answering such mail is how two programs come to write to each other for ever.
createdAt
string
state
acceptedhanded_overdeliveredbouncedexpireduncertainnullnull
Where a sent message has got to.
More accepted: the API took it and charged for it. handed_over: the mail server has it. delivered: the recipient's server took it, which says nothing of inbox or spam folder. bounced: the recipient's server refused it. expired: it could not be delivered within a day. uncertain: whether the mail server took it is not known, and it is not sent again by itself. Null for a message that was received.
stateDetail
stringnull
What a server said, where the message was refused or given up.
More Null otherwise.
nextCursor
stringnull
What to send as cursor for the messages after these.
More Null when these are the last.

Errors and other answers

400invalid_request cursor is not one this sandbox's list gave.
404 Not found.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Disable sandbox emailSend email message →