Home SharePoint Customizing the SharePoint Welcome Email

If you’ve tried to customize the SharePoint Grant Permissions form or Welcome Email, you likely looked to Google or Bing for help. I did, and found a few options that were not supported or not recommended by Microsoft (e.g. modifying Application pages or Resource files), or didn’t quite fulfill the requirement (e.g. use jQuery to change the subject and email body, which still includes the default SharePoint message). One possible option is to create your own Application page to grant permissions and send your users to your custom page, but this requires writing all the logic from scratch.

With the use of HTTP Modules and jQuery, I was able to modify the contents of the out-of-the-box Aclinv.aspx page and intercept its post back to customize the SharePoint Group Welcome Email. Since I’m using the same OOTB page, I don’t have to worry about recreating code to manually add users to a group or site.

Let’s look at the out-of-the-box Grant Permissions (/_layouts/aclinv.aspx) page and Email Template.

sp-greantpermissions-ootb    sp-welcomeemail-ootb

This MSDN post confirms that the 1st and 3rd paragraph of the email body cannot be customized OOTB.

What if you’d like to send your users a more personalized Welcome Email?

The Goal
We’ll reuse the Grant Permissions page and have it send the Welcome Email using our own template.

Below is what the Grant Permissions page and Welcome Email should look like after our changes. Since we’re using our own email template, we don’t need the Send Email section of the page.

sp-greantpermissions-customjpg    sp-welcomeemail-custom

The Solution

This post, Modifying SharePoint Application Pages in the RIGHT WAY, makes use of an HTTP Module to add a custom validation control to the Grant Permissions page. It was a great starting point, but we want to do more than just adding a control to the page.

Here’s a summary of the steps I followed to customize the SharePoint Welcome Email:

  1. Modify the Aclinv.aspx page via jQuery to:
    1. Uncheck the Send Email checkbox to prevent the page from sending the default email
    2. Hide all Send Email controls
  2. Create an HTTP Module to:
    1. Add a custom Send Email checkbox below the user picker (this will allow users to still be able to choose whether they want to send the Welcome Email)
    2. Send custom email to user(s) using our own email template

The Code
If you’re not familiar with HTTP Modules, check out this article: The Two Interceptors: HttpModule and HttpHandlers. It also covers the events that we will make use of to add our own Send Email checkbox and send the custom email.

We will also make use of jQuery selectors. Documentation is available here: http://api.jquery.com/category/selectors/

Step 1: Modify the Aclinv.aspx page via jQuery

Create a JavaScript file with the following code:

$(document).ready(function () {    
  //uncheck default Send Email checkbox to prevent SharePoint from sending default email
  $(":checkbox[id$=ifsSendEmail_chkSendEmail]").attr('checked', false);
  //hide Send Email controls  

Add a reference to the file on your master page.

<script type="text/javascript" src="/_layouts/projectName/scripts/customwelcomeemail.js"></script>

Step 2: Create an HTTPModule

As mentioned above, Modifying SharePoint Application Pages in the RIGHT WAY, is a great starting point. All you need to do is change the page_Init method to add a checkbox instead of the custom validator control.

void page_Init(object sender, EventArgs e)
	if (page != null)
		//Find People Picker control
		Control= page.Form.FindControl("PlaceHolderMain").Controls[1].FindControl("PlaceHolderControls").Controls[1].FindControl("PlaceHolderControl").FindControl("userPicker");

		//Create new custom Send Email checkbox and add it under People Picker control
		CheckBox cb = new CheckBox();
		cb.Checked = true;
		cb.Text = "Send welcome e-mail to the new users";
		cb.ID = "chkSendCustomEmail";
		//add the custom validator just after the Add Users control
		ctrl.Parent.Controls.AddAt(ctrl.Parent.Controls.IndexOf(ctrl) + 1, cb); 

We also need to attach the EndRequest event to the HttpApplication class and create its Event Handler method (context_EndRequest).

public void Init(HttpApplication context)
    //PreRequestHandlerExecute to add custom "Send Email" checkbox
    context.PreRequestHandlerExecute += new EventHandler(context_PreRequestHandlerExecute);

    //EndRequest to process users and send email
    context.EndRequest += new EventHandler(context_EndRequest);

In the context_EndRequest method, we will check a few things:

  1. Is the current page aclinv.aspx?
  2. Was the page submitted to the server (Ok button was clicked)?
  3. Was the newly added checkbox checked?
void context_EndRequest(object sender, EventArgs)
	HttpApplication httpApp = sender as HttpApplication;

	if (httpApp != null)
		page = httpApp.Context.CurrentHandler as Page;

		if (page != null)
			//Only Process "Grant Permissions" page
			if (HttpContext.Current.Request.Url.AbsoluteUri.Contains("_layouts/aclinv.aspx"))
				if (!page.IsCallback) //will only process if Page is submitted (no callback, redirects to Users page)
					//Find newly added custom checkbox
					Control ctrlSendEmail = page.Form.FindControl("PlaceHolderMain").Controls[1].FindControl("PlaceHolderControls").Controls[1].FindControl("PlaceHolderControl").FindControl("chkSendCustomEmail");
					CheckBox chkSendEmail = (CheckBox)ctrlSendEmail;
					if (chkSendEmail != null)
						if (chkSendEmail.Checked)
							GetUsers(); //Get users and send email

If our criteria is met, we will call the GetUsers() method. This method will find the User Picker control on the page, loop through the PickerEntity list and get the user’s first and last name and email.

void GetUsers()
	if (page != null)
		//Find People Picker control and get user(s)
		PeopleEditor ctrlUserPicker = page.Form.FindControl("PlaceHolderMain").Controls[1].FindControl("PlaceHolderControls").Controls[1].FindControl("PlaceHolderControl").FindControl("userPicker") as PeopleEditor;

		if (ctrlUserPicker != null)
			PickerEntity peUser = null;
			string userName = "";
			string email = "";

			foreach (var user in ctrlUserPicker.Entities)
				//Get user data
				peUser = (PickerEntity)user;
				userName = peUser.DisplayText;
				email = peUser.EntityData["Email"].ToString();
				SendEmail(email, userName);

Once we have the user information, we can call our SendEmail method, plug in our data in the Email Template and send the email.

private void SendEmail(string Email, string UserName)
	string siteName = SPContext.Current.Web.Title;
	string siteUrl = SPContext.Current.Web.Url;

	//Check to see if email server is set
	bool blnlsEmailServerSet = SPUtility.IsEmailServerSet(SPContext.Current.Web);
	if (blnlsEmailServerSet)
		//Send email
		StringDictionary headers = new StringDictionary();
		headers.Add("To", Email);
		headers.Add("From", "sharepoint@tahoepartners.com");
		headers.Add("Subject", String.Format("Welcome to the {0} Online Community", siteName));
		headers.Add("content-type", "text/html");
		string bodyText = String.Format("Hello {0},<br /><br />Please take a moment to introduce yourself via the discussion board on the community's home page at: {1}<br /><br />The rest of the community members look forward to sharing and collaborating with you.", UserName, siteUrl);

		Boolean emailSent = true;

                        //Send false so it won't append the footer text
			emailSent = SPUtility.SendEmail(SPContext.Current.Web, headers, bodyText, false); 		});

The last step is to register your module. Look for the <modules> tag in your web.config file and add an entry for your new module.

<modules runAllManagedModulesForAllRequests="true">
   <add name="MyAddUserNotificationModule" type="Namespace.File.AddUserNotificationModule, AssemblyName, Version=, Culture=neutral, PublicKeyToken=8dd9c02f0e682ad8" />

You can get the full code for the module class here: AddUserNotificationModule.txt

And voila! Your users will now receive a personalized Welcome Email, while Admins get to use the same Grant Permissions page.

If you want to add more flexibility, you can create a list to store your Email Templates and get the list items in your SendEmail() method. The possibilities are truly endless with the power and flexibility of the ASP.Net framework.

Have you been able to accomplish this in different ways? Let us know in the comments!

3 replies to this post

Leave a Reply