Skip to content
Cloudflare Docs

Runtime API

Background

An EmailEvent is the event type to programmatically process your emails with a Worker. You can reject, forward, or drop emails according to the logic you construct in your Worker.

Syntax: ES modules

EmailEvent can be handled in Workers functions written using the ES modules format by adding an email function to your module's exported handlers:

export default {
  async email(message, env, ctx) {
    await message.forward("<YOUR_EMAIL>");
  },
};

Parameters

  • message ForwardableEmailMessage

  • env object

    • An object containing the bindings associated with your Worker using ES modules format, such as KV namespaces and Durable Objects.

  • ctx object

    • An object containing the context associated with your Worker using ES modules format. Currently, this object just contains the waitUntil function.

Syntax: Service Worker

EmailEvent can be handled in Workers functions written using the Service Worker syntax by attaching to the email event with addEventListener:

addEventListener("email", async (event) => {
  await event.message.forward("<YOUR_EMAIL>");
});

Properties

ForwardableEmailMessage definition

 interface ForwardableEmailMessage<Body = unknown> {
  readonly from: string;
  readonly to: string;
  readonly headers: Headers;
  readonly raw: ReadableStream;
  readonly rawSize: number;


  public constructor(from: string, to: string, raw: ReadableStream | string);


  setReject(reason: string): void;
  forward(rcptTo: string, headers?: Headers): Promise<void>;
  reply(message: EmailMessage): Promise<void>;
}

An email message that is sent to a consumer Worker and can be rejected/forwarded.

  • from string

    • Envelope From attribute of the email message.

  • to string

    • Envelope To attribute of the email message.

  • headers Headers

  • raw ReadableStream

    • Stream of the email message content.

  • rawSize number

    • Size of the email message content.

  • setReject(reasonstring) : void

    • Reject this email message by returning a permanent SMTP error back to the connecting client, including the given reason.

  • forward(rcptTostring, headersHeadersoptional) : Promise

    • Forward this email message to a verified destination address of the account. If you want, you can add extra headers to the email message. Only X-* headers are allowed.
    • When the promise resolves, the message is confirmed to be forwarded to a verified destination address.

  • reply(EmailMessage) : Promise

    • Reply to the sender of this email message with a new EmailMessage object.
    • When the promise resolves, the message is confirmed to be replied.

EmailMessage definition

interface EmailMessage {
    readonly from: string;
    readonly to: string;
}

An email message that can be sent from a Worker.

  • from string

    • Envelope From attribute of the email message.

  • to string

    • Envelope To attribute of the email message.