INTEGRITY Dokumentace

← Cloudflare Email Service / email-service / api / send-emails

Workers API

Workers API poskytuje nativní možnosti odesílání e-mailů přímo z vašich Cloudflare Workers prostřednictvím bindings. Pokud Workers nepoužíváte, můžete e-maily odesílat pomocí REST API místo toho.

E-mailová vazba

Nakonfigurujte send_email binding do konfiguračního souboru Wrangler, čímž povolíte odesílání e-mailů:

{
	"send_email": [{ "name": "EMAIL" }],
}
[[send_email]]
name = "EMAIL"

Můžete omezit, které odesílatele a příjemce může vazba používat. Více informací najdete v Konfigurace send bindings pro dostupné atributy omezení a příklady.

send() metoda

Odešlete jeden e-mail pomocí send() metodu na vašem e-mailovém bindingu.

Rozhraní

interface SendEmail {
	send(message: EmailMessage | EmailMessageBuilder): Promise<EmailSendResult>;
}

interface EmailAddress {
	email: string;
	name?: string;
}

// Structured email builder (recommended)
interface EmailMessageBuilder {
	to: string | EmailAddress | (string | EmailAddress)[]; // Max 50 recipients
	from: string | EmailAddress;
	subject: string;
	html?: string;
	text?: string;
	cc?: string | EmailAddress | (string | EmailAddress)[];
	bcc?: string | EmailAddress | (string | EmailAddress)[];
	replyTo?: string | EmailAddress;
	attachments?: Attachment[];
	// Custom headers. See /email-service/reference/headers/
	headers?: { [key: string]: string };
	// The combined number of addresses in `to`, `cc`, and `bcc` must not
	// exceed 50. See /email-service/platform/limits/ for all limits.
}

interface Attachment {
	content: string | ArrayBuffer | ArrayBufferView; // Base64 string or binary content
	filename: string;
	type: string; // MIME type
	disposition: "attachment" | "inline";
	contentId?: string; // For inline attachments
}

interface EmailSendResult {
	messageId: string; // Unique email ID
}

// Errors are thrown as standard Error objects with a `code` property
// try { await env.EMAIL.send(...) } catch (e) { console.log(e.code, e.message) }

Základní použití

const response = await env.EMAIL.send({
	to: "[email protected]",
	from: "[email protected]",
	subject: "Welcome to our service!",
	html: "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
	text: "Welcome! Thanks for signing up.",
});

Informace o více příjemcích, CC/BCC a pojmenovaných adresách najdete v Zadání příjemců.

Přílohy

Soubory odešlete tak, že obsah zakódovaný v base64 zahrnete do attachments pole. Celková velikost zprávy nesmí překročit 5 MiB (včetně příloh).

const response = await env.EMAIL.send({
	to: "[email protected]",
	from: "[email protected]",
	subject: "Your Invoice",
	html: "<h1>Invoice attached</h1><p>Please find your invoice attached.</p>",
	attachments: [
		{
			content: "JVBERi0xLjQKJeLjz9MKMSAwIG9iag...", // Base64 PDF content
			filename: "invoice-12345.pdf",
			type: "application/pdf",
			disposition: "attachment",
		},
	],
});

Informace o vložených obrázcích a nahrávání souborů najdete v E-mailové přílohy.

Zpracování chyb

Ošetření chyb při odesílání e-mailů:

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		try {
			const response = await env.EMAIL.send({
				to: "[email protected]",
				from: "[email protected]",
				subject: "Test Email",
				text: "This is a test email.",
			});

			return new Response(
				JSON.stringify({
					success: true,
					emailId: response.messageId,
				}),
			);
		} catch (error) {
			// Error has .code and .message properties
			console.error("Email sending failed:", error.code, error.message);

			// Handle specific error types
			switch (error.code) {
				case "E_SENDER_NOT_VERIFIED":
					return new Response(
						JSON.stringify({
							success: false,
							error: "Please verify your sender domain first",
						}),
						{ status: 400 },
					);

				case "E_RATE_LIMIT_EXCEEDED":
					return new Response(
						JSON.stringify({
							success: false,
							error: "Rate limit exceeded. Please try again later",
						}),
						{ status: 429 },
					);

				default:
					return new Response(
						JSON.stringify({
							success: false,
							error: error.message,
						}),
						{ status: 500 },
					);
			}
		}
	},
};

Kódy chyb

Při odesílání e-mailů se mohou vrátit následující chybové kódy:

Kód chyby Popis Časté příčiny
E_VALIDATION_ERROR Chyba ověření v datové části Neplatný formát e-mailu, chybějící povinná pole, poškozená data
E_FIELD_MISSING Chybí povinné pole Chybí to, from, nebo subject pole
E_TOO_MANY_RECIPIENTS Příliš mnoho příjemců v polích to/cc/bcc Součet příjemců přesahuje limit 50
E_TOO_MANY_ATTACHMENTS Příliš mnoho příloh v attachments pole attachments pole překračuje 32 položek
E_SENDER_NOT_VERIFIED Doména odesílatele není ověřena Pokus o odeslání z neověřené domény
E_RECIPIENT_NOT_ALLOWED Příjemce není v seznamu povolených adres Adresa příjemce není v allowed_destination_addresses
E_RECIPIENT_SUPPRESSED Příjemce je na seznamu potlačených adres E-mailová adresa má nedoručené zprávy nebo nahlásila vaše e-maily jako spam
E_SENDER_DOMAIN_NOT_AVAILABLE Doména není dostupná pro odesílání Doména není zaregistrována ve službě Email Service
E_CONTENT_TOO_LARGE Obsah e-mailu překračuje limit velikosti Celková velikost zprávy přesahuje maximum
E_DELIVERY_FAILED E-mail se nepodařilo doručit Selhání doručení přes SMTP, zamítnutí serverem příjemce
E_RATE_LIMIT_EXCEEDED Překročen limit rychlosti Dosažen limit rychlosti odesílání
E_DAILY_LIMIT_EXCEEDED Překročen denní limit Dosažena denní kvóta odesílání
E_INTERNAL_SERVER_ERROR Interní chyba služby Email Service je dočasně nedostupná
E_HEADER_NOT_ALLOWED Hlavička není povolena Hlavičku řídí platforma, nebo není na allowlist
E_HEADER_USE_API_FIELD Musí se použít pole API Hlavička jako From musí být nastaveno prostřednictvím vyhrazeného pole API
E_HEADER_VALUE_INVALID Neplatná hodnota hlavičky Poškozená hodnota, prázdná hodnota nebo nesprávný formát
E_HEADER_VALUE_TOO_LONG Hodnota hlavičky je příliš dlouhá Hodnota přesahuje limit 2,048 bajtů
E_HEADER_NAME_INVALID Neplatný název hlavičky Neplatné znaky nebo překročen limit 100 bajtů
E_HEADERS_TOO_LARGE Obsah hlaviček je příliš velký Celková velikost vlastních hlaviček překračuje limit 16 KB
E_HEADERS_TOO_MANY Příliš mnoho hlaviček Více než 20 vlastních hlaviček na seznamu povolených (jiných než X)

Starší EmailMessage API

EmailMessage API zůstává podporováno kvůli zpětné kompatibilitě. Použijte ho, pokud již máte nezpracovanou RFC 5322 ↗ zprávu MIME k odeslání. U nového kódu dejte přednost strukturovanému send() metoda výše.

import { EmailMessage } from "cloudflare:email";
import { createMimeMessage } from "mimetext";

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const msg = createMimeMessage();
		msg.setSender({ name: "Sender", addr: "[email protected]" });
		msg.setRecipient("[email protected]");
		msg.setSubject("Legacy Email");
		msg.addMessage({
			contentType: "text/html",
			data: "<h1>Hello from legacy API</h1>",
		});

		const message = new EmailMessage(
			"[email protected]",
			"[email protected]",
			msg.asRaw(),
		);

		await env.EMAIL.send(message);
		return new Response("Legacy email sent");
	},
};

Další kroky