Receive email in your app
Receive inbound email at a coss.com address or your own domain, handle the email.received webhook in Next.js, read attachments and reply.
Every coss.com environment can receive email. Each message is stored as a received email and
announced by an email.received webhook; your handler fetches it and can reply.
Get an inbound email address
Each environment has its own domain under coss.com's inbound domain, such as
k3j9x2m7qp4l.inbound.coss.com. Mail to any address at it (support@…, orders+42@…) is
received, with no DNS setup. Use the part before the @ to route messages in your app.
const { : } = await ...();
.(`Send a test email to hello@${?.}`);Receive email at your own domain with an MX record
To receive at inbound.acme.com, set up receiving on one of your domains
and publish the MX record it lists:
const { : } = await ...(, {
: "inbound.acme.com",
});
const = ?.?.;
.(?., ?., ?.);- Use a subdomain. Pointing
acme.comitself at coss.com moves all of its mail here, your team's mailboxes included. - The environment of the API key that sets it up receives the mail. Mail to an address nobody receives at is dropped without a bounce.
Handle the email.received webhook in Next.js
Subscribe a webhook endpoint to email.received. The event says who sent what
to whom, never the content, so fetch the email for its bodies:
import { , , } from "coss";
const = new ();
export async function (: ) {
try {
const = await (await .(), ., ..!);
if (. !== "email.received" || ..) return new ("ok");
const { : , } = await ...(..);
if () return new ("try again", { : 500 }); // coss.com retries the event
await ({
: . ?? .,
: . ?? "(no subject)",
: . ?? "",
});
return new ("ok");
} catch () {
if ( instanceof ) {
return new ("invalid signature", { : 400 });
}
throw ;
}
}recipientsare the envelope addresses your environment received the message for, Bcc'd ones included: use them to tellsupport@fromorders@.htmlcomes from whoever sent the email. Sanitize it before you show it to anyone.- Webhooks can arrive twice: skip an
event.idyou already handled.
Download attachments
The email lists its attachments' metadata; download each one's bytes:
for (const of .) {
const { : } = await ...(., .);
.(., ., ?.);
}Attachments are served as application/octet-stream, whatever they claim to be. Long bodies and
headers are cut (truncated: true); getRaw() returns the whole message as received.
Reply to a received email
Send a normal email with In-Reply-To and References set, so mail clients show the reply in the
same thread. With a live key, from must be on one of your verified domains.
if (.) {
await ..({
: "Acme Support <support@acme.com>",
: .. > 0 ? . : (. ?? .),
: `Re: ${. ?? ""}`,
: "Thanks, we're on it.",
: {
"In-Reply-To": .,
: [...., .].(" "),
},
});
}Spam, viruses and limits
Every message is scanned on arrival. verdicts holds the spam and virus scans and the SPF, DKIM
and DMARC checks (pass, fail, gray or processing_failed).
- Spam (
spam: true) and mail that fails authentication is still received: decide in your handler. - A message with a virus is
blocked: its content is never stored and no webhook is sent. - Organizations have daily limits on received messages and data, and a maximum message size. Mail over a limit is dropped and counted in the dashboard.
- Received emails are kept for 30 days.
Test receiving in a sandbox
In a sandbox environment, Send a test email on the Received emails page receives a message
without sending one. Put [coss-test:spam], [coss-test:virus], [coss-test:spf-fail],
[coss-test:dkim-fail] or [coss-test:dmarc-fail] in its subject to try each verdict. Real mail to
your inbound address works too.
Forward events to your local server with coss listen, and follow what arrives with coss inbox:
coss listen --forward-to localhost:3000/webhooks/coss
coss inbox # prints the inbound domain, then each email as it arrivesBuilding an AI agent that answers email? Inboxes give each agent its own address, keep received mail as threads and reply from the same address.
Next steps
- Receiving email: every field, verdict and limit.
- Verify webhook signatures in Node.js.
- Give an AI agent its own email address.
Last updated