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.com itself 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:

app/webhooks/coss/route.ts
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 ;
  }
}
  • recipients are the envelope addresses your environment received the message for, Bcc'd ones included: use them to tell support@ from orders@.
  • html comes from whoever sent the email. Sanitize it before you show it to anyone.
  • Webhooks can arrive twice: skip an event.id you 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 arrives

Building 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

Last updated