Cómo crear reglas de buzón con Microsoft Graph PowerShell

En este tutorial, le mostraré cómo crear reglas de buzón en Exchange Online usando Microsoft Graph PowerShell. Cubriré qué permisos se requieren para completar las tareas (tanto permisos delegados como de aplicación), cómo construir sus propias condiciones y acciones de reglas y cómo aplicar la regla del buzón a varios usuarios de su inquilino.

Para crear las reglas del buzón utilizaremos el cmdlet New-MgUserMailFolderMessageRule que se incluye en el módulo Microsoft.Graph.Mail.

Requisitos previos y permisos

En primer lugar, para ejecutar nuestro script y los comandos necesarios, debe tener instalado el SDK de Microsoft Graph PowerShell. Consulte mi tutorial sobre cómo instalar el módulo Microsoft Graph PowerShell.

También debe asegurarse de que el usuario con el que inicia sesión en su inquilino tenga los permisos necesarios para realizar estas acciones; en la mayoría de los casos, los derechos de administrador global serán suficientes.

Cómo crear una regla de buzón usando Microsoft Graph PowerShell

Ahora echemos un vistazo a cómo crear una regla de buzón único en una cuenta de usuario única usando Microsoft Graph PowerShell. He comentado el guión a continuación para ayudarle a comprender lo que está sucediendo.

En el siguiente script, estamos creando una regla de buzón que se aplica a los remitentes que incluyen una cadena específica en su dirección de remitente y para enviarles correos electrónicos moviéndolos todos a una carpeta específica.

Como también puede ver, hay cierta información que debemos proporcionar para que esto suceda. En primer lugar, los usuarios UPN a los que queremos que se aplique la regla, luego el nombre de la carpeta de destino, el nombre para mostrar de la regla y también el el remitente contiene el campo.

#Import the graph module
Import-Module Microsoft.Graph.Mail

#Connect to Microsoft Graph
Connect-MgGraph -Scope MailboxSettings.Read, MailboxSettings.ReadWrite, Mail.ReadWrite

#Complete the below with the requested information
$targetuser = "your UPN here"
$targetfolder = "Target folder name here"
$userid = $targetuser

#Store the target folder
$targetfolder = Get-MgUserMailFolder -UserId $userId -filter "DisplayName eq '$targetfolder'"

#Store the inbox folder (New rules can only be created on the inbox folder)
$MailboxFolder = Get-MgUserMailFolder -UserId $userId -filter "DisplayName eq 'inbox'"

#Define the Conditions and Actions
$params = @{
	DisplayName = "Company-Wide Move To Training Folder"
	Sequence = 2
	IsEnabled = $true
	Conditions = @{
		SenderContains = @(
			"[email "
		)
	}
	Actions = @{
		moveToFolder = $targetfolder.id
		StopProcessingRules = $true
	}
}

#Create the rule
New-MgUserMailFolderMessageRule -UserId $userId -MailFolderId $mailboxfolder.id -BodyParameter $params

Una vez que se ejecuta el script, debería ver un resultado como el siguiente:

También puede verificar que esto se haya completado como se esperaba iniciando sesión en outlook.office.com como su usuario objetivo haciendo clic en Configuración > Ver todas las configuraciones de Outlook > Reglas.

Aquí hay otro ejemplo en el que me centraré únicamente en la sección de parámetros de regla del script, ya que esto es lo que probablemente cambiará. Aquí especificamos si el correo electrónico proviene de "[correo electrónico protegido]" y contiene "Capacitación" en el campo de asunto, luego lo movemos a la carpeta de destino y lo marcamos como de alta importancia.

$params = @{
	DisplayName = "Company-Wide Move To Training Folder"
	Sequence = 2
	IsEnabled = $true
	Conditions = @{
		SenderContains = @(
			"[email "
		)
		SubjectContains = @(
			"Training"
		)
	}
	Actions = @{
		moveToFolder = $targetfolder.id
		markImportance = "high"
	}
}

Cómo construir tu propia regla de mensajes en formato JSON

Si no desea utilizar los ejemplos anteriores, lo mejor que puede hacer es construir sus propias condiciones y acciones de reglas, así que echemos un vistazo a cómo construir su propia regla.

En primer lugar, comencemos con una línea de base, a continuación se muestra el cuerpo de nuestros parámetros definidos, como puede ver, los campos de condiciones y acciones están vacíos. También hay algunos parámetros iniciales que debemos proporcionar, como el DisplayName, el número de Sequence y IsEnabled (donde está habilitado o no). .

$params = @{
	DisplayName = "#DisplayName#"
	Sequence = 2 #supply a number
	IsEnabled = $true #true or false
	Conditions = @{
		#conditions
	}
	Actions = @{
		#Actions
	}
}

Hay muchos parámetros diferentes que puede proporcionar en los campos de condición y acciones del script; eche un vistazo a las listas a continuación para ver qué está disponible.

Condiciones opcionales

“bodyContains”: [“Cadena”]
“bodyOrSubjectContains”: [“String”]
“categorías”: [“String”], “fromAddresses ”: [{“@odata.type”: “microsoft.graph.recipient” }]
“hasAttachments”: “Booleano”, “headerContains”: [“Cadena”]
“importancia”: “String”, “isApprovalRequest”: “Booleano”
“isAutomaticForward”: “Booleano”
“isAutomaticReply”: “Booleano”
“isEncrypted”: “Booleano”
“isMeetingRequest”: “Booleano”
“isMeetingResponse”: “Booleano”
“isNonDeliveryReport”: “Booleano”
“isPermissionControlled”: “Booleano”
“isReadReceipt”: “Booleano”
“isSigned”: “Booleano”
“isVoicemail”: “Booleano”
“messageActionFlag”: “Cadena”
“notSentToMe”: “Booleano”
“destinatarioContiene”: [“Cadena”]
“senderContains”: [“String”]
“sensibilidad”: “Cadena”
“sentCcMe”: “Booleano”
“sentOnlyToMe”: “Booleano”
“sentToAddresses”: [{“@odata.type”: “microsoft.graph.destinatario”}]
“sentToMe”: “Booleano”
“sentToOrCcMe”: “Booleano”
“subjectContains”: [“String”]
“withinSizeRange”: {“@odata.type”: “microsoft.graph.sizeRange”}

Acciones opcionales

“assignCategories”: [“Cadena”]
“copyToFolder”: “String”
“eliminar”: “Booleano”
“forwardAsAttachmentTo”: [{“@odata.type”: “microsoft.graph.destinatario”}]
“forwardTo”: [{“@odata.type”: “microsoft.graph.destinatario”}]
“markAsRead”: “Booleano”
“markImportance”: “Cadena”
“moveToFolder”: “String”
“permanentDelete”: “Booleano”
“redirectTo”: {“@odata.type”: “microsoft.graph.destinatario”}
“stopProcessingRules”: “Booleano”

Para incluir los distintos tipos de condiciones y acciones en su secuencia de comandos, puede hacerlo incluyéndolas en el formato correspondiente. No todos los parámetros se especifican en el mismo formato, por lo que a continuación se muestran algunos ejemplos.

Ejemplo: “copyToFolder”: “String”

Al apuntar a una carpeta, se debe especificar la identificación de la carpeta. Utilice mi ejemplo en el script anterior para recopilar la identificación de la carpeta.

copyToFolder = $targetfolder.id

Ejemplo: “markAsRead”: “Booleano”

Como se trata de un valor booleano, puede ser Verdadero o Falso.

markAsRead: $true or $false

Ejemplo: “bodyOrSubjectContains”: [“String”]

Aunque el valor está en formato 'cadena', está entre corchetes, esto significa que cuando especificamos este parámetro, debe presentarse en una matriz.

bodyContains = @(
			"important information"
		)

Cómo crear una regla de buzón para todos los usuarios

Desafortunadamente, a diferencia de cuando aplicamos la configuración del buzón a nuestro propio contexto de usuario, no podemos aplicar la configuración del buzón a ningún otro usuario mientras usamos permisos delegados en Microsoft Graph PowerShell (que es el único tipo de permiso que podemos usar cuando usamos un mensaje de inicio de sesión interactivo). Esto se debe a que la configuración del buzón no es propiedad del usuario, sino que se guarda en la configuración del buzón, a la que no se puede acceder mediante permisos delegados. Sin embargo, esto no queda tan claro en MS Docs, así que téngalo en cuenta.

Para lograr nuestro objetivo, primero debemos registrar una aplicación en Azure AD y luego proporcionarle los permisos Graph necesarios. Tiene la opción de usar un secreto de cliente o un certificado para autenticarse en 365, por lo que en nuestro caso usaremos un secreto para simplificar el proceso. Sigue estos pasos:

1. Comience iniciando sesión en Azure AD con una cuenta de administrador global https://aad.portal.azure.com/

2. Seleccione Azure Active Directory en el menú de la izquierda y luego seleccione Registros de aplicaciones.

3. Seleccione Nuevo registro. Ingrese un nombre para su aplicación, seleccione Cuentas solo en este directorio organizacional e ingrese un URI de redireccionamiento (acabo de usar office.com). Luego haga clic en registrarse.

4. Tome nota del ID de la aplicación (cliente) en la pestaña de descripción general, ya que lo necesitaremos en nuestro script.

5. En el menú de la izquierda, seleccione Permisos de API.

6. Haga clic en Agregar un permiso, luego seleccione Microsoft Graph y haga clic en Permisos de aplicación.

7. En el cuadro de búsqueda, busque y seleccione los siguientes permisos:

Configuración del buzón.ReadWrite
Correo.Leer
Usuario.Leer.Todo

y haga clic en Agregar permisos.

8. Mientras esté en la página de registro de la aplicación, seleccione Otorgar consentimiento de administrador para... y haga clic en Sí en la ventana emergente.

9. Ahora, en el menú de la izquierda, seleccione Certificado y secretos.

10. Haga clic en Agregar nuevo secreto y aparecerá una nueva ventana a la derecha. Ingrese la descripción y la duración de vencimiento, luego haga clic en Agregar.

11. Una vez que haya creado el secreto, lo verá en la página de registros de la aplicación. Tome nota del Valor y del ID secreto, ya que los necesitaremos en nuestro script.

12. Por último, solo necesitamos tomar el ID del inquilino. Podemos hacer esto regresando a https://aad.portal.azure.com/ y seleccionando Azure Active Directory en el menú de la izquierda. La ID del inquilino aparecerá en la pestaña Descripción general.

Guión completo

Aquí está el script completo que implementará su regla de buzón para todos los usuarios de su inquilino de Microsoft 365.