Send your app's own email
A transactional email is one your app owes one person: a receipt, a sign-in link, a password reset. It leaves from a mailbox kept for it, or from a sender address that sends through Amazon SES, exactly as you wrote it. Start by reading what your app already sent. This sends nothing.
import { Colding } from "colding";
const colding = new Colding("cd_your_key");
const page = await colding.sends.list({ kind: "transactional" });
for (const send of page.items) console.log(send.to, send.status);Replace the key with yours. kind: "transactional" leaves out every other kind of email. The list is empty until your app sends its first one.
[email protected] sent
What you need first
Use a key from the first guide. Each permission covers one kind of action, and one does not include another.
- The
transactionalpermission on the key. A key with onlysendcannot send these emails, and a key with onlytransactionalcannot send campaigns. To follow an email afterwards, the key also needsread. - Where it leaves from: a mailbox kept for your app's email, with
purpose: "transactional"(the next section sets one), or a sender address (the Sender addresses section). - A plan with transactional email. The free plan has none, and the call answers 402
PLAN_GATE. - The workspace owner must have accepted the acceptable use policy. Until then, sending answers 403
AUP_REQUIRED. - A confirmed address to send from. A working login proves the password, not that the address is yours, so the owner, or a key with
setup, confirms a mailbox's address with the code we email to it. Until then, the call answers 409. A sender address needs no confirming: the records of its domain prove it.
Read how mailboxes are connected
A paid plan lets one mailbox send 200 to 1,000 of these emails a day, by plan. The count starts again at midnight in the workspace's time zone.
Keep a mailbox for it
Every mailbox has one purpose at a time: cold for campaigns and messages, or transactional for your app's email. A transactional mailbox does not send campaigns, and the other kind does not send your app's email. Send the wrong kind from a mailbox and the call answers 409.
Set the purpose with mailboxes.update. The key needs operate and transactional, and the plan must include transactional email:
const mailbox = await colding.mailboxes.update({
mailboxId,
purpose: "transactional",
});
console.log(mailbox.purpose);It prints transactional. Going back to cold is the same call, and also needs transactional. A transactional mailbox still receives mail, and you can still reply from it.
A mailbox that campaigns send from, or that has emails scheduled, cannot become transactional. The call answers 409, and details.campaigns lists those campaigns by ID and name. Take the mailbox out of them, let its scheduled emails go or cancel them, then call again.
A send-only mailbox has no inbox. It is a sending service's SMTP login, and it is always transactional. A key with setup connects it with mailboxes.connectSendOnly. Without setup, only a signed-in owner connects it, and an agent asks for it with a handoff.
Read how a send-only mailbox is connected
Keep your app's email on its own subdomain, such as mail.example.com, apart from the domain your campaigns use. A campaign's bounces and spam complaints are then less likely to reach your receipts. The console suggests this when both kinds share a domain. It is advice, not a rule.
Sender addresses
Sender addresses are not on any plan for sale yet. Until our team opens sending through Amazon SES for your workspace, creating one answers 402 PLAN_GATE with the messageKey serverErrors.hostedTransactionalClosed. We open it for one business at a time: write to [email protected].
A sender address is the From address of your app's email, like [email protected]. It has no password and no login, and it sits on a mail domain of yours that is set up for transactional email. It does not receive mail.
A key can't make one. An owner makes it in the console, under Domains, once the domain is Active. An agent asks an owner with a manage_sender_addresses handoff. Behind the console are three operations only an owner can call: create_sender_address, update_sender_address and delete_sender_address. A key gets 403 on them.
Every sender address has a replyTo, the address where replies go. We never receive mail for the domain, so a reply to the sender address itself would go nowhere. Name an address someone reads, like your support desk. It can't be the sender address.
A key reads sender addresses with senderAddresses.list and senderAddresses.get. Replace the key with yours.
const page = await colding.senderAddresses.list();
for (const sender of page.items) console.log(sender.id, sender.address, sender.replyTo);Each one has id, address, domainId, displayName, replyTo, createdAt and createdBy. The id is the mailboxId that a send names. Narrow the list with domainId. The list is paged: pass nextCursor back as cursor. A deleted sender address is not listed, and getting it answers 404.
To get one made, create a handoff, give the owner its link, then read the result. When the owner has made the address, the handoff is completed and resultMailboxId is the new sender address's ID.
const request = await colding.handoffs.create({
kind: "manage_sender_addresses",
note: "Add [email protected]. Replies go to [email protected].",
});
console.log(request.url);
// Later, after the owner has opened the link:
const done = await colding.handoffs.get({ handoffId: request.id });
if (done.resultMailboxId) {
const sender = await colding.senderAddresses.get({ senderAddressId: done.resultMailboxId });
console.log(sender.address, sender.replyTo);
}An address your app already sends from, as a connected mailbox or a send-only mailbox, can't also be a sender address. To move it, disconnect the mailbox first. That deletes the messages stored here for it (mail at your provider stays), and the sender address gets a new ID that your app must send with. Until you change the ID in your app's config, a send that names the old one answers 404.
To send from a sender address, pass its id as mailboxId.
Send one email
transactional.send sends one email to one person, from one mailbox or sender address:
const send = await colding.transactional.send({
mailboxId: "66666666-6666-4666-8666-666666666666",
to: "[email protected]",
subject: "Your sign-in link",
bodyText: "Open this link to sign in: https://app.example.com/in/abc123",
intentKey: "sign-in-link-user-42-2030-01-15",
expiresAt: "2030-01-15T10:15:00Z",
});
console.log(send.id, send.status);The call returns the email with status reserved, shown as About to go out in the console. It counts toward today's sends but hasn't gone out yet. The worker, our background sender, sends it next.
Send bodyHtml, bodyText or both. The email goes out exactly as you wrote it: no signature, no unsubscribe line, no open or click tracking, no wait between emails and no undo window. toName sets the name on the To line, and replyTo says where replies go.
fromName puts another name on the From line of this one email, such as Acme Support. The address stays the mailbox's or sender address's own. Use up to 64 characters on one line, without @, or >, so the name can't look like an address. Left out, the email uses the name the mailbox or sender address already has.
unsubscribeUrl is your app's own unsubscribe link for this person, such as https://app.example/unsubscribe?t=abc. It goes out as the List-Unsubscribe header, with List-Unsubscribe-Post: List-Unsubscribe=One-Click, so mail apps like Gmail can show an unsubscribe button. When the person presses it, the mail app sends a POST to your link, which must unsubscribe them with no other step. Use an https:// link of up to 995 ASCII characters, without spaces, commas, or >. Your app records the unsubscribe and keeps its own preferences: we add nothing to our suppression list. Left out, the email has no unsubscribe headers. Not every mail app shows the button, so keep a link in the email too.
Set expiresAt for a code or a link that stops working, as a date and time with its offset. If the email has not started going out by then, it is canceled with errorCode expired and never sent. A time that has already passed answers 400.
You can cancel an email that has not started going out with sends.cancel. It needs the transactional permission. Once an email has started going out, it can't be canceled, and the call answers 409.
Send a calendar invite or a PDF
An email can carry a calendar invite (an .ics file) or a PDF, such as a booking or a receipt. Put each file in attachments, with its filename, its contentType and its bytes in base64 as content:
const invite = [
"BEGIN:VCALENDAR",
"VERSION:2.0",
"PRODID:-//Acme//Bookings//EN",
"METHOD:REQUEST",
"BEGIN:VEVENT",
"UID:[email protected]",
"DTSTAMP:20300115T090000Z",
"DTSTART:20300120T130000Z",
"DTEND:20300120T140000Z",
"SUMMARY:Haircut with José at Acme",
"ORGANIZER:mailto:[email protected]",
"ATTENDEE;RSVP=TRUE:mailto:[email protected]",
"END:VEVENT",
"END:VCALENDAR",
"",
].join("\r\n");
// The file's UTF-8 bytes in base64. In Node, Buffer.from(invite).toString("base64") is the same.
const bytes = new TextEncoder().encode(invite);
const content = btoa(Array.from(bytes, (byte) => String.fromCharCode(byte)).join(""));
const send = await colding.transactional.send({
mailboxId: "77777777-7777-4777-8777-777777777777",
to: "[email protected]",
subject: "Your booking on January 20",
bodyText: "See you on January 20 at 1 pm. The invite adds it to your calendar.",
intentKey: "booking-1042-confirmation",
attachments: [{ filename: "invite.ics", contentType: "text/calendar", content }],
});
console.log(send.files);An email carries up to 3 files (10 with fileIds). A PDF is up to 1 MB, a calendar file up to 256 KB, and the email with its files up to 2 MB. We read each file's bytes, not only its name: a PDF starts with %PDF-, and a calendar file is UTF-8 text with no NUL byte from BEGIN:VCALENDAR to END:VCALENDAR. The name ends in .ics or .pdf to match. Any other file, such as an image or a zip, is refused with 400 and the reason, so send a link to it instead.
A calendar file may say METHOD:REQUEST, METHOD:CANCEL or METHOD:PUBLISH, or name no method. With one of the three it goes as an invitation, so Gmail and Outlook show their button to add it to the calendar. We read the method from the file, so write the line there. Any other method, such as REPLY, is refused.
From a sender address, we check the links in a calendar file the way we check the links in the body. We never read inside a PDF, so its links are not checked.
Each file becomes a stored file: files.list shows it, it counts toward your workspace's file room, and it is deleted 7 days after the email goes. The files are part of the request, so the same intentKey with other files is refused (422).
It works from a sender address and from a mailbox you connected. Stored files in fileIds go only from a mailbox you connected.
Send through SMTP
SMTP is how an app hands email to a sending service. When our team enables it for your workspace, use it for receipts, sign-in links and other email people asked for. To ask for access, write to [email protected].
Your SMTP password is an API key with only the Send app email permission. An owner makes it in Agents › API keys. Keep only that permission, choose the sender addresses the app may use and set its daily limit. The key is shown once. A key that can also read mail or send campaigns is refused.
Server: smtp.colding.app. Username: colding. Port 465 uses TLS, an encrypted connection from the first byte. Port 587 uses STARTTLS, which turns encryption on before login. The password is the key you just made.
Send one email to one recipient. A second recipient is refused. It can carry a calendar invite (.ics) or a PDF, by the same rules as the API. Any other file, an inline image included, is refused: link to it instead. The whole email must fit within 2 MiB, and each text or HTML part still meets the API limit. The From header and MAIL FROM must be the same live sender address your key may use. Its name comes from the sender address, not the message.
We carry the recipient, its name when the To address matches it, the From name, Reply-To, Subject, your text and HTML parts, and your calendar files and PDFs. A From name the API would refuse is left out, and the email goes under the sender address's own name. We carry your own unsubscribe link too: the first https:// link in List-Unsubscribe, only when you also send List-Unsubscribe-Post: List-Unsubscribe=One-Click and the link follows the rule above. Otherwise both headers are left out and the email still goes. An invitation's two copies, the calendar part and the attached .ics, go as one file. Cc, Bcc and all other headers are dropped. There is no expiresAt over SMTP. A successful answer means the email was accepted for sending, not delivered.
Supabase Auth (GoTrue)
Use these settings without changing GoTrue. Replace SMTP_LOGIN with your key and the example sender with a sender address you added. Keep the key out of source control.
GOTRUE_SMTP_HOST=smtp.colding.app
GOTRUE_SMTP_PORT=465
GOTRUE_SMTP_USER=colding
GOTRUE_SMTP_PASS=<SMTP_LOGIN>
[email protected]SMTP cannot promise exactly one email. Resending the same built message keeps the same intent. Rebuilding it with a new Date can send another copy. Set an X-Intent-Key header to name one email, or use the API's intentKey when you need a retry to return the same send.
A temporary refusal can pass later. Wait until the reset time if one is given, then retry the same message. A permanent refusal needs a change: read the answer and fix the key, sender address, payment or email before trying again.
After 5 failed logins from your IP network in a minute, or 10 in an hour, the next login closes the connection until that window resets. The answer says when. Fix the app's key before reconnecting. An API outage does not count as a wrong login.
Name each email
intentKey is required. It is your own name for one email, up to 255 characters, such as receipt-order-1042. Use something your app already has, like the order number.
Send the identical request again and you get the same email back. Nothing more is sent. This holds for good, not only for 24 hours.
const request = {
mailboxId: "66666666-6666-4666-8666-666666666666",
to: "[email protected]",
subject: "Receipt for order 1042",
bodyText: "Thanks for your order. The receipt is in your account.",
intentKey: "receipt-order-1042",
};
const first = await colding.transactional.send(request);
const again = await colding.transactional.send(request);
console.log(first.id === again.id);true
The request is the mailbox, the address, the name, fromName, unsubscribeUrl, the subject, both bodies, expiresAt and replyTo. Build it once and send that same copy on every retry. Save the intentKey before you send, so a crash does not lose it.
The same intentKey with a different request is refused with 422 IDEMPOTENCY_KEY_REUSED, and nothing is sent. To send a second email on purpose, such as a receipt again, use a new intentKey.
A retry is answered before the plan, the payment and expiresAt are checked. So a retry that comes late still gets its email back, even if the payment has failed since.
Names that start with draft:, warmup: or campaign: are ours, and are refused.
Through Amazon SES
Pass a sender address's id as mailboxId. The call keeps the same intentKey, body and expiresAt. Amazon SES delivers the email and signs it with your domain's key. Your app needs no mailbox of its own.
const send = await colding.transactional.send({
mailboxId: "77777777-7777-4777-8777-777777777777",
to: "[email protected]",
subject: "Your sign-in link",
bodyText: "Open this link to sign in: https://app.example.com/in/abc123",
intentKey: "sign-in-link-user-42-2030-01-16",
});
console.log(send.status, send.viaOurServers);reserved true
The answer has status reserved. viaOurServers stays true for sender addresses that use Amazon SES. It is false for mailboxes you connected, unless their mail server is one of ours.
Here sent means Amazon SES accepted the email, not that it reached an inbox. SES replaces the delivered Message-ID and Date. The ledger keeps our messageId and puts SES's id in providerMessageId. A later bounce does not undo the acceptance.
expiresAt only stops an email before sending starts. It cannot recall email Amazon SES already accepted. If the answer is lost after sending starts, the status is unknown. It counts as sent and is never resent.
When a sender address cannot send
A sender address can be refused for more reasons than a mailbox can. None of these reserves anything, so the identical request can go again. resetAt says when.
402 hostedTransactionalClosed- Your workspace is not open for email through Amazon SES yet. Our team opens it for one business at a time: write to [email protected].
429 hostedTransactionalDay- Your workspace sent all the emails it may send through Amazon SES today. The number is your workspace's own. Wait for
resetAt, midnight in the workspace's time zone. 429 domainRamp- A domain that is new to Amazon SES starts with a small number of emails a day and can send a little more each day it sends.
details.limitis today's number. It starts over atresetAt, midnight UTC. 429 ipCeiling429 ipShare- This is our shared Amazon SES sending room, not your plan's limit. It counts email sent in the last day, even across midnight. Other workspaces keep room for their own email. Try again after
resetAt. 409 sesIdentityNotReady409 sesTenantNotReady409 sesTenantPaused409 sesAccountPaused503 sesAccountUnavailable- Amazon SES has not verified your domain or finished setting up your workspace, or it paused our account or your workspace. The error's
messageKeysays which. Check the domain's DNS records for verification; contact support for a pause. 409 mailDomainNotSigning- Your domain's DNS records failed our check, so we can't sign its email. Nothing is sent from it until the records pass again. Fix them in the console, under Domains.
409 senderDomainUnderReview- Our team put the sender address's domain on hold because too much of its email bounced or was marked as spam. There is no
resetAt: nothing sends from the domain until our team turns it back on.details.caseNumberis the number to quote. Further down this page, you can read when we hold a domain and how the hold ends.
Your workspace's daily number starts again at midnight in its time zone. Your domain's daily limit starts again at midnight UTC. SES's shared room covers a rolling day; resetAt says when to try again.
With domainRamp, ipCeiling or ipShare, an app that already has another confirmed address connected for transactional email can send the same content from it now, with its own intentKey. The recipient sees that other address as the From. Otherwise, send the identical request again after resetAt. With hostedTransactionalDay, wait for resetAt: that number is your workspace's own.
Set up a second way to send before you need it
- Before you need it, connect another address for transactional email: a mailbox kept for it, or your sending service's login. Confirm its sender address. It can't be the sender address you use through Amazon SES.
- Keep its
mailboxIdin your app's config as the second sender. - Use it only after a 429 that reserved nothing, whose
details.scopeisdomainRamp,ipCeilingoripShare. Send the same content through thatmailboxIdwith its ownintentKey. The same key with a different email is refused. If this send is accepted, do not also retry the first one. Never send a second copy of an email that is alreadysentorunknown. - The recipient sees the second address as the From, not your sender address through Amazon SES.
hostedTransactionalDayis your workspace's own number for the day. Wait forresetAton that one.
Follow it until it ends
sends.get answers for one email. sends.list answers for many, newest first, and kind: "transactional" keeps only these. Both need read. A status only moves forward. These emails cannot be scheduled, so scheduled never shows:
reserved- About to go out. It already counts toward today's sends and is waiting its turn.
sending- Going out now.
sent- The mail server it left through accepted it: your provider's, for a mailbox you connected, or ours, for a sender address. That does not mean it reached an inbox.
failed- It did not go out.
errorCodesays why. unknown- The connection broke while it was going out, so we cannot tell if the server took it. It counts as sent and is never sent again.
cancelled- It stopped before it left: a person or a key canceled it, or a check refused it when it was due.
errorCodesays why.
To hear how each email ended without asking, read the events. Every send ends in send.sent, send.failed, send.unknown, send.cancelled or send.bounced, campaign emails too, so the example checks kind:
const page = await colding.events.list({
types: ["send.sent", "send.failed", "send.unknown", "send.cancelled", "send.bounced"],
});
for (const event of page.items) {
if ("kind" in event.data && event.data.kind === "transactional")
console.log(event.type, event.subjectId);
}subjectId is the email's ID. These emails have no send.opened or send.clicked, because they carry no tracking.
sent means the mail server it left through accepted the email: your provider's, from a mailbox you connected, or ours, from a sender address. Neither says it reached an inbox. A bounce can arrive later. Then send.bounced fires, and bouncedAt says when. From a sender address, deliveredAt says when the recipient's server accepted it, and deferredAt when it first asked to try again later. Each stays null until a notice arrives.
Replies land in the inbox, or at replyTo when you set one. A send-only mailbox has no inbox, and neither has a sender address: replies go to replyTo, or else to the reply-to address the sender address was made with.
When it is refused or stopped
A refused call sends nothing. These are the answers a send can get:
400 VALIDATION_ERROR- The request is wrong: no body, a bad address, a
fromNameorunsubscribeUrlthat breaks its rule, or anexpiresAtthat has already passed. 402 PLAN_GATE- The plan has no transactional email. A plan change lifts it, and
details.upgradeTonames a plan that has it. From a sender address, it can also mean our team has not opened Amazon SES for the workspace yet. 402 PAYMENT_REQUIRED- The last payment failed. Paying lifts it.
403 FORBIDDEN- The key lacks
transactional, or an owner limited it: to some mailboxes, to one kind of email, or to a total of emails.details.scopesays which. 403 AUP_REQUIRED- The owner has not accepted the acceptable use policy yet.
404 NOT_FOUND- No such mailbox or sender address in this workspace. One of another workspace answers the same.
409 CONFLICT- Something about the mailbox, the address or the workspace blocks this send. The message says what: the mailbox is not transactional, its address is not confirmed, the recipient stopped your app's email or, from a sender address, one of Amazon SES is not ready or our team put its domain on hold.
422 IDEMPOTENCY_KEY_REUSED- This
intentKeyalready names a different email. 429 QUOTA_EXCEEDED- The mailbox sent all its app emails for today, or the key reached its daily limit. From a sender address, it can also be the room through Amazon SES: Through Amazon SES lists each one.
details.scopesays which, andresetAtsays when sending can start again. 429 RATE_LIMIT_EXCEEDED- The API received too many requests in a short time. Wait for the time in the response, then send the identical request again.
The first guide lists every error code and what to do about it.
Stopped before it left
A call can succeed and the email still not go out. Just before it delivers, the worker looks once more. If something changed, it cancels the email with an errorCode and sends nothing:
expiredexpiresAtpassed before the email started going out.recipient_suppressed- The address went on the suppression list for app email after you made the call.
authority_revoked- The key or the person that sent it can no longer send app email.
key_stream_scopekey_mailbox_scope- An owner limited the key after you made the call, so it can no longer send this kind of email, or send from this mailbox.
payment_failed- A payment failed after you made the call.
workspace_posture- We limited the workspace before the email left, or the account that sent it can no longer send.
workspace_closing- The owner asked to delete the workspace.
sender_unconfirmed- The mailbox's address was not confirmed as the workspace's.
mailbox_disconnected- The mailbox was disconnected, or the sender address deleted, after you made the call.
mail_ip_held- The server of ours the email was to leave from was put on hold after you made the call.
domain_not_signing- The sender address's domain failed our check after you made the call, so we can't sign its email.
mailbox_paused- The mailbox was paused, or our team put the sender address's domain on hold, after you made the call.
failed is different: the email was tried, and the server or the mailbox refused it. errorCode says why. To send it again, use a new intentKey, because the old one still names the failed email.
relay_refused means our Amazon SES setup or account refused the email. Nothing was sent, no attempt was spent and nobody was suppressed. Contact support. After the cause is fixed, start a new send with a new intentKey.
When we hold a mail domain
We watch the app email that leaves through Amazon SES, one mail domain at a time. If too much of it bounces or gets marked as spam, we put the domain on hold. Every sender address on it stops sending until our team turns it back on. Other mail domains, and the mailboxes you connected, keep sending.
We count the last 7 days. A bounce counts when the person's mail server refused the address. A bounce that gives no reason counts for nothing, and so does a delay on our side. An email that a person marks as spam counts once.
We hold a domain when 0.5% of its emails were marked as spam, or 10% bounced. With fewer than 50 emails in those days, no rate counts. A spam hold also needs at least 3 different people who marked an email, so one person can't hold your domain alone. A bounce hold also needs at least 10 bounces that went to 3 or more different recipient domains (the part after the @), so one company's mail server can't hold your domain alone. These are today's numbers, and they may change.
A receiving server can also refuse your email as unwanted. We hold the domain for that only when other senders through Amazon SES don't get the same refusal from that server.
While the hold lasts, a send from any sender address on the domain answers 409 with senderDomainUnderReview. details.caseNumber is our case number. details.ground says which rule held the domain: complaint_rate, bounce_rate, policy_bounce_rate or policy_abuse_burst. An email that was already waiting to go is canceled with mailbox_paused. You can't add a sender address on the domain either.
Only our team turns sending back on, and the count starts over when it does. Write to [email protected] and quote the case number.
The workspace gets one mail_domain_problem alert when the hold starts (under_review) and one when it ends (review_ended), and each sender address fires mailbox.review_changed. The console's page for the domain shows the last 7 days and the hold.
We also read your app email as its own group when we judge the whole workspace. The rates are the same, but they only count from 200 emails in those days. Spam marks still need 3 different people, and bounces still need 3 or more recipient domains. If your email passes them, or a domain is held on several different days, we can limit the workspace. posture.reasonCode then says transactional_bounce_rate, transactional_complaint_rate or sending_pauses.
Who stops getting it
Your app's email has its own suppression list. An address can stop campaigns and messages (cold in the API), your app's email (transactional), or both. What stops what depends on what came back, and about which email:
- The address bounced, about any email
- Both
- A person marked a campaign or message email as spam
- Campaigns and messages only
- A person marked your app's email as spam
- Both
- A person replied asking to stop, to a campaign or message email
- Campaigns and messages only
- A person replied asking to stop, to your app's email
- Both
An unsubscribe from your campaigns never stops your app's email.
No address check comes first, because the person asked for this email. Only the suppression list is read, twice: when you make the call, and again just before the email goes out.
See what has stopped your app's email:
const page = await colding.suppressions.list({ stream: "transactional" });
for (const row of page.items) console.log(row.value, row.source, row.twinSource);source says why each row is there. twinSource says why the same address is on the other list, or is null when it is not.
suppressions.add adds an address with stream: "transactional", and needs operate. Taking one off is for a signed-in owner or admin in the console. No key can.
suppression.added fires for each new row, with its stream and source.
Reports from a sending service
A send-only mailbox has no inbox, so a bounce cannot come back as mail. The sending service tells us another way: a report sent to an address of ours, the mailbox's report hook. We read Mailgun, Postmark, Resend, SendGrid and Amazon SES. A report counts only when the service proves it is theirs and it names an email this mailbox sent.
The owner turns the hook on in the console and copies its address into the service. A key cannot, because the hook holds or shows a secret. A key reads the rest:
const hook = await colding.mailboxes.reportHook({ mailboxId });
console.log(hook.service, hook.on, hook.lastReportAt);
const reports = await colding.mailboxes.reports({ mailboxId });
for (const report of reports) console.log(report.kind, report.outcome);reportHook says whether we read this service (supported) and whether the hook is on. It also gives the time of the last report (lastReportAt) and how many came in the last 30 days, by outcome (counts). It never shows the secret.
Amazon SES has no secret. The owner gives us the SNS topic. The hook says when AWS's subscription was confirmed, and the last message we refused, with the reason (refusal).
reports lists what came in, newest first: 20 by default, up to 100. Each says whether it was a bounce or a complaint and what became of it. It has no address and none of the service's words. Reports are kept 30 days.
The outcome says what we did:
suppressed- The report said the address is gone, or a person complained. That email's recipient is on the suppression list.
stamped- A permanent failure that does not say the address is gone, such as a refusal about the message or about us. The email is marked bounced, and nobody goes on the list.
no_send- No email of this mailbox matches the report. Nothing changed.
other_recipient- It names someone the email did not go to. Nothing changed.
not_final- A delay, or a failure the service will retry. Nothing changed.
Only the recipient of the email the report is about goes on the list. An address named inside a report never does.
The code that reads each service's reports was written from its documentation and has not yet run against a live account. Check the first report with reports before you rely on it.
Three guards against sending twice
A timeout does not tell you whether an email went out. Three separate guards stop a second one. They work at different points, and none of them replaces another.
A saved answer: the HTTP request key
Every write the SDK makes carries an Idempotency-Key. For 24 hours, the same workspace, operation, key and input get the saved answer back instead of a second run. If saving the answer fails, or the first try got no answer for 15 minutes, the call can run again. This guard alone cannot promise one email.
The send intent: one name for one email
This is why intentKey is required here: it is the guard that holds for good. The same key with the same request always returns the same email, long after the saved answer is gone.
The worker's claim
Before it delivers, the worker claims the email's row once, so two workers cannot both send it. If the connection breaks at the end of sending, the email is marked unknown, counts as sent and is never sent again.
None of these proves delivery. sent means the sending service accepted the email: your connected mailbox's provider, or Amazon SES for a sender address.