Delivery status

Email statusCopy Anchor Link

status on the email says whether it was handed to the delivery provider:

Recipient statusCopy Anchor Link

Delivery happens per recipient. recipients lists every distinct address across to, cc and bcc, each with its own status. A status only moves forward:

queued → sent → delivery_delayed → delivered, then bounced / suppressed / failed, then complained.

suppressed means the recipient was skipped because it is on the environment's suppression list, or the provider reported it as suppressed. An email whose recipients are all suppressed fails with all_recipients_suppressed.

COSS automatically screens a sample of live emails for spam, phishing and other abuse right before sending them. An email it is confident about fails with content_rejected and live sending is suspended until COSS support reviews the account. Sandbox emails are never screened. COSS also emails your organization's owners and admins when it warns about your sending reputation or suspends live sending.

EventsCopy Anchor Link

Each change is recorded as an event. List them with coss.email.listEvents (see GET /v1/emails/{id}/events), or receive them as webhooks.

const { data: events } = await coss.email.listEvents("email_01k7c8m4q2f3e9v6t5r1n0p8yz");

for (const event of events?.data ?? []) {
  if (event.type === "email.bounced") {
    console.log(event.recipient, event.data.bounce?.type);
                                             
Copy Text
EmailEventData.bounce?: {
    type: "permanent" | "transient" | "undetermined";
    sub_type: string;
    diagnostic_code: string | null;
} | undefined
  }
}

email.sent, email.failed, email.scheduled, email.rescheduled and email.canceled describe the whole email (recipient is null). Delivery events describe individual recipients. Open and click events name a recipient only when the email had exactly one non-suppressed recipient.