@visulima/email 1.0.0-alpha.1 → 1.0.0-alpha.3

package/README.md

@@ -1,15 +1,24 @@
-<div align="center">
-  <h3>visulima email</h3>
-  <p>
-  Email sending package with multiple provider support
-  </p>
-</div>
+<!-- START_PACKAGE_OG_IMAGE_PLACEHOLDER -->
+
+<a href="https://www.anolilab.com/open-source" align="center">
+
+  <img src="__assets__/package-og.svg" alt="email" />
+
+</a>
+
+<h3 align="center">A comprehensive email library with multi-provider support, crypto utilities, and template engines</h3>
+
+<!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
 <br />
 
 <div align="center">
 
-[![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
+[![typescript-image][typescript-badge]][typescript-url]
+[![mit licence][license-badge]][license]
+[![npm downloads][npm-downloads-badge]][npm-downloads]
+[![Chat][chat-badge]][chat]
+[![PRs Welcome][prs-welcome-badge]][prs-welcome]
 
 </div>
 
@@ -44,7 +53,7 @@ pnpm add @visulima/email
 ### Basic Usage
 
 ```typescript
-import { createMail, resendProvider } from "@visulima/email";
+import { createMail, MailMessage, resendProvider } from "@visulima/email";
 
 // Create a provider
 const resend = resendProvider({
@@ -54,18 +63,82 @@ const resend = resendProvider({
 // Create a Mail instance
 const mail = createMail(resend);
 
+// Optional: Set default configuration for all emails
+mail.setFrom({ email: "noreply@example.com", name: "My App" });
+
 // Send an email using the message builder
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>").send();
+const message = new MailMessage()
+    .to("user@example.com")
+    // .from() is optional if set via mail.setFrom()
+    .subject("Hello")
+    .html("<h1>Hello World</h1>");
+
+const result = await mail.send(message);
 
 if (result.success) {
     console.log("Email sent:", result.data?.messageId);
 }
 ```
 
+### Default Configuration
+
+You can configure default values for all emails sent through a Mail instance:
+
+```typescript
+import { createMail, MailMessage, resendProvider } from "@visulima/email";
+
+const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
+
+// Set default from address
+mail.setFrom({ email: "noreply@example.com", name: "My App" });
+
+// Set default reply-to address
+mail.setReplyTo({ email: "support@example.com" });
+
+// Set default headers
+mail.setHeaders({
+    "X-App-Name": "MyApp",
+    "X-Version": "1.0.0",
+});
+
+// Or chain them together
+const mail2 = createMail(resendProvider({ apiKey: "re_xxx" }))
+    .setFrom({ email: "noreply@example.com" })
+    .setReplyTo({ email: "support@example.com" })
+    .setHeaders({ "X-App-Name": "MyApp" });
+
+// Now all emails will use these defaults if not specified in the message
+const message = new MailMessage().to("user@example.com").subject("Hello").html("<h1>Hello World</h1>");
+// No need to set .from() - it will use the default
+
+await mail.send(message);
+```
+
+### Creating Draft Emails
+
+You can create draft emails in EML (RFC 822) format without sending them. The `draft()` method returns the email as an EML string with an `X-Unsent: 1` header automatically added:
+
+```typescript
+import { createMail, MailMessage, resendProvider } from "@visulima/email";
+import { writeFile } from "fs/promises";
+
+const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
+
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");
+
+// Create a draft in EML format
+const eml = await mail.draft(message);
+
+// Save to file
+await writeFile("draft.eml", eml);
+
+// EML files can be opened by email clients
+```
+
 ### Using Different Providers
 
 ```typescript
-import { createMail, smtpProvider, resendProvider } from "@visulima/email";
+import { createMail, MailMessage, smtpProvider, resendProvider } from "@visulima/email";
 
 // SMTP provider
 const smtp = smtpProvider({
@@ -86,30 +159,13 @@ const smtpMail = createMail(smtp);
 const resendMail = createMail(resend);
 
 // Send via specific provider
-await resendMail.message().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>").send();
-```
-
-### Using Mailable Classes
+const message = new MailMessage()
+    .to("user@example.com")
+    .from("sender@example.com")
+    .subject("Hello")
+    .html("<h1>Hello World</h1>");
 
-```typescript
-import { createMail, type Mailable, type EmailOptions } from "@visulima/email";
-import { resendProvider } from "@visulima/email";
-
-class WelcomeEmail implements Mailable {
-    constructor(private user: { name: string; email: string }) {}
-
-    build(): EmailOptions {
-        return {
-            from: { email: "noreply@example.com" },
-            to: { email: this.user.email, name: this.user.name },
-            subject: "Welcome!",
-            html: `<h1>Welcome ${this.user.name}!</h1>`,
-        };
-    }
-}
-
-const mail = createMail(resendProvider({ apiKey: "re_xxx" }));
-const result = await mail.send(new WelcomeEmail({ name: "John", email: "john@example.com" }));
+await resendMail.send(message);
 ```
 
 ### Direct Email Sending
@@ -126,7 +182,7 @@ const emailOptions: EmailOptions = {
     html: "<h1>Hello World</h1>",
 };
 
-const result = await mail.sendEmail(emailOptions);
+const result = await mail.send(emailOptions);
 ```
 
 ### Failover Provider
@@ -134,7 +190,7 @@ const result = await mail.sendEmail(emailOptions);
 The failover provider allows you to configure multiple email providers as backups. If the primary provider fails, it will automatically try the next provider in the list.
 
 ```typescript
-import { createMail, failoverProvider, resendProvider, smtpProvider } from "@visulima/email";
+import { createMail, MailMessage, failoverProvider, resendProvider, smtpProvider } from "@visulima/email";
 
 // Create individual providers
 const resend = resendProvider({ apiKey: "re_xxx" });
@@ -157,7 +213,9 @@ const failover = failoverProvider({
 // Use failover provider
 const mail = createMail(failover);
 
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>").send();
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");
+
+const result = await mail.send(message);
 
 // The failover provider will try Resend first, and if it fails,
 // automatically try SMTP
@@ -188,7 +246,7 @@ const failover = failoverProvider({
 The round-robin provider distributes your email sending workload across multiple providers. Each email is sent using the next available provider in rotation, providing load balancing across your mailers.
 
 ```typescript
-import { createMail, roundRobinProvider, resendProvider, smtpProvider } from "@visulima/email";
+import { createMail, MailMessage, roundRobinProvider, resendProvider, smtpProvider } from "@visulima/email";
 
 // Create individual providers
 const resend = resendProvider({ apiKey: "re_xxx" });
@@ -212,13 +270,16 @@ const roundRobin = roundRobinProvider({
 const mail = createMail(roundRobin);
 
 // Each email will be distributed across providers in rotation
-await mail.message().to("user1@example.com").from("sender@example.com").subject("Email 1").html("<h1>Email 1</h1>").send();
+const message1 = new MailMessage().to("user1@example.com").from("sender@example.com").subject("Email 1").html("<h1>Email 1</h1>");
+await mail.send(message1);
 // Uses resend (or random start)
 
-await mail.message().to("user2@example.com").from("sender@example.com").subject("Email 2").html("<h1>Email 2</h1>").send();
+const message2 = new MailMessage().to("user2@example.com").from("sender@example.com").subject("Email 2").html("<h1>Email 2</h1>");
+await mail.send(message2);
 // Uses smtp (next in rotation)
 
-await mail.message().to("user3@example.com").from("sender@example.com").subject("Email 3").html("<h1>Email 3</h1>").send();
+const message3 = new MailMessage().to("user3@example.com").from("sender@example.com").subject("Email 3").html("<h1>Email 3</h1>");
+await mail.send(message3);
 // Uses resend (back to first)
 ```
 
@@ -262,7 +323,8 @@ const mailgun = mailgunProvider({
 const mail = createMail(mailgun);
 
 // Send email with Mailgun-specific options
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>").send();
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>");
+const result = await mail.send(message);
 
 // Or use Mailgun-specific features
 import type { MailgunEmailOptions } from "@visulima/email/providers/mailgun";
@@ -280,7 +342,7 @@ const mailgunOptions: MailgunEmailOptions = {
     deliveryTime: Math.floor(Date.now() / 1000) + 3600, // Schedule for 1 hour from now
 };
 
-await mail.sendEmail(mailgunOptions);
+await mail.send(mailgunOptions);
 ```
 
 ### Mailjet Provider
@@ -301,7 +363,8 @@ const mailjet = mailjetProvider({
 const mail = createMail(mailjet);
 
 // Send email with Mailjet-specific options
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>").send();
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>");
+const result = await mail.send(message);
 
 // Or use Mailjet-specific features
 import type { MailjetEmailOptions } from "@visulima/email/providers/mailjet";
@@ -320,7 +383,7 @@ const mailjetOptions: MailjetEmailOptions = {
     deliveryTime: Math.floor(Date.now() / 1000) + 3600, // Schedule for 1 hour from now
 };
 
-await mail.sendEmail(mailjetOptions);
+await mail.send(mailjetOptions);
 ```
 
 ### MailerSend Provider
@@ -359,7 +422,7 @@ const mailerSendOptions: MailerSendEmailOptions = {
     scheduledAt: Math.floor(Date.now() / 1000) + 3600, // Schedule for 1 hour from now
 };
 
-await mail.sendEmail(mailerSendOptions);
+await mail.send(mailerSendOptions);
 ```
 
 ### Mandrill Provider (Mailchimp Transactional)
@@ -393,7 +456,7 @@ const mandrillOptions: MandrillEmailOptions = {
     metadata: { orderId: "123" },
 };
 
-await mail.sendEmail(mandrillOptions);
+await mail.send(mandrillOptions);
 ```
 
 ### Postal Provider
@@ -426,7 +489,7 @@ const postalOptions: PostalEmailOptions = {
     tags: ["welcome"],
 };
 
-await mail.sendEmail(postalOptions);
+await mail.send(postalOptions);
 ```
 
 ### Mailtrap Provider
@@ -460,7 +523,7 @@ const mailtrapOptions: MailtrapEmailOptions = {
     tags: ["welcome"],
 };
 
-await mail.sendEmail(mailtrapOptions);
+await mail.send(mailtrapOptions);
 ```
 
 ### MailPace Provider
@@ -493,7 +556,7 @@ const mailPaceOptions: MailPaceEmailOptions = {
     listUnsubscribe: "<mailto:unsubscribe@example.com>",
 };
 
-await mail.sendEmail(mailPaceOptions);
+await mail.send(mailPaceOptions);
 ```
 
 ### Azure Communication Services Provider
@@ -530,7 +593,7 @@ const azureOptions: AzureEmailOptions = {
     importance: "high", // "normal" or "high"
 };
 
-await mail.sendEmail(azureOptions);
+await mail.send(azureOptions);
 ```
 
 ### Infobip Provider
@@ -564,7 +627,7 @@ const infobipOptions: InfobipEmailOptions = {
     sendAt: Date.now() + 3600000, // Schedule for 1 hour from now (milliseconds)
 };
 
-await mail.sendEmail(infobipOptions);
+await mail.send(infobipOptions);
 ```
 
 ### Scaleway Provider
@@ -596,7 +659,7 @@ const scalewayOptions: ScalewayEmailOptions = {
     projectId: "project-uuid", // Optional
 };
 
-await mail.sendEmail(scalewayOptions);
+await mail.send(scalewayOptions);
 ```
 
 ### AhaSend Provider
@@ -628,7 +691,7 @@ const ahaSendOptions: AhaSendEmailOptions = {
     tags: ["welcome"],
 };
 
-await mail.sendEmail(ahaSendOptions);
+await mail.send(ahaSendOptions);
 ```
 
 ### Mailomat Provider
@@ -660,7 +723,7 @@ const mailomatOptions: MailomatEmailOptions = {
     tags: ["welcome"],
 };
 
-await mail.sendEmail(mailomatOptions);
+await mail.send(mailomatOptions);
 ```
 
 ### Sweego Provider
@@ -692,7 +755,7 @@ const sweegoOptions: SweegoEmailOptions = {
     tags: ["welcome"],
 };
 
-await mail.sendEmail(sweegoOptions);
+await mail.send(sweegoOptions);
 ```
 
 ### Brevo Provider (formerly Sendinblue)
@@ -712,7 +775,8 @@ const brevo = brevoProvider({
 const mail = createMail(brevo);
 
 // Send email with Brevo-specific options
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>").send();
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>");
+const result = await mail.send(message);
 
 // Or use Brevo-specific features
 import type { BrevoEmailOptions } from "@visulima/email/providers/brevo";
@@ -728,7 +792,7 @@ const brevoOptions: BrevoEmailOptions = {
     scheduledAt: Math.floor(Date.now() / 1000) + 3600, // Schedule for 1 hour from now
 };
 
-await mail.sendEmail(brevoOptions);
+await mail.send(brevoOptions);
 ```
 
 ### Postmark Provider
@@ -748,7 +812,8 @@ const postmark = postmarkProvider({
 const mail = createMail(postmark);
 
 // Send email with Postmark-specific options
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>").send();
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>");
+const result = await mail.send(message);
 
 // Or use Postmark-specific features
 import type { PostmarkEmailOptions } from "@visulima/email/providers/postmark";
@@ -767,7 +832,7 @@ const postmarkOptions: PostmarkEmailOptions = {
     metadata: { userId: "123" }, // Custom metadata
 };
 
-await mail.sendEmail(postmarkOptions);
+await mail.send(postmarkOptions);
 ```
 
 ### SendGrid Provider
@@ -787,7 +852,8 @@ const sendgrid = sendGridProvider({
 const mail = createMail(sendgrid);
 
 // Send email with SendGrid-specific options
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>").send();
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>");
+const result = await mail.send(message);
 
 // Or use SendGrid-specific features
 import type { SendGridEmailOptions } from "@visulima/email/providers/sendgrid";
@@ -807,7 +873,7 @@ const sendGridOptions: SendGridEmailOptions = {
     },
 };
 
-await mail.sendEmail(sendGridOptions);
+await mail.send(sendGridOptions);
 ```
 
 ### Plunk Provider
@@ -827,7 +893,8 @@ const plunk = plunkProvider({
 const mail = createMail(plunk);
 
 // Send email with Plunk-specific options
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>").send();
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Welcome").html("<h1>Welcome!</h1>");
+const result = await mail.send(message);
 
 // Or use Plunk-specific features
 import type { PlunkEmailOptions } from "@visulima/email/providers/plunk";
@@ -843,7 +910,7 @@ const plunkOptions: PlunkEmailOptions = {
     data: { name: "John" }, // Template data
 };
 
-await mail.sendEmail(plunkOptions);
+await mail.send(plunkOptions);
 ```
 
 ### Mock Provider (for Testing)
@@ -864,7 +931,8 @@ const mock = mockProvider({
 const mail = createMail(mock);
 
 // Send email (stored in memory)
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Test").html("<h1>Test</h1>").send();
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Test").html("<h1>Test</h1>");
+const result = await mail.send(message);
 
 // Access stored emails
 const sentEmails = mock.getSentEmails();
@@ -931,7 +999,8 @@ const customMailCrab = mailCrabProvider({
 // Use MailCrab provider
 const mail = createMail(mailCrab);
 
-const result = await mail.message().to("user@example.com").from("sender@example.com").subject("Test Email").html("<h1>Test</h1>").send();
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Test Email").html("<h1>Test</h1>");
+const result = await mail.send(message);
 ```
 
 **Note:** Make sure MailCrab is running locally before using this provider. MailCrab can be installed via Docker or as a standalone application.
@@ -1054,6 +1123,263 @@ Template engines are optional peer dependencies and work where their underlying
 
 \* Runtime support depends on the wrapped providers. Works if all wrapped providers support the runtime.
 
+## Disposable Email Detection
+
+The package includes support for detecting disposable email addresses using the `@visulima/disposable-email-domains` package, which is included as a dependency.
+
+### Usage
+
+```typescript
+import { isDisposableEmail } from "@visulima/email/validation/disposable-email-domains";
+
+// Check if an email is disposable
+if (isDisposableEmail("user@mailinator.com")) {
+    console.log("Disposable email detected!");
+}
+
+// With custom domains
+const customDomains = new Set(["my-disposable.com"]);
+if (isDisposableEmail("user@my-disposable.com", customDomains)) {
+    console.log("Custom disposable email detected!");
+}
+```
+
+**Note:** The `@visulima/disposable-email-domains` package is included as a dependency, so no additional installation is required.
+
+## Email Verification
+
+The package provides comprehensive email verification utilities including MX record checking, SMTP verification, and role account detection.
+
+### MX Record Checking
+
+Check if a domain has valid MX (Mail Exchange) records:
+
+```typescript
+import { checkMxRecords } from "@visulima/email/validation/check-mx-records";
+
+const result = await checkMxRecords("example.com");
+
+if (result.valid) {
+    console.log("MX records:", result.records);
+    // Records are sorted by priority (lowest first)
+} else {
+    console.error("No MX records found:", result.error);
+}
+```
+
+#### Caching MX Records
+
+Use caching to improve performance and reduce DNS lookups:
+
+```typescript
+import { checkMxRecords } from "@visulima/email/validation/check-mx-records";
+import { InMemoryCache } from "@visulima/email/utils/cache";
+
+// Create a cache instance
+const cache = new InMemoryCache();
+
+// Use cache with default TTL (1 hour)
+const result1 = await checkMxRecords("example.com", { cache });
+
+// Use cache with custom TTL (5 minutes)
+const result2 = await checkMxRecords("example.com", {
+    cache,
+    ttl: 5 * 60 * 1000, // 5 minutes in milliseconds
+});
+
+// Clear cache when needed
+await cache.clear();
+```
+
+#### Custom Cache Implementation
+
+You can implement your own cache using the `Cache` interface (e.g., for Redis, LRU cache, etc.):
+
+```typescript
+import type { Cache, MxCheckResult } from "@visulima/email/utils/cache";
+import { checkMxRecords } from "@visulima/email/validation/check-mx-records";
+
+// Example: Custom Redis cache implementation
+const redisCache: Cache<MxCheckResult> = {
+    get: async (key: string) => {
+        const cached = await redis.get(`mx:${key}`);
+        return cached ? JSON.parse(cached) : undefined;
+    },
+    set: async (key: string, value: MxCheckResult, ttl: number) => {
+        await redis.setex(`mx:${key}`, Math.floor(ttl / 1000), JSON.stringify(value));
+    },
+    delete: async (key: string) => {
+        await redis.del(`mx:${key}`);
+    },
+    clear: async () => {
+        // Clear all MX cache keys
+        const keys = await redis.keys("mx:*");
+        if (keys.length > 0) {
+            await redis.del(...keys);
+        }
+    },
+};
+
+// Use custom cache
+const result = await checkMxRecords("example.com", {
+    cache: redisCache,
+    ttl: 10 * 60 * 1000, // 10 minutes
+});
+```
+
+### Role Account Detection
+
+Detect if an email address is a role account (non-personal email like `noreply@`, `support@`, etc.):
+
+```typescript
+import { isRoleAccount } from "@visulima/email/validation/role-accounts";
+
+if (isRoleAccount("noreply@example.com")) {
+    console.log("This is a role account");
+}
+
+// With custom role prefixes
+const customPrefixes = new Set(["custom-role", "my-role"]);
+if (isRoleAccount("custom-role@example.com", customPrefixes)) {
+    console.log("Custom role account detected");
+}
+```
+
+### SMTP Verification
+
+Verify if an email address exists by connecting to the mail server:
+
+```typescript
+import { verifySmtp } from "@visulima/email/validation/verify-smtp";
+import { InMemoryCache } from "@visulima/email/utils/cache";
+import type { MxCheckResult, SmtpVerificationResult } from "@visulima/email/validation/check-mx-records";
+
+// Create separate caches for MX records and SMTP results
+const mxCache = new InMemoryCache<MxCheckResult>();
+const smtpCache = new InMemoryCache<SmtpVerificationResult>();
+
+const result = await verifySmtp("user@example.com", {
+    timeout: 5000,
+    fromEmail: "test@example.com",
+    port: 25,
+    cache: mxCache, // Optional: cache MX records
+    smtpCache, // Optional: cache SMTP verification results
+    ttl: 5 * 60 * 1000, // Cache for 5 minutes
+});
+
+if (result.valid) {
+    console.log("Email address exists");
+} else {
+    console.error("Verification failed:", result.error);
+}
+```
+
+**Note:** Many mail servers block SMTP verification to prevent email harvesting. This method may not work for all domains.
+
+### Comprehensive Email Verification
+
+Combine all verification checks in a single function:
+
+```typescript
+import { verifyEmail } from "@visulima/email/validation/verify-email";
+import { InMemoryCache } from "@visulima/email/utils/cache";
+import type { MxCheckResult, SmtpVerificationResult } from "@visulima/email/validation/check-mx-records";
+
+// Create separate caches for MX records and SMTP results
+const mxCache = new InMemoryCache<MxCheckResult>();
+const smtpCache = new InMemoryCache<SmtpVerificationResult>();
+
+const result = await verifyEmail("user@example.com", {
+    checkDisposable: true,
+    checkRoleAccount: true,
+    checkMx: true,
+    checkSmtp: false, // Optional, many servers block this
+    cache: mxCache, // Optional: cache MX records
+    smtpCache, // Optional: cache SMTP verification results
+    customDisposableDomains: new Set(["custom-disposable.com"]),
+    customRolePrefixes: new Set(["custom-role"]),
+});
+
+if (result.valid) {
+    console.log("Email is valid!");
+} else {
+    console.error("Errors:", result.errors);
+    console.warn("Warnings:", result.warnings);
+}
+
+// Access individual check results
+console.log("Format valid:", result.formatValid);
+console.log("Is disposable:", result.disposable);
+console.log("Is role account:", result.roleAccount);
+console.log("MX valid:", result.mxValid);
+console.log("SMTP valid:", result.smtpValid);
+```
+
+### Email Utilities
+
+The package also exports standalone utility functions that can be used independently:
+
+#### Email Validation
+
+```typescript
+import { validateEmail } from "@visulima/email/validation/validate-email";
+
+if (validateEmail("user@example.com")) {
+    console.log("Valid email!");
+}
+```
+
+#### Parse Email Address
+
+```typescript
+import { parseAddress } from "@visulima/email/utils/parse-address";
+
+// Parse email with name
+const address = parseAddress("John Doe <john@example.com>");
+// { name: "John Doe", email: "john@example.com" }
+
+// Parse email without name
+const simple = parseAddress("jane@example.com");
+// { email: "jane@example.com" }
+```
+
+#### Format Email Address
+
+```typescript
+import { formatEmailAddress } from "@visulima/email/utils/format-email-address";
+
+const formatted = formatEmailAddress({
+    email: "user@example.com",
+    name: "John Doe",
+});
+// "John Doe <user@example.com>"
+
+const simple = formatEmailAddress({ email: "user@example.com" });
+// "user@example.com"
+```
+
+#### Normalize Email Aliases
+
+Normalize email aliases for supported providers (Gmail, Yahoo, Outlook, etc.):
+
+```typescript
+import { normalizeEmailAliases } from "@visulima/email/utils/normalize-email-aliases";
+
+// Gmail: removes dots and plus aliases
+normalizeEmailAliases("example+test@gmail.com"); // "example@gmail.com"
+normalizeEmailAliases("ex.ample@gmail.com"); // "example@gmail.com"
+
+// Yahoo, Outlook, FastMail, Mail.com, GMX, etc.: removes plus aliases only
+normalizeEmailAliases("user+tag@yahoo.com"); // "user@yahoo.com"
+normalizeEmailAliases("user.name@yahoo.com"); // "user.name@yahoo.com" (dots preserved)
+normalizeEmailAliases("user+tag@fastmail.com"); // "user@fastmail.com"
+normalizeEmailAliases("user+tag@mail.com"); // "user@mail.com"
+normalizeEmailAliases("user+tag@gmx.com"); // "user@gmx.com"
+
+// Unsupported domains return unchanged
+normalizeEmailAliases("user@example.com"); // "user@example.com"
+```
+
 ## Related
 
 ## Supported Node.js Versions
@@ -1072,13 +1398,23 @@ If you would like to help take a look at the [list of issues](https://github.com
 - [Daniel Bannert](https://github.com/prisis)
 - [All Contributors](https://github.com/visulima/visulima/graphs/contributors)
 
+## Made with ❤️ at Anolilab
+
+This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Anolilab](https://www.anolilab.com/open-source) is a Development and AI Studio. Contact us at [hello@anolilab.com](mailto:hello@anolilab.com) if you need any help with these technologies or just want to say hi!
+
 ## License
 
-The visulima email is open-sourced software licensed under the [MIT][license-url]
+The visulima email is open-sourced software licensed under the [MIT][license]
+
+<!-- badges -->
 
-[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
-[typescript-url]: https://www.typescriptlang.org/ "TypeScript"
-[license-image]: https://img.shields.io/npm/l/@visulima/email?color=blueviolet&style=for-the-badge
-[license-url]: LICENSE.md "license"
-[npm-image]: https://img.shields.io/npm/v/@visulima/email/latest.svg?style=for-the-badge&logo=npm
-[npm-url]: https://www.npmjs.com/package/@visulima/email/v/latest "npm"
+[license-badge]: https://img.shields.io/npm/l/@visulima/email?style=for-the-badge
+[license]: https://github.com/visulima/visulima/blob/main/LICENSE
+[npm-downloads-badge]: https://img.shields.io/npm/dm/@visulima/email?style=for-the-badge
+[npm-downloads]: https://www.npmjs.com/package/@visulima/email
+[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
+[prs-welcome]: https://github.com/visulima/visulima/blob/main/.github/CONTRIBUTING.md
+[chat-badge]: https://img.shields.io/discord/932323359193186354.svg?style=for-the-badge
+[chat]: https://discord.gg/TtFJY8xkFK
+[typescript-badge]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]: https://www.typescriptlang.org/