make mail field optionally configurable for the user

this change explicitly depends on acceptance of
Azure/azure-rest-api-specs#12127

internal/services/aadgraph/user_resource.go

@@ -85,8 +85,10 @@ func userResource() *schema.Resource {
 			},
 
 			"mail": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:         schema.TypeString,
+				Optional:     true,
+				Computed:     true,
+				ValidateFunc: validate.StringIsEmailAddress,
 			},
 
 			"onpremises_sam_account_name": {
@@ -201,8 +203,14 @@ func userResourceCreate(d *schema.ResourceData, meta interface{}) error {
 	ctx := meta.(*clients.AadClient).StopContext
 
 	upn := d.Get("user_principal_name").(string)
+	mail := d.Get("mail").(string)
 	mailNickName := d.Get("mail_nickname").(string)
 
+	//default mail to the upn if not set to a different address
+	if mail == "" {
+		mail = upn
+	}
+
 	//default mail nickname to the first part of the UPN (matches the portal)
 	if mailNickName == "" {
 		mailNickName = strings.Split(upn, "@")[0]
@@ -211,6 +219,7 @@ func userResourceCreate(d *schema.ResourceData, meta interface{}) error {
 	userCreateParameters := graphrbac.UserCreateParameters{
 		AccountEnabled: utils.Bool(d.Get("account_enabled").(bool)),
 		DisplayName:    utils.String(d.Get("display_name").(string)),
+		Mail:           &mail,
 		MailNickname:   &mailNickName,
 		PasswordProfile: &graphrbac.PasswordProfile{
 			ForceChangePasswordNextLogin: utils.Bool(d.Get("force_password_change").(bool)),
@@ -313,6 +322,10 @@ func userResourceUpdate(d *schema.ResourceData, meta interface{}) error {
 		userUpdateParameters.Surname = utils.String(d.Get("surname").(string))
 	}
 
+	if d.HasChange("mail") {
+		userUpdateParameters.Mail = utils.String(d.Get("mail").(string))
+	}
+
 	if d.HasChange("mail_nickname") {
 		userUpdateParameters.MailNickname = utils.String(d.Get("mail_nickname").(string))
 	}

internal/services/aadgraph/user_resource_test.go

@@ -181,6 +181,7 @@ resource "azuread_user" "test" {
   display_name    = "acctestUser-%[1]d-Updated"
   given_name      = "acctestUser-%[1]d-GivenName"
   surname         = "acctestUser-%[1]d-Surname"
+  mail            = "acctestUser.%[1]d.Updated@${data.azuread_domains.tenant_domain.domains.0.domain_name}"
   mail_nickname   = "acctestUser-%[1]d-Updated"
   account_enabled = false
   password        = "%[2]s"