Email Service - FadiZahhar/umbraco8showandtell GitHub Wiki

Great! You want a step-by-step tutorial on using the email service in Umbraco 8, based on the code inside your latest HighlyDeveloped.Core.zip.
I’ll extract and examine your code, then write a clear guide on best-practice email sending (and settings) for Umbraco 8, including practical usage examples.

Let’s start by extracting and reviewing your code.

Here’s what’s relevant for emailing in your codebase:

  • Services/EmailService.cs (the actual email-sending logic)

  • Interfaces/IEmailService.cs (the contract/interface)

  • RegisterServicesComposer.cs (dependency injection registration for Umbraco’s DI container)

Let’s review these files and then I’ll walk you through using your email service in Umbraco 8, following best practices.


Step 1: Review IEmailService.cs (Interface)

Let’s look at the interface first.

Your interface is simple and clear:

public interface IEmailService
{
    void SendContactNotificationToAdmin(ContactFormViewModel vm);
}
  • It requires an implementation to send a contact notification email to admin, given a view model.


Step 2: Review EmailService.cs (Implementation)

Let’s see how the service actually sends the email.

Your EmailService does the following (following best practices for an Umbraco 8 service):

  • Uses dependency injection for Umbraco services (UmbracoHelper, IContentService, ILogger).

  • Fetches email templates from Umbraco content nodes (dynamic, editable by content editors).

  • Reads email addresses (From, To, Test accounts) and a test/debug mode flag from Site Settings.

  • Uses mail merge to personalize template content (replaces ##name##, ##email##, etc).

  • Logs all sent emails as Umbraco content nodes (audit trail).

  • Sends email via SmtpClient with HTML and plain text support.

  • Catches and logs errors robustly.


Step 3: How is the Service Registered for DI?

Let’s quickly check the composer to ensure you can inject IEmailService anywhere.

Your RegisterServicesComposer properly registers your service:

public class RegisterServicesComposer : IUserComposer
{
    public void Compose(Composition composition)
    {
        composition.Register<IEmailService, EmailService>(Lifetime.Request);
    }
}
  • This means anywhere in Umbraco 8, you can inject IEmailService and use it!


📨 Step-by-Step: Using the Email Service in Umbraco 8


Step 1: Set Up Content for Configuration and Templates

A. Site Settings

In your Umbraco backoffice, under Settings → Document Types, ensure you have a siteSettings node with:

  • emailSettingsFromAddress (Textstring)

  • emailSettingsAdminAccounts (Textbox Multiple, comma-separated for multiple emails)

  • testMode (True/False)

  • emailTestAccounts (Textbox Multiple)

B. Email Template

Create a Document Type: emailTemplate with:

  • emailTemplateSubjectLine (Textstring)

  • emailTemplateHtmlContent (Richtext Editor or Textbox)

  • emailTemplateTextContent (Textbox)

Create a node named "New Contact Form Notification" (or any name you want) under a folder like "Emails".

  • In your HTML/Text, use merge fields like ##name##, ##email##, ##comment##.


Step 2: Dependency Injection—Use the Service Anywhere

In any SurfaceController, Composer, or Service, inject the interface:

private readonly IEmailService _emailService;

public MyController(IEmailService emailService) { _emailService = emailService; }

In SurfaceControllers, if you use parameterless constructors, you can resolve with Current.Factory.GetInstance<IEmailService>().


Step 3: Sending an Email (Contact Form Example)

When you want to send an email:

using HighlyDeveloped.Core.ViewModel;

public ActionResult SubmitContact(ContactFormViewModel vm) { // ... your form validation, captcha, etc ...

_emailService.SendContactNotificationToAdmin(vm);

// Show success to user, etc.
TempData["status"] = "OK";
return RedirectToCurrentUmbracoPage();

}

  • The SendContactNotificationToAdmin method handles everything: template, merge, logging, sending.


Step 4: Best Practice Highlights

  • Email content is editable in Umbraco—no redeploy needed to change wording or design.

  • All sent emails are logged as Umbraco content (you can review/audit later).

  • Debug/test mode lets you redirect all emails to a test inbox safely.

  • Full error logging using Umbraco’s logging abstraction.


Step 5: Configure SMTP

Set your SMTP settings in your web.config (or via appSettings):

<system.net>
  <mailSettings>
    <smtp from="[email protected]">
      <network host="smtp.yourdomain.com" port="587" userName="smtpuser" password="smtppassword" enableSsl="true" />
    </smtp>
  </mailSettings>
</system.net>

Tip: Use a transactional email service (e.g., SendGrid, Mailgun) for reliability, especially in production.


Step 6: Review and Test

  • Make sure you create at least one emailTemplate and set up your site settings node.

  • Try submitting a contact form—emails should be logged under your "Emails" folder and delivered.


Summary Table

Task Location Details
Interface Interfaces/IEmailService.cs Contract for email actions
Service Implementation Services/EmailService.cs Fetches templates, logs, sends email
DI Registration RegisterServicesComposer.cs Registers service for injection
Site Settings/Template Umbraco content nodes Configurable by content editors
Usage Any controller/service via injection _emailService.SendContactNotificationToAdmin(vm)

Best Practice Email Usage in Umbraco 8

  1. Configure: All addresses and templates are editable in Umbraco.

  2. Inject: Use the DI container to inject your service.

  3. Send: Call the appropriate method (SendContactNotificationToAdmin).

  4. Audit: All emails are saved as Umbraco content for history/auditing.

  5. Safe Testing: Flip a switch in site settings to enter test mode.


You now have a professional, maintainable, and testable email infrastructure in your Umbraco 8 project!
If you want an example of customizing a new template or sending a different kind of email (e.g., password reset, welcome message), just ask!

⚠️ **GitHub.com Fallback** ⚠️