Email ›

Send email message

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

Sends one message from the sandbox to the address of its own account, which is the only address a sandbox may write to. Mail has to be on for the sandbox. The message is charged when it is taken here, whatever becomes of it, and its state says where it has got to: GET the message to follow it, or wait for email.delivered or email.bounced. It does not depend on the sandbox running. Sent again with the same Idempotency-Key, it is the same message and nothing more is sent.

RequestTypeScript

import { Agental } from "agental-sdk";
const agental = new Agental();
const sandbox = await agental.sandboxes.get("sbx_2a9a47e50daec64a");
const sent = await sandbox.email.send({
subject: "Nightly report",
text: "All tests passed.",
});

Answer200 OK · EmailMessageSummary

{
"id": string,
"sandboxId": string,
"direction": "received" | "sent",
"from": string | null,
"to": string,
"subject": string | null,
"sizeBytes": integer,
"attachments": [{
"filename": string | null,
"contentType": string,
"sizeBytes": integer,
}],
"checks": {
"spf": string | null,
"dkim": string | null,
"dmarc": string | null,
},
… 5 more
}

This request was made before.

Path

idrequired

string

e.g. "sbx_0123456789abcdef"

Headers

`Authorization`required Bearer key	An API key that may make this call.
`Idempotency-Key` string	A name for this request, 8 to 200 visible characters. A repeat under the same name sends nothing and answers with the message the first one made.

Body

`to` string	Who the message is for. It can only be the address of the sandbox's own account, which is who it is for when this is left out. Any other address is refused and nothing is sent.
`from` string	What stands before the @ of the address the message is from. The rest is the sandbox's mail domain. sandbox unless it is said. e.g. `"reports"`
`fromName` string	The name shown beside that address. e.g. `"Nightly report"`
`subject`required string
`text`required string	The message, as plain text.
`replyTo` string	The id of a message this sandbox received, which this one answers. It is threaded under it. It gives no leave to write to whoever sent that message. e.g. `"eml_9c41d0a7b2e65f38"`
`attachments` array of object

Returns

200 This request was made before. This is the message it made then.

EmailMessageSummary14 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.

Null for a bounce that names nobody.

to

string

The address the message was delivered to.

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.

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.

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.

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.

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.

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.

Null otherwise.

Errors and other answers

202	The message was taken and is on its way.
400	invalid_request.
403	`recipient_not_allowed` the message is for an address other than the account's own, or that address was never proved to be its owner's, or the sandbox belongs to no account.
403	`mail_suspended` mail has been switched off for the account by whoever runs the service.
404	Not found.
409	`mail_off` mail is off for the sandbox.
409	`recipient_refuses_mail` the address refused a message for good, and nothing is sent to it for a day.
413	message_too_large.
429	`mail_limit_reached` the account has sent what it may in an hour or a day, or its stored mail is full.
501	mail_not_configured, or
501	`mail_sending_not_configured` this deployment takes mail and sends none. GET /v1/policy says so as email.

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

← List email messages Get email message →