Sending Email from an ASP.NET Web Pages (Razor) Site

Article
07/11/2022

This article explains how to send an email message from a website when you use ASP.NET Web Pages (Razor).

What you'll learn:

How to send an email message from your website.

How to attach a file to an email message.

This is the ASP.NET feature introduced in the article:

The WebMail helper.

Software versions used in the tutorial

ASP.NET Web Pages (Razor) 3

This tutorial also works with ASP.NET Web Pages 2.

Sending Email Messages from Your Website

There are all sorts of reasons why you might need to send email from your website. You might send confirmation messages to users, or you might send notifications to yourself (for example, that a new user has registered.) The WebMail helper makes it easy for you to send email.

To use the WebMail helper, you have to have access to an SMTP server. (SMTP stands for Simple Mail Transfer Protocol.) An SMTP server is an email server that only forwards messages to the recipient's server — it's the outbound side of email. If you use a hosting provider for your website, they probably set you up with email and they can tell you what your SMTP server name is. If you're working inside a corporate network, an administrator or your IT department can usually give you the information about an SMTP server that you can use. If you're working at home, you might even be able to test using your ordinary email provider, who can tell you the name of their SMTP server. You typically need:

The name of the SMTP server.
The port number. This is almost always 25. However, your ISP may require you to use port 587. If you are using secure sockets layer (SSL) for email, you might need a different port. Check with your email provider.
Credentials (user name, password).

In this procedure, you create two pages. The first page has a form that lets users enter a description, as if they were filling in a technical-support form. The first page submits its information to a second page. In the second page, code extracts the user's information and sends an email message. It also displays a message confirming that the problem report has been received.

[Screenshot shows a message confirming the problem report has been received.]

Note

To keep this example simple, the code initializes the WebMail helper right in the page where you use it. However, for real websites, it's a better idea to put initialization code like this in a global file, so that you initialize the WebMail helper for all files in your website. For more information, see Customizing Site-Wide Behavior for ASP.NET Web Pages.

Create a new website.

Add a new page named EmailRequest.cshtml and add the following markup:

<!DOCTYPE html>
<html>
<head>
    <title>Request for Assistance</title>
</head>
<body>
  <h2>Submit Email Request for Assistance</h2>
  <form method="post" action="ProcessRequest.cshtml">
    <div>
        Your name:
        <input type="text" name="customerName" />
    </div>

    <div>
        Your email address:
        <input type="text" name="customerEmail" />
    </div>

    <div>
        Details about your problem: <br />
        <textarea name="customerRequest" cols="45" rows="4"></textarea>
    </div>

    <div>
        <input type="submit" value="Submit" />
    </div>
  </form>
</body>
</html>

Notice that the action attribute of the form element has been set to ProcessRequest.cshtml. This means that the form will be submitted to that page instead of back to the current page.

Add a new page named ProcessRequest.cshtml to the website and add the following code and markup:
```
@{
 var customerName = Request["customerName"];
 var customerEmail = Request["customerEmail"]; 
 var customerRequest = Request["customerRequest"];
 var errorMessage = "";
 var debuggingFlag = false;
 try {
 // Initialize WebMail helper
 WebMail.SmtpServer = "your-SMTP-host";
 WebMail.SmtpPort = 25;
 WebMail.UserName = "your-user-name-here";
 WebMail.Password = "your-account-password";
 WebMail.From = "your-email-address-here";

 // Send email
 WebMail.Send(to: customerEmail,
 subject: "Help request from - " + customerName,
 body: customerRequest
 );
 }
 catch (Exception ex ) {
 errorMessage = ex.Message;
 }
}
<!DOCTYPE html>
<html>
<head>
 <title>Request for Assistance</title>
</head>
<body>
 Sorry to hear that you are having trouble, @customerName.
 @if(errorMessage == ""){
 An email message has been sent to our customer service
 department regarding the following problem:
 @customerRequest
 }
 else{
 The email was not sent.
 Please check that the code in the ProcessRequest page has 
 correct settings for the SMTP server name, a user name, 
 a password, and a "from" address.
 
 if(debuggingFlag){
 The following error was reported:
 @errorMessage
 }
 }
</body>
</html>
```
In the code, you get the values of the form fields that were submitted to the page. You then call the WebMail helper's Send method to create and send the email message. In this case, the values to use are made up of text that you concatenate with the values that were submitted from the form.

The code for this page is inside a try/catch block. If for any reason the attempt to send an email doesn't work (for example, the settings aren't right), the code in the catch block runs and sets the errorMessage variable to the error that has occurred. (For more information about try/catch blocks or the <text> tag, see Introduction to ASP.NET Web Pages Programming Using the Razor Syntax.)

In the body of the page, if the errorMessage variable is empty (the default), the user sees a message that the email message has been sent. If the errorMessage variable is set to true, the user sees a message that there's been a problem sending the message.

Notice that in the portion of the page that displays an error message, there's an additional test: if(debuggingFlag). This is a variable that you can set to true if you're having trouble sending email. When debuggingFlag is true, and if there's a problem sending email, an additional error message is displayed that shows whatever ASP.NET has reported when it tried to send the email message. Fair warning, though: the error messages that ASP.NET reports when it can't send an email message can be generic. For example, if ASP.NET can't contact the SMTP server (for example, because you made an error in the server name), the error is Failure sending mail.

Note

Important When you get an error message from an exception object (ex in the code), do not routinely pass that message through to users. Exception objects often include information that users should not see and that can even be a security vulnerability. That's why this code includes the variable debuggingFlag that's used as a switch to display the error message, and why the variable by default is set to false. You should set that variable to true (and therefore display the error message) only if you're having a problem with sending email and you need to debug. Once you have fixed any problems, set debuggingFlag back to false.

Modify the following email related settings in the code:
- Set your-SMTP-host to the name of the SMTP server that you have access to.
- Set your-user-name-here to the user name for your SMTP server account.
- Set your-account-password to the password for your SMTP server account.
- Set your-email-address-here to your own email address. This is the email address that the message is sent from. (Some email providers don't let you specify a different From address and will use your user name as the From address.)
 Tip
 
 Configuring Email Settings
 
 It can be a challenge sometimes to make sure you have the right settings for the SMTP server, port number, and so on. Here are a few tips:
 - The SMTP server name is often something like smtp.provider.com or smtp.provider.net. However, if you publish your site to a hosting provider, the SMTP server name at that point might be localhost. This is because after you've published and your site is running on the provider's server, the email server might be local from the perspective of your application. This change in server names might mean you have to change the SMTP server name as part of your publishing process.
 - The port number is usually 25. However, some providers require you to use port 587 or some other port.
 - Make sure that you use the right credentials. If you've published your site to a hosting provider, use the credentials that the provider has specifically indicated are for email. These might be different from the credentials you use to publish.
 - Sometimes you don't need credentials at all. If you're sending email using your personal ISP, your email provider might already know your credentials. After you publish, you might need to use different credentials than when you test on your local computer.
 - If your email provider uses encryption, you have to set WebMail.EnableSsl to true.
Run the EmailRequest.cshtml page in a browser. (Make sure the page is selected in the Files workspace before you run it.)
Enter your name and a problem description, and then click the Submit button. You're redirected to the ProcessRequest.cshtml page, which confirms your message and which sends you an email message.

Sending a File Using Email

You can also send files that are attached to email messages. In this procedure, you create a text file and two HTML pages. You'll use the text file as an email attachment.

In the website, add a new text file and name it MyFile.txt.
Copy the following text and paste it in the file:

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Create a page named SendFile.cshtml and add the following markup:

<!DOCTYPE html>
<html>
<head>
    <title>Attach File</title>
</head>
<body>
  <h2>Submit Email with Attachment</h2>
  <form method="post" action="ProcessFile.cshtml">
    <div>
        Your name:
        <input type="text" name="customerName" />
    </div>

    <div>
        Your email address:
        <input type="text" name="customerEmail" />
    </div>

    <div>
        Subject line: <br />
        <input type="text" size= 30 name="subjectLine" />
    </div>

    <div>
        File to attach: <br />
        <input type="text" size=60 name="fileAttachment" />
    </div>

    <div>
        <input type="submit" value="Submit" />
    </div>
  </form>
</body>
</html>

Create a page named ProcessFile.cshtml and add the following markup:

@{
    var customerName = Request["customerName"];
    var customerEmail = Request["customerEmail"]; 
    var customerRequest = Request["customerRequest"];
    var subjectLine = Request["subjectLine"];
    var fileAttachment = Request["fileAttachment"];
    var errorMessage = "";
    var debuggingFlag = false;

    try {
        // Initialize WebMail helper
        WebMail.SmtpServer = "your-SMTP-host";
        WebMail.SmtpPort = 25;
        WebMail.UserName = "your-user-name-here";
        WebMail.Password = "your-account-password";
        WebMail.From = "your-email-address-here";

        // Create array containing file name
        var filesList = new string [] { fileAttachment };

        // Attach file and send email
        WebMail.Send(to: customerEmail,
            subject: subjectLine,
            body: "File attached. <br />From: " + customerName,
            filesToAttach: filesList);
    }
    catch (Exception ex ) {
        errorMessage = ex.Message;
    }
}
<!DOCTYPE html>
<html>
<head>
    <title>Request for Assistance</title>
</head>
<body>
  <p>Sorry to hear that you are having trouble, <b>@customerName</b>.</p>
    @if(errorMessage == ""){
        <p><b>@customerName</b>, thank you for your interest.</p>
        <p>An email message has been sent to our customer service
           department with the <b>@fileAttachment</b> file attached.</p>
    }
    else{
        <p><b>The email was <em>not</em> sent.</b></p>
        <p>Please check that the code in the ProcessRequest page has 
           correct settings for the SMTP server name, a user name, 
           a password, and a "from" address.
        </p>
        if(debuggingFlag){
            <p>The following error was reported:</p>
            <p><em>@errorMessage</em></p>
        }
    }
</body>
</html>

Modify the following email related settings in the code from the example:
- Set your-SMTP-host to the name of an SMTP server that you have access to.
- Set your-user-name-here to the user name for your SMTP server account.
- Set your-email-address-here to your own email address. This is the email address that the message is sent from.
- Set your-account-password to the password for your SMTP server account.
- Set target-email-address-here to your own email address. (As before, you'd normally send an email to someone else, but for testing, you can send it to yourself.)
Run the SendFile.cshtml page in a browser.
Enter your name, a subject line, and the name of the text file to attach (MyFile.txt).
Click the Submit button. As before, you're redirected to the ProcessFile.cshtml page, which confirms your message and which sends you an email message with the attached file.

Sending Email from an ASP.NET Web Pages (Razor) Site

Software versions used in the tutorial

Sending Email Messages from Your Website

Configuring Email Settings

Sending a File Using Email

Additional Resources

Feedback

Feedback

Additional resources