How to send email from Umbraco with SMTP

Why Umbraco needs SMTP

Umbraco sends email for password resets, user invitations, notifications and health check reports. Your own code, such as a contact form, can use the same settings. Until SMTP is configured, none of these emails go out.

Step 1: Configure SMTP

{
  "Umbraco": {
    "CMS": {
      "Global": {
        "Smtp": {
          "From": "website@example.com",
          "Host": "smtp.sendgrid.net",
          "Port": 587,
          "SecureSocketOptions": "StartTls",
          "Username": "apikey"
        }
      }
    }
  }
}

Typical settings for popular providers:

• Microsoft 365: host smtp.office365.com, port 587, StartTls. The sending account needs SMTP AUTH enabled.
• SendGrid: host smtp.sendgrid.net, port 587, username apikey, and your API key as the password.
• Mailgun: host smtp.mailgun.org, port 587, with your domain's SMTP credentials.

Step 2: Keep the password out of source control

Never put the SMTP password in appsettings.json. Use one of these instead:

# On your machine (stored outside the project)
dotnet user-secrets init
dotnet user-secrets set "Umbraco:CMS:Global:Smtp:Password" "your-password"

# On the server, as an environment variable
Umbraco__CMS__Global__Smtp__Password=your-password

Azure App Service: add it under Settings › Environment variables as Umbraco__CMS__Global__Smtp__Password.

Step 3: Test without sending real email

In development, catch every email locally with a tool such as smtp4dev or Mailpit:

docker run --rm -p 3000:80 -p 2525:25 rnwood/smtp4dev

{
  "Umbraco": {
    "CMS": {
      "Global": {
        "Smtp": { "From": "dev@example.test", "Host": "localhost", "Port": 2525, "SecureSocketOptions": "None" }
      }
    }
  }
}

Open http://localhost:3000 to see every email your site sends.

Step 4: Send your own emails

Inject IEmailSender anywhere, such as a controller, a notification handler or a background job:

using Umbraco.Cms.Core.Mail;
using Umbraco.Cms.Core.Models.Email;

var message = new EmailMessage(
    from: "website@example.com",
    to: "team@example.com",
    subject: "New enquiry",
    body: "<p>Someone filled in the contact form.</p>",
    isBodyHtml: true);

await emailSender.SendAsync(message, emailType: "ContactForm");

emailType is a label you choose. It appears in logs and lets other code react to specific kinds of email.

Deliverability checklist

• Add SPF, DKIM and DMARC DNS records for the domain you send from, or your emails will land in spam.
• Send from an address on your own domain, not a free webmail address.
• Check Settings › Health Check › SMTP in the backoffice to confirm Umbraco can reach your mail server.