Inicio rápido: Envío de un correo electrónico mediante Azure Communication Services
En este inicio rápido se describe cómo enviar un correo electrónico mediante nuestros SDK de correo electrónico.
Introducción a Azure Communication Services mediante Try Email de Communication Services a fin de enviar mensajes de correo electrónico.
Requisitos previos
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- La versión más reciente de la biblioteca cliente de .NET Core para su sistema operativo.
- Un recurso de Azure Email Communication Services creado y listo con un dominio aprovisionado. Comenzar con la creación de un recurso de comunicación por correo electrónico
- Un recurso activo de Communication Services conectado con el dominio de correo electrónico. Comenzar conectando el recurso de correo electrónico con un recurso de comunicación
Este inicio rápido supone un pequeño costo en su cuenta de Azure.
Envío de un correo electrónico mediante Try Email
Probar Email ayuda a iniciar el envío de correos electrónicos a los destinatarios deseados mediante Azure Communication Services, así como a comprobar la configuración de la aplicación para enviar correos electrónicos. También ayuda a iniciar el desarrollo de notificaciones por correo electrónico con el fragmento de código de su lenguaje preferido.
Para enviar un mensaje a un destinatario y especificar el asunto y el cuerpo del mensaje,
En la página de información general de un recurso de Azure Communication Services aprovisionado, haga clic en Probar correo electrónico en el panel de navegación izquierdo en Correo electrónico.
Seleccione uno de los dominios comprobados en la lista desplegable.
Redacte el correo electrónico que se va a enviar
- Escriba la dirección de correo electrónico del destinatario
- Escriba el asunto
- Escriba el cuerpo del mensaje del correo electrónico
Haga clic en Enviar
Correo electrónico enviado correctamente.
Ahora también puede copiar el fragmento de código de ejemplo para enviar un correo electrónico que se usará en el proyecto de ejemplo para enviar notificaciones.
El fragmento de código para enviar un correo electrónico ya está listo para usarse en el proyecto de notificación.
Introducción al uso de Azure Communication Services mediante la extensión de comunicación de la CLI de Azure para enviar mensajes de correo electrónico.
Este inicio rápido supone un pequeño costo en su cuenta de Azure.
Prerrequisitos
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- Un recurso de Azure Email Communication Services creado y listo con un dominio aprovisionado. Introducción a la creación de un recurso de Email Communication
- Un recurso de Azure Communication Services activo conectado a un dominio de correo electrónico y su cadena de conexión. Introducción a la conexión de un recurso de comunicación de correo electrónico con un recurso de Azure Communication.
- La CLI de Azure más reciente.
Comprobación de requisitos previos
- En una ventana de terminal o comando, ejecute el comando
az --version
para comprobar que la CLI de Azure y la extensión de comunicación están instaladas. - Para ver los dominios comprobados con su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal. Busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.
Instalación
Adición de la extensión
Agregue la extensión Azure Communication Services para la CLI de Azure mediante el comando az extension
.
az extension add --name communication
Inicio de sesión en la CLI de Azure
Deberá iniciar sesión en la CLI de Azure. Para iniciar sesión, ejecute el comando az login
desde el terminal y proporcione sus credenciales.
Almacenamiento de la cadena de conexión en una variable de entorno
Puede configurar la variable de entorno AZURE_COMMUNICATION_CONNECTION_STRING
para usar las operaciones de claves de la CLI de Azure sin tener que usar --connection_string
para pasar la cadena de conexión. Para configurar una variable de entorno, abra una ventana de consola y seleccione el sistema operativo en las pestañas siguientes. Reemplace <connectionString>
por la cadena de conexión real.
Nota:
No almacene la cadena de conexión como una variable de entorno sin cifrar para los entornos de producción. Esto está pensado solo para fines de prueba. Para entornos de producción, debe generar nuevas cadenas de conexión. Le recomendamos que cifre las cadenas de conexión y las cambie con regularidad.
setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"
Después de agregar la variable de entorno, puede que tenga que reiniciar todos los programas en ejecución que necesiten leer la variable de entorno, incluida la ventana de consola. Por ejemplo, si usa Visual Studio como editor, reinícielo antes de ejecutar el ejemplo.
Enviar un mensaje de correo electrónico
az communication email send
--connection-string "yourConnectionString"
--sender "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
--to "<emailalias@emaildomain.com>"
--subject "Welcome to Azure Communication Services Email" --text "This email message is sent from Azure Communication Services Email using Azure CLI."
Haga estas sustituciones en el código:
- Reemplace
<yourConnectionString>
por la cadena de conexión. - Reemplace
<emailalias@emaildomain.com>
por la dirección de correo electrónico a la que quiere enviar un mensaje. - Reemplace
<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>
por la dirección MailFrom del dominio comprobado.
El comando anterior también realiza un sondeo en el messageId y devuelve el estado de la entrega del correo electrónico. El estado puede ser uno de los siguientes:
Nombre del estado | Descripción |
---|---|
NotStarted | No estamos enviando este estado desde nuestro servicio en este momento. |
En ejecución | La operación de envío de correo electrónico está actualmente en curso y se está procesando. |
Correcto | La operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico |
Con error | La operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error. |
Parámetros opcionales
Los siguientes parámetros opcionales están disponibles en la CLI de Azure.
--html
se puede usar en lugar de--text
para el cuerpo del correo electrónico HTML.--importance
establece el tipo de importancia para el correo electrónico. Los valores conocidos son: alto, normal y bajo. El valor predeterminado es normal.--to
establece la lista de destinatarios de correo electrónico.--cc
establece direcciones de correo electrónico de copia carbón.--bcc
establece direcciones de correo electrónico de copia oculta.--reply-to
establece la dirección de correo electrónico de respuesta.--disable-tracking
indica si el seguimiento de la involucración del usuario debe deshabilitarse para esta solicitud.--attachments
establece la lista de datos adjuntos de correo electrónico.--attachment-types
establece la lista de tipos de datos adjuntos de correo electrónico, en el mismo orden de los datos adjuntos.
También puede utilizar una lista de destinatarios con --cc
y --bcc
similar a --to
. Es necesario que haya al menos un destinatario en --to
o --cc
o --bcc
.
Para empezar a usar Azure Communication Services, utilice la biblioteca cliente de correo electrónico de C# de Communication Services para enviar mensajes por correo electrónico.
Sugerencia
Inicie la experiencia de envío de correo electrónico con Azure Communication Services omitiendo directamente todo hasta el código de ejemplo Envío de correo electrónico básico y Envío de correo electrónico avanzado en GitHub.
Descripción del modelo de objetos de correo electrónico
Las clases e interfaces siguientes controlan algunas de las características principales de la biblioteca cliente de correo electrónico de Azure Communication Services para C#.
Nombre | Descripción |
---|---|
EmailAddress | Esta clase contiene una dirección de correo electrónico y una opción de nombre para mostrar. |
EmailAttachment | Esta clase crea datos adjuntos de correo electrónico al aceptar un identificador único, una cadena de tipo MIME de datos adjuntos de correo electrónico, datos binarios para el contenido y un identificador de contenido opcional para definirlo como datos adjuntos insertados. |
EmailClient | La clase es necesaria para toda la funcionalidad del correo electrónico. Cree una instancia de ella con la cadena de conexión y úsela para enviar mensajes de correo electrónico. |
EmailClientOptions | Esta clase se puede agregar a la creación de instancias de EmailClient para tener como destino una versión de API específica. |
EmailContent | Esta clase contiene el asunto y el cuerpo del mensaje de correo electrónico. Debe especificar al menos uno de los contenidos PlainText o Html |
EmailCustomHeader | Esta clase permite agregar un par nombre-valor para un encabezado personalizado. La importancia del correo electrónico también se puede especificar mediante estos encabezados con el nombre de encabezado "x-priority" o "x-msmail-priority". |
EmailMessage | Esta clase combina el remitente, el contenido y los destinatarios. También se pueden agregar encabezados personalizados, datos adjuntos y direcciones de correo electrónico de respuesta. |
EmailRecipients | Esta clase contiene listas de objetos EmailAddress para los destinatarios de mensajes de correo electrónico, incluyendo las listas opcionales para los destinatarios CC y CCO. |
EmailSendOperation | Esta clase representa la operación asincrónica de envío de correo electrónico y se devuelve desde la llamada API de envío de correo electrónico. |
EmailSendResult | Esta clase contiene los resultados de la operación de envío de correo electrónico. Tiene un identificador de operación, un estado de la operación y un objeto de error (cuando proceda). |
EmailSendResult devuelve el siguiente estado de la operación de correo electrónico realizada.
Estado | Descripción |
---|---|
NotStarted | No estamos enviando este estado desde nuestro servicio en este momento. |
En ejecución | La operación de envío de correo electrónico está actualmente en curso y se está procesando. |
Correcto | La operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico |
Con error | La operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error. |
Requisitos previos
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- La versión más reciente de la biblioteca cliente de .NET Core para su sistema operativo.
- Un recurso de Azure Email Communication Services creado y listo con un dominio aprovisionado. Comenzar con la creación de un recurso de comunicación por correo electrónico
- Un recurso activo de Communication Services conectado con el dominio de correo electrónico y una cadena de conexión. Comenzar conectando el recurso de correo electrónico con un recurso de comunicación
Este inicio rápido supone un pequeño costo en su cuenta de Azure.
Nota
También podemos enviar un correo electrónico desde nuestro propio dominio verificado. Agregar dominios personalizados verificados a Email Communication Services.
Comprobación de requisitos previos
- En una ventana de terminal o de comandos, ejecute
dotnet
para comprobar que la biblioteca cliente de .NET esté instalada. - Para ver los subdominios asociados a su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal, busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.
Creación de una aplicación de C#
En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use el comando dotnet new
para crear una nueva aplicación de consola con el nombre EmailQuickstart
. Este comando crea un sencillo proyecto "Hola mundo" de C# con un solo archivo de origen: Program.cs.
dotnet new console -o EmailQuickstart
Cambie el directorio a la carpeta de la aplicación recién creada y use el comando dotnet build
para compilar la aplicación.
cd EmailQuickstart
dotnet build
Instalar el paquete
Mientras sigue en el directorio de aplicaciones, instale el paquete de la biblioteca cliente de correo electrónico de Azure Communication Services para .NET con el comando dotnet add package
.
dotnet add package Azure.Communication.Email
Creación del cliente de correo electrónico con autenticación
Abra Program.cs y reemplace el código existente por lo siguiente para agregar directivas using
a fin de incluir el espacio de nombres Azure.Communication.Email
y un punto inicial para la ejecución de su programa.
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Azure;
using Azure.Communication.Email;
namespace SendEmail
{
internal class Program
{
static async Task Main(string[] args)
{
}
}
}
Hay algunas opciones diferentes disponibles para autenticar un cliente de correo electrónico:
Abra Program.cs en un editor de texto y reemplace el cuerpo del método Main
por el código para inicializar EmailClient
con la cadena de conexión. El siguiente código recupera la cadena de conexión para el recurso de una variable de entorno denominada COMMUNICATION_SERVICES_CONNECTION_STRING
. Aprenda a administrar la cadena de conexión del recurso.
// This code demonstrates how to fetch your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
EmailClient emailClient = new EmailClient(connectionString);
Nota:
Se recomienda usar el sondeo manual (enviar correo electrónico con sondeo de estado asincrónico) para enviar correo electrónico.
- Enviar correo electrónico con sondeo de estado asincrónico
- Enviar correo electrónico con sondeo de estado sincrónico
Envío de correo electrónico básico
Construcción del mensaje de correo electrónico
Para enviar un mensaje de correo electrónico, debe hacer lo siguiente:
- Defina el asunto y el cuerpo del correo electrónico.
- Defina la dirección del remitente. Cree el mensaje de correo electrónico con la información del remitente del que obtiene su dirección MailFrom del dominio comprobado.
- Defina la dirección del destinatario.
- Llame al método SendAsync. Agregue este código al final del método
Main
en Program.cs:
Reemplace por los detalles del dominio y modifique los detalles del contenido y destinatario según sea necesario.
//Replace with your domain and modify the content, recipient details as required
var subject = "Welcome to Azure Communication Service Email APIs.";
var htmlContent = "<html><body><h1>Quick send email test</h1><br/><h4>This email message is sent from Azure Communication Service Email.</h4><p>This mail was sent using .NET SDK!!</p></body></html>";
var sender = "donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net";
var recipient = "emailalias@contoso.com";
Envío y obtención del estado de envío de correo electrónico
Al llamar a SendAsync con Azure.WaitUntil.Started, el método vuelve después de iniciar la operación. El método devuelve un objeto EmailSendOperation. Puede llamar al método UpdateStatusAsync para actualizar el estado de la operación de correo electrónico.
El objeto EmailSendOperation devuelto contiene un objeto EmailSendStatus que contiene:
- Estado actual de la operación de envío de correo electrónico.
- Un objeto de error con detalles de error si el estado actual está en un estado de error.
/// Send the email message with WaitUntil.Started
EmailSendOperation emailSendOperation = await emailClient.SendAsync(
Azure.WaitUntil.Started,
sender,
recipient,
subject,
htmlContent);
/// Call UpdateStatus on the email send operation to poll for the status
/// manually.
try
{
while (true)
{
await emailSendOperation.UpdateStatusAsync();
if (emailSendOperation.HasCompleted)
{
break;
}
await Task.Delay(100);
}
if (emailSendOperation.HasValue)
{
Console.WriteLine($"Email queued for delivery. Status = {emailSendOperation.Value.Status}");
}
}
catch (RequestFailedException ex)
{
Console.WriteLine($"Email send failed with Code = {ex.ErrorCode} and Message = {ex.Message}");
}
/// Get the OperationId so that it can be used for tracking the message for troubleshooting
string operationId = emailSendOperation.Id;
Console.WriteLine($"Email operation id = {operationId}");
Ejecute la aplicación desde el directorio de la aplicación con el comando dotnet run
.
dotnet run
Código de ejemplo
Puede descargar la aplicación de ejemplo de GitHub.
Para empezar a usar Azure Communication Services, utilice la biblioteca cliente de correo electrónico de JS de Communication Services para enviar mensajes por correo electrónico.
Sugerencia
Inicie la experiencia de envío de correo electrónico con Azure Communication Services omitiendo directamente todo hasta el código de ejemplo Envío de correo electrónico básico y Envío de correo electrónico avanzado en GitHub.
Descripción del modelo de objetos de correo electrónico
Las clases e interfaces siguientes controlan algunas de las características principales de la biblioteca cliente de correo electrónico de Azure Communication Services para JavaScript.
Nombre | Descripción |
---|---|
EmailAddress | Esta clase contiene una dirección de correo electrónico y una opción de nombre para mostrar. |
EmailAttachment | Esta clase crea datos adjuntos de correo electrónico al aceptar un identificador único, una cadena de tipo MIME de datos adjuntos de correo electrónico, datos binarios para el contenido y un identificador de contenido opcional para definirlo como datos adjuntos insertados. |
EmailClient | La clase es necesaria para toda la funcionalidad del correo electrónico. Cree una instancia de ella con la cadena de conexión y úsela para enviar mensajes de correo electrónico. |
EmailClientOptions | Esta clase se puede agregar a la creación de instancias de EmailClient para tener como destino una versión de API específica. |
EmailContent | Esta clase contiene el asunto y el cuerpo del mensaje de correo electrónico. Debe especificar al menos uno de los contenidos PlainText o Html. |
EmailCustomHeader | Esta clase permite agregar un par nombre-valor para un encabezado personalizado. La importancia del correo electrónico también se puede especificar mediante estos encabezados con el nombre de encabezado "x-priority" o "x-msmail-priority". |
EmailMessage | Esta clase combina el remitente, el contenido y los destinatarios. También se pueden agregar encabezados personalizados, datos adjuntos y direcciones de correo electrónico de respuesta. |
EmailRecipients | Esta clase contiene listas de objetos EmailAddress para los destinatarios de mensajes de correo electrónico, incluyendo las listas opcionales para los destinatarios CC y CCO. |
EmailSendResult | Esta clase contiene los resultados de la operación de envío de correo electrónico. Tiene un identificador de operación, un estado de la operación y un objeto de error (cuando proceda). |
EmailSendStatus | Esta clase representa el conjunto de estados de una operación de envío de correo electrónico. |
EmailSendResult devuelve el siguiente estado de la operación de correo electrónico realizada.
Nombre del estado | Descripción |
---|---|
isStarted | Devuelve True si la operación de envío de correo electrónico está actualmente en curso y se está procesando. |
IsCompleted | Devuelve True si la operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico |
resultado | Propiedad que existe si la operación de envío de correo electrónico ha concluido. |
error | Propiedad que existe si la operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error. |
Requisitos previos
- Node.js (~14).
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- Un recurso de Azure Email Communication Services creado y listo con un dominio aprovisionado. Introducción a la creación de un recurso de Email Communication
- Un recurso de Azure Communication Services activo conectado a un dominio de correo electrónico y su cadena de conexión. Introducción a la conexión de un recurso de comunicación de correo electrónico con un recurso de Azure Communication.
Este inicio rápido supone un pequeño costo en su cuenta de Azure.
Nota
También podemos enviar un correo electrónico desde nuestro propio dominio verificado. Agregar dominios personalizados verificados a Email Communication Services.
Comprobación de requisitos previos
- En una ventana de terminal o de comandos, ejecute
node --version
para comprobar que Node.js está instalado. - Para ver los dominios comprobados con su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal, busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.
Configuración del entorno de la aplicación
Creación de una nueva aplicación Node.js
En primer lugar, abra la ventana de comandos o de terminal, cree un nuevo directorio para la aplicación y navegue hasta este.
mkdir email-quickstart && cd email-quickstart
Ejecute npm init -y
para crear un archivo package.json con la configuración predeterminada.
npm init -y
Use un editor de texto para crear un archivo denominado send-email.js en el directorio raíz del proyecto. Cambie la propiedad "main" de package.json a "send-email.js". En la sección siguiente se muestra cómo agregar el código fuente de este inicio rápido al archivo recién creado.
Instalar el paquete
Use el comando npm install
para instalar la biblioteca cliente de correo electrónico de Azure Communication Services para JavaScript.
npm install @azure/communication-email --save
La opción --save
muestra la biblioteca como dependencia en el archivo package.json.
Creación del cliente de correo electrónico con autenticación
Hay algunas opciones diferentes disponibles para autenticar un cliente de correo electrónico:
Importe la clase EmailClient desde la biblioteca cliente y cree una instancia con la cadena de conexión.
El código siguiente recupera la cadena de conexión del recurso de una variable de entorno denominada COMMUNICATION_SERVICES_CONNECTION_STRING
mediante el paquete dotenv. Use el comando npm install
para instalar el paquete dotenv. Aprenda a administrar la cadena de conexión del recurso.
npm install dotenv
Agregue el código siguiente a send-email.js:
const { EmailClient } = require("@azure/communication-email");
require("dotenv").config();
// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];
const emailClient = new EmailClient(connectionString);
Para facilitar las cosas, en este inicio rápido se usan cadenas de conexión, pero en los entornos de producción se recomienda usar entidades de servicio.
Envío de correo electrónico básico
Enviar un mensaje de correo electrónico
Para enviar un mensaje de correo electrónico, llame a la función beginSend
desde EmailClient. Este método devuelve un sondeo que comprueba el estado de la operación y recupera el resultado una vez finalizada.
async function main() {
const POLLER_WAIT_TIME = 10
try {
const message = {
senderAddress: "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>",
content: {
subject: "Welcome to Azure Communication Services Email",
plainText: "This email message is sent from Azure Communication Services Email using the JavaScript SDK.",
},
recipients: {
to: [
{
address: "<emailalias@emaildomain.com>",
displayName: "Customer Name",
},
],
},
};
const poller = await emailClient.beginSend(message);
if (!poller.getOperationState().isStarted) {
throw "Poller was not started."
}
let timeElapsed = 0;
while(!poller.isDone()) {
poller.poll();
console.log("Email send polling in progress");
await new Promise(resolve => setTimeout(resolve, POLLER_WAIT_TIME * 1000));
timeElapsed += 10;
if(timeElapsed > 18 * POLLER_WAIT_TIME) {
throw "Polling timed out.";
}
}
if(poller.getResult().status === KnownEmailSendStatus.Succeeded) {
console.log(`Successfully sent the email (operation id: ${poller.getResult().id})`);
}
else {
throw poller.getResult().error;
}
} catch (e) {
console.log(e);
}
}
main();
Haga estas sustituciones en el código:
- Reemplace
<emailalias@emaildomain.com>
por la dirección de correo electrónico a la que quiere enviar un mensaje. - Reemplace
<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>
por la dirección MailFrom del dominio comprobado.
Ejecución del código
use el comando node para ejecutar el código que agregó al archivo send-email.js.
node ./send-email.js
Código de ejemplo
Puede descargar la aplicación de ejemplo de GitHub.
Introducción a Azure Communication Services mediante el SDK de correo electrónico de Communication Services para Java a fin de enviar mensajes de correo electrónico.
Sugerencia
Inicie la experiencia de envío de correo electrónico con Azure Communication Services omitiendo directamente todo hasta el código de ejemplo Envío de correo electrónico básico y Envío de correo electrónico avanzado en GitHub.
Descripción del modelo de objetos de correo electrónico
Las clases e interfaces siguientes controlan algunas de las características principales del SDK de correo electrónico de Azure Communication Services para Python.
Nombre | Descripción |
---|---|
EmailAddress | Esta clase contiene una dirección de correo electrónico y una opción de nombre para mostrar. |
EmailAttachment | Esta interfaz crea datos adjuntos de correo electrónico al aceptar un identificador único, una cadena de tipo MIME de datos adjuntos de correo electrónico, una cadena de bytes de contenido y un identificador de contenido opcional para definirlo como datos adjuntos insertados. |
EmailClient | La clase es necesaria para toda la funcionalidad del correo electrónico. Cree una instancia de ella con la cadena de conexión y úsela para enviar mensajes de correo electrónico. |
EmailMessage | Esta clase combina el remitente, el contenido y los destinatarios. También se pueden agregar encabezados personalizados, datos adjuntos y direcciones de correo electrónico de respuesta. |
EmailSendResult | Esta clase contiene los resultados de la operación de envío de correo electrónico. Tiene un identificador de operación, un estado de la operación y un objeto de error (cuando proceda). |
EmailSendStatus | Esta clase representa el conjunto de estados de una operación de envío de correo electrónico. |
EmailSendResult devuelve el siguiente estado de la operación de correo electrónico realizada.
Nombre del estado | Descripción |
---|---|
NOT_STARTED | No estamos enviando este estado desde nuestro servicio en este momento. |
IN_PROGRESS | La operación de envío de correo electrónico está actualmente en curso y se está procesando. |
SUCCESSFULLY_COMPLETED | La operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico |
FAILED | La operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error. |
Requisitos previos
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- Kit de desarrollo de Java (JDK), versión 8 o posterior.
- Apache Maven.
- Un recurso de Communication Services implementado y una cadena de conexión. Para obtener más información, consulte Creación de un recurso de Communication Services.
- Cree un recurso de Azure Email Communication Services para empezar a enviar correos electrónicos.
- Una identidad administrada de configuración para un entorno de desarrollo, consulte Autorización del acceso con identidad administrada.
Este inicio rápido supone un pequeño costo en su cuenta de Azure.
Nota
También podemos enviar un correo electrónico desde nuestro propio dominio verificado Agregar dominios verificados personalizados a Email Communication Service.
Comprobación de requisitos previos
- En una ventana de terminal o de comandos, ejecute
mvn -v
para comprobar que Maven está instalado. - Para ver los dominios comprobados con su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal. Busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.
Configuración del entorno de la aplicación
Para configurar un entorno a fin de enviar correos electrónicos, siga los pasos descritos en las secciones siguientes.
Creación de una aplicación Java
Abra la ventana de terminal o de comandos y navegue hasta el directorio en el que quiere crear la aplicación de Java. Ejecute el siguiente comando para generar el proyecto Java desde la plantilla maven-archetype-quickstart.
mvn archetype:generate -DarchetypeArtifactId="maven-archetype-quickstart" -DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" -DgroupId="com.communication.quickstart" -DartifactId="communication-quickstart"
El objetivo generate
crea un directorio con el mismo nombre que el valor artifactId
. En este directorio, el directorio src/main/java contiene el código fuente del proyecto, el directorio src/test/java contiene el origen de la prueba, y el archivo pom.xml es el modelo de objetos del proyecto (POM).
Instalar el paquete
Abra el archivo pom.xml en el editor de texto. Agregue el siguiente elemento de dependencia al grupo de dependencias.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-email</artifactId>
<version>1.0.0-beta.2</version>
</dependency>
Instalación del marco de la aplicación
Abra /src/main/java/com/communication/quickstart/App.java en un editor de texto, agregue directivas de importación y quite la instrucción System.out.println("Hello world!");
:
package com.communication.quickstart;
import com.azure.communication.email.models.*;
import com.azure.communication.email.*;
import com.azure.core.util.polling.*;
public class App
{
public static void main( String[] args )
{
// Quickstart code goes here.
}
}
Creación del cliente de correo electrónico con autenticación
Hay algunas opciones diferentes disponibles para autenticar un cliente de correo electrónico.
Para autenticar un cliente, cree una instancia EmailClient
de con la cadena de conexión. Aprenda a administrar la cadena de conexión del recurso. También puede iniciar el cliente con cualquier cliente HTTP personalizado que implemente la interfaz com.azure.core.http.HttpClient
.
Para crear una instancia de un cliente sincrónico, agregue el siguiente código al método main
:
// You can get your connection string from your resource in the Azure portal.
String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";
EmailClient emailClient = new EmailClientBuilder()
.connectionString(connectionString)
.buildClient();
Para crear instancias de un cliente asincrónico, agregue el código siguiente al método main
:
// You can get your connection string from your resource in the Azure portal.
String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";
EmailAsyncClient emailClient = new EmailClientBuilder()
.connectionString(connectionString)
.buildAsyncClient();
Para facilitar las cosas, en este inicio rápido se usan cadenas de conexión, pero en los entornos de producción se recomienda usar entidades de servicio.
Envío de correo electrónico básico
Un mensaje de correo electrónico se puede diseñar mediante el objeto EmailMessage
en el SDK.
EmailMessage message = new EmailMessage()
.setSenderAddress("<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>")
.setToRecipients("<emailalias@emaildomain.com>")
.setSubject("Welcome to Azure Communication Services Email")
.setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");
Haga estas sustituciones en el código:
- Reemplace
<emailalias@emaildomain.com>
por la dirección de correo electrónico a la que quiere enviar un mensaje. - Reemplace
<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>
por la dirección MailFrom del dominio comprobado.
Para enviar el mensaje de correo electrónico, llame a la función beginSend
desde EmailClient
.
Al llamar a beginSend
en el cliente sincrónico, se devuelve un objeto SyncPoller
, que se puede usar para comprobar el estado de la operación y recuperar el resultado una vez finalizado. Tenga en cuenta que la solicitud inicial para enviar un correo electrónico se enviará tan pronto como se llame al método beginSend
. Enviar un correo electrónico es una operación de larga duración. Es importante tener en cuenta que el método getFinalResult()
en el sondeo es una operación de bloqueo hasta que se alcanza un estado terminal (SUCCESSFULLY_COMPLETED
o FAILED
). El método recomendado es realizar un sondeo manual a un intervalo adecuado a las necesidades de la aplicación, como se muestra en el ejemplo siguiente.
try
{
SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null); // This will send out the initial request to send an email
PollResponse<EmailSendResult> pollResponse = null;
Duration timeElapsed = Duration.ofSeconds(0);
Duration POLLER_WAIT_TIME = Duration.ofSeconds(10);
// Polling is done manually to avoid blocking the application in case of an error
while (pollResponse == null
|| pollResponse.getStatus() == LongRunningOperationStatus.NOT_STARTED
|| pollResponse.getStatus() == LongRunningOperationStatus.IN_PROGRESS)
{
pollResponse = poller.poll();
// The operation ID can be retrieved as soon as .poll() is called on the poller
System.out.println("Email send poller status: " + pollResponse.getStatus() + ", operation id: " + pollResponse.getValue().getId());
Thread.sleep(POLLER_WAIT_TIME.toMillis());
timeElapsed = timeElapsed.plus(POLLER_WAIT_TIME);
if (timeElapsed.compareTo(POLLER_WAIT_TIME.multipliedBy(18)) >= 0)
{
throw new RuntimeException("Polling timed out.");
}
}
if (poller.getFinalResult().getStatus() == EmailSendStatus.SUCCEEDED)
{
System.out.printf("Successfully sent the email (operation id: %s)", poller.getFinalResult().getId());
}
else
{
throw new RuntimeException(poller.getFinalResult().getError().getMessage());
}
}
catch (Exception exception)
{
System.out.println(exception.getMessage());
}
Ejecución del código
Vaya al directorio que contiene el archivo pom.xml y compile el proyecto mediante el comando
mvn
.mvn compile
Compilar el paquete.
mvn package
Ejecute el siguiente comando
mvn
para ejecutar la aplicación.mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"
Código de ejemplo
Puede descargar la aplicación de ejemplo de GitHub.
Introducción a Azure Communication Services mediante el SDK de correo electrónico de Communication Services para Python a fin de enviar mensajes de correo electrónico.
Sugerencia
Inicie la experiencia de envío de correo electrónico con Azure Communication Services omitiendo directamente todo hasta el código de ejemplo Envío de correo electrónico básico y Envío de correo electrónico avanzado en GitHub.
Descripción del modelo de objetos de correo electrónico
La plantilla de mensaje JSON y objeto de respuesta siguientes muestran algunas de las características principales del SDK de correo electrónico de Azure Communication Services para Python.
message = {
"content": {
"subject": "str", # Subject of the email message. Required.
"html": "str", # Optional. Html version of the email message.
"plainText": "str" # Optional. Plain text version of the email
message.
},
"recipients": {
"to": [
{
"address": "str", # Email address. Required.
"displayName": "str" # Optional. Email display name.
}
],
"bcc": [
{
"address": "str", # Email address. Required.
"displayName": "str" # Optional. Email display name.
}
],
"cc": [
{
"address": "str", # Email address. Required.
"displayName": "str" # Optional. Email display name.
}
]
},
"senderAddress": "str", # Sender email address from a verified domain. Required.
"attachments": [
{
"contentInBase64": "str", # Base64 encoded contents of the attachment. Required.
"contentType": "str", # MIME type of the content being attached. Required.
"name": "str" # Name of the attachment. Required.
}
],
"userEngagementTrackingDisabled": bool, # Optional. Indicates whether user engagement tracking should be disabled for this request if the resource-level user engagement tracking setting was already enabled in the control plane.
"headers": {
"str": "str" # Optional. Custom email headers to be passed.
},
"replyTo": [
{
"address": "str", # Email address. Required.
"displayName": "str" # Optional. Email display name.
}
]
}
response = {
"id": "str", # The unique id of the operation. Uses a UUID. Required.
"status": "str", # Status of operation. Required. Known values are:
"NotStarted", "Running", "Succeeded", and "Failed".
"error": {
"additionalInfo": [
{
"info": {}, # Optional. The additional info.
"type": "str" # Optional. The additional info type.
}
],
"code": "str", # Optional. The error code.
"details": [
...
],
"message": "str", # Optional. The error message.
"target": "str" # Optional. The error target.
}
}
Los valores response.status
se explican con más detalle en la tabla siguiente.
Nombre del estado | Descripción |
---|---|
InProgress | La operación de envío de correo electrónico está actualmente en curso y se está procesando. |
Correcto | La operación de envío de correo electrónico se ha completado sin errores y el correo electrónico ha salido para su entrega. Cualquier estado detallado sobre la entrega de correo electrónico más allá de esta fase se puede obtener mediante Azure Monitor o Azure Event Grid. Aprenda a suscribirse a eventos de correo electrónico |
Con error | La operación de envío de correo electrónico no se realizó correctamente y encontró un error. El correo electrónico no se ha enviado. El resultado contiene un objeto de error con más detalles sobre el motivo del error. |
Requisitos previos
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- Versión 3.7 o superiores de Python.
- Un recurso de Azure Email Communication Services creado y listo con un dominio aprovisionado. Introducción a la creación de un recurso de Email Communication
- Un recurso de Azure Communication Services activo conectado a un dominio de correo electrónico y su cadena de conexión. Introducción a la conexión de un recurso de comunicación de correo electrónico con un recurso de Azure Communication.
Este inicio rápido supone un pequeño costo en su cuenta de Azure.
Nota
También podemos enviar un correo electrónico desde nuestro propio dominio verificado. Agregar dominios personalizados verificados a Email Communication Services.
Comprobación de requisitos previos
- En una ventana de terminal o de comandos, ejecute
python --version
para comprobar que Python está instalado. - Para ver los dominios comprobados con su recurso de correo electrónico Email Communication Services, inicie sesión en Azure Portal. Busque el recurso Email Communication Services y abra la pestaña Aprovisionar dominios en el panel de navegación izquierdo.
Configuración del entorno de la aplicación
Para configurar un entorno a fin de enviar correos electrónicos, siga los pasos descritos en las secciones siguientes.
Creación de una nueva aplicación de Python
Abra el terminal o la ventana de comandos. A continuación, use el siguiente comando para crear un entorno virtual y activarlo. Este comando crea un nuevo directorio para la aplicación.
python -m venv email-quickstart
Vaya al directorio raíz del entorno virtual y actívelo con los siguientes comandos.
cd email-quickstart .\Scripts\activate
Use un editor de texto para crear un archivo denominado send-email.py en el directorio raíz del proyecto y agregue la estructura del programa, incluido el control de excepciones básico.
import os from azure.communication.email import EmailClient try: # Quickstart code goes here. except Exception as ex: print('Exception:') print(ex)
En las secciones siguientes, agregará todo el código fuente de este inicio rápido al archivo send-email.py que ha creado.
Instalar el paquete
Mientras sigue en el directorio de la aplicación, instale el paquete del SDK de correo electrónico de Azure Communication Services para Python con el siguiente comando.
pip install azure-communication-email
Creación del cliente de correo electrónico con autenticación
Hay algunas opciones diferentes disponibles para autenticar un cliente de correo electrónico:
Cree una instancia de EmailClient con la cadena de conexión. Aprenda a administrar la cadena de conexión del recurso.
# Create the EmailClient object that you use to send Email messages.
email_client = EmailClient.from_connection_string(<connection_string>)
Para facilitar las cosas, en este inicio rápido se usan cadenas de conexión, pero en los entornos de producción se recomienda usar entidades de servicio.
Envío de correo electrónico básico
Enviar un mensaje de correo electrónico
Para enviar un mensaje de correo electrónico, debe hacer lo siguiente:
- Construya el mensaje con los siguientes valores:
senderAddress
: una dirección de correo electrónico de remitente válida, que se encuentra en el campo MailFrom en el panel de información general del dominio vinculado al recurso de Email de Communication Services.recipients
: objeto con una lista de destinatarios de correo electrónico y, opcionalmente, listas para los destinatarios CC y CCO de correo electrónico.content
: un objeto que contiene el asunto y, opcionalmente, el texto sin formato o el contenido HTML de un mensaje de correo electrónico.
- Llame al método begin_send, que devuelve el resultado de la operación.
message = {
"content": {
"subject": "This is the subject",
"plainText": "This is the body",
"html": "<html><h1>This is the body</h1></html>"
},
"recipients": {
"to": [
{
"address": "<emailalias@emaildomain.com>",
"displayName": "Customer Name"
}
]
},
"senderAddress": "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
}
poller = email_client.begin_send(message)
print("Result: " + poller.result())
Haga estas sustituciones en el código:
- Reemplace
<emailalias@emaildomain.com>
por la dirección de correo electrónico a la que quiere enviar un mensaje. - Reemplace
<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>
por la dirección MailFrom del dominio comprobado.
Obtención del estado de la entrega del correo electrónico
Podemos sondear el estado de la entrega de correo electrónico estableciendo un bucle en el objeto de estado de la operación devuelto desde el método begin_send
de EmailClient.
POLLER_WAIT_TIME = 10
try:
email_client = EmailClient.from_connection_string(connection_string)
poller = email_client.begin_send(message);
time_elapsed = 0
while not poller.done():
print("Email send poller status: " + poller.status())
poller.wait(POLLER_WAIT_TIME)
time_elapsed += POLLER_WAIT_TIME
if time_elapsed > 18 * POLLER_WAIT_TIME:
raise RuntimeError("Polling timed out.")
if poller.result()["status"] == "Succeeded":
print(f"Successfully sent the email (operation id: {poller.result()['id']})")
else:
raise RuntimeError(str(poller.result()["error"]))
except Exception as ex:
print(ex)
Ejecución del código
Ejecute la aplicación desde el directorio de la aplicación con el comando python
.
python send-email.py
Código de ejemplo
Puede descargar la aplicación de ejemplo de GitHub.
Requisitos previos
Una cuenta de Azure con una suscripción activa o también puede crear una cuenta de Azure de forma gratuita.
Un recurso de Azure Communication Services activo o también puede crear un recurso de Communication Services.
Un recurso de Azure Logic Apps activo (aplicación lógica) y un flujo de trabajo, o cree un nuevo recurso de aplicación lógica y flujo de trabajo con el desencadenador que desee usar. Actualmente, el conector Correo electrónico de Azure Communication Services solo proporciona acciones, por lo que el flujo de trabajo de la aplicación lógica requiere un desencadenador, como mínimo. Puede crear un recurso de aplicación lógica estándar o de consumo.
Un recurso de correo electrónico de Azure Communication Services con un dominio configurado o un dominio personalizado.
Un recurso Azure Communication Services conectado a un dominio de correo electrónico de Azure.
Enviar correo electrónico
Para agregar un nuevo paso al flujo de trabajo mediante el conector de correo electrónico de Azure Communication Services, siga estos pasos:
En el diseñador, abra el flujo de trabajo de la aplicación lógica.
Consumo
En el paso en el que quiera agregar la nueva acción, seleccione Nuevo paso. Como alternativa, para agregar la nueva acción entre pasos, mueva el puntero sobre la flecha entre esos pasos, seleccione el signo más (+) y seleccione Agregar una acción.
En el cuadro de búsqueda Elegir una operación, seleccione Premium. En el cuadro de búsqueda, escriba Correo electrónico de comunicación de Azure.
En la lista de acciones, seleccione Enviar correo electrónico.
Estándar
En el paso en el que quiera agregar la nueva acción, seleccione el signo más (+). Como alternativa, para agregar la nueva acción entre pasos, mueva el puntero sobre la flecha entre esos pasos, seleccione el signo más (+) y seleccione Agregar una acción.
En el cuadro de búsqueda Agregar una acción, seleccione Premium en la lista desplegable runtime. En el cuadro de búsqueda, escriba Correo electrónico de comunicación de Azure.
En la lista de acciones, seleccione Enviar correo electrónico.
Proporcione un nombre para la conexión.
Escriba la cadena de conexión para el recurso de Azure Communications Service. Para buscar esta cadena, siga estos pasos:
En Azure Portal, abra el recurso de Azure Communication Service.
En el menú de recursos, en Configuración, seleccione Claves y copie la cadena de conexión.
Seleccione Crear cuando haya terminado.
En el campo Desde, use la dirección de correo electrónico que configuró en los requisitos previos. Escriba los valores de los campos Para, Asunto y Cuerpo, por ejemplo:
Guarde el flujo de trabajo. En la barra de herramientas del diseñador, seleccione Save (Guardar).
Prueba del flujo de trabajo
En función de si tiene un flujo de trabajo de Consumo o Estándar, inicie manualmente el flujo de trabajo:
- Consumo: en la barra de herramientas del diseñador, seleccione Ejecutar desencadenador>Ejecutar.
- Estándar: en el menú del flujo de trabajo, seleccione Información general. En la barra de herramientas, seleccione Ejecutar desencadenador>Ejecutar.
El flujo de trabajo crea un usuario, emite un token de acceso para ese usuario y, a continuación, quita y elimina al usuario. Puede comprobar las salidas de estas acciones después de que el flujo de trabajo se ejecute correctamente.
Debería obtener un correo electrónico en la dirección especificada. También puede usar la acción Obtener estado del mensaje de correo electrónico para comprobar el estado de los correos electrónicos enviados a través de la acción Enviar correo electrónico. Para más acciones, revise la documentación de referencia del conector de correo electrónico de Azure Communication Services.
Limpieza de recursos de flujo de trabajo
Para limpiar el flujo de trabajo y el recurso de la aplicación lógica, así como los recursos relacionados, revise cómo limpiar los recursos de la aplicación lógica Consumo o cómo limpiar los recursos de la aplicación lógica Estándar.
Solución de problemas
Entrega de correo electrónico
Para solucionar incidencias relacionadas con la entrega de correo electrónico, puede obtener el estado de la entrega de correo electrónico para capturar los detalles de la entrega.
Importante
El resultado correcto devuelto por el sondeo del estado de la operación de envío solo valida el hecho de que el correo electrónico se haya enviado correctamente para su entrega. Para obtener información adicional sobre el estado de la entrega en el extremo del destinatario, deberá hacer referencia a cómo controlar los eventos de correo electrónico.
limitación de correo electrónico
Si ve que la aplicación se bloquea, podría deberse a que el envío de correo electrónico está limitado. Puede controlarlo mediante el registro o mediante la implementación de una directiva personalizada.
Nota
Esta configuración de espacio aislado sirve para ayudar a los desarrolladores a empezar a compilar la aplicación. Puede solicitar gradualmente aumentar el volumen de envío una vez que la aplicación esté lista para publicarse. Envíe una solicitud de soporte técnico para aumentar el límite de envío deseado si necesita enviar un volumen de mensajes que supere los límites de frecuencia.
Limpieza de recursos de Azure Communication Service
Para limpiar y quitar una suscripción a Communication Services, puede eliminar el recurso o grupo de recursos. Al eliminar el grupo de recursos, también se eliminará cualquier otro recurso asociado. Obtenga más información sobre la limpieza de recursos.
Pasos siguientes
En esta guía de inicio rápido, aprendió a enviar mensajes de correo electrónico mediante Azure Communication Services. También puede que desee consultar:
- Obtenga más información sobre los conceptos de correo electrónico.
- Familiarizarse con la biblioteca cliente de correo electrónico.
- Obtenga más información sobre cómo enviar un mensaje de chat desde Power Automate mediante Azure Communication Services.
- Para obtener más información sobre los tokens de acceso, consulte Crear y administrar tokens de acceso y usuarios de Azure Communication Services.