1import type * as runtime from "@cloudflare/workers-types";
2import * as Data from "effect/Data";
3import * as Effect from "effect/Effect";
4import * as Binding from "../../Binding.ts";
5import type { RuntimeContext } from "../../RuntimeContext.ts";
6import type { SendEmail } from "./SendEmail.ts";
7
8/**
9 * Bind a {@link SendEmail} `send_email` descriptor to a Worker and obtain the
10 * Effect-native client for sending email.
11 *
12 * `Send` is a single identifier that is simultaneously the binding's Context
13 * tag, its type, and the callable — `yield* Cloudflare.Email.Send(EmailDescriptor)`.
14 *
15 * **Example:** Send to any verified destination
16 * ```typescript
17 * const Email = Cloudflare.Email.SendEmail("Email");
18 *
19 * // in the Worker effect:
20 * const email = yield* Cloudflare.Email.Send(Email);
21 * yield* email.send({
22 * from: "noreply@example.com",
23 * to: "user@example.com",
24 * subject: "Hello",
25 * text: "Hi from Alchemy",
26 * });
27 * ```
28 *
29 * @binding
30 * @product Email
31 * @category Email
32 */
33export interface Send extends Binding.Service<
34 Send,
35 "Cloudflare.Email.SendEmail",
36 (sender: SendEmail) => Effect.Effect<SendClient>
37> {}
38
39export const Send = Binding.Service<Send>("Cloudflare.Email.SendEmail");
40
41/**
42 * Email body shape for the builder-form `send` call. Either `text`, `html`,
43 * or both must be provided.
44 */
45export interface SendEmailMessage {
46 from: string | runtime.EmailAddress;
47 to: string | string[];
48 subject: string;
49 replyTo?: string | runtime.EmailAddress;
50 cc?: string | string[];
51 bcc?: string | string[];
52 headers?: Record<string, string>;
53 text?: string;
54 html?: string;
55 attachments?: runtime.EmailAttachment[];
56}
57
58export class SendEmailError extends Data.TaggedError("SendEmailError")<{
59 message: string;
60 cause?: unknown;
61}> {}
62
63export interface SendClient {
64 /**
65 * The raw runtime `SendEmail` binding. Use this when you need direct
66 * access to the Cloudflare object (e.g. to send a pre-built
67 * `EmailMessage` from `cloudflare:email`).
68 */
69 raw: Effect.Effect<runtime.SendEmail, never, RuntimeContext>;
70 /**
71 * Send an email using the builder form. Equivalent to calling
72 * `env.<name>.send({ from, to, subject, text, html, ... })`.
73 */
74 send(
75 message: SendEmailMessage,
76 ): Effect.Effect<runtime.EmailSendResult, SendEmailError, RuntimeContext>;
77 /**
78 * Send a raw `EmailMessage` (constructed via `cloudflare:email`).
79 */
80 sendRaw(
81 message: runtime.EmailMessage,
82 ): Effect.Effect<runtime.EmailSendResult, SendEmailError, RuntimeContext>;
83}