Sdílet prostřednictvím

Rychlý start: Jak odeslat e-mail pomocí Azure Communication Services

  • Článek

Poznámka:

Podělte se s námi o své nápady a zpětnou vazbu o službě Azure Communication Services tím, že si probereme tento krátký průzkum.

Tento rychlý start popisuje, jak odesílat e-maily pomocí našich e-mailových sad SDK.

Začněte se službou Azure Communication Services pomocí služby Communication Services Try Email k odesílání e-mailových zpráv.

Požadavky

Dokončením tohoto rychlého startu se v účtu Azure účtují malé náklady na pár centů nebo méně USD.

Odeslání e-mailu pomocí try Email

Vyzkoušejte e-mail, který vám pomůže začít odesílat e-maily požadovaným příjemcům pomocí služeb Azure Communication Services a také ověřit konfiguraci aplikace pro odesílání e-mailů. Pomůže vám také rychle začít s vývojem e-mailových oznámení pomocí fragmentu kódu v preferovaném jazyce.

Odeslání zprávy příjemci a zadání předmětu a textu zprávy

  1. Na stránce přehledu zřízeného prostředku služby Azure Communication Service klikněte na tlačítko Vyzkoušet e-mail na levém navigačním panelu v části E-mail .

    Snímek obrazovky s levým navigačním panelem Pro vyzkoušení e-mailu

  2. V rozevíracím seznamu vyberte jednu z ověřených domén.

    Snímek obrazovky znázorňující doménu s podrobnostmi z rozevíracího seznamu

  3. Vytvoření e-mailu k odeslání

    • Zadejte e-mailovou adresu příjemce.
    • Zadat předmět
    • Napsání textu e-mailu

    Snímek obrazovky znázorňující, jak filtrovat a vybrat jednu z ověřených e-mailových domén pro připojení

  4. Klikněte na Odeslat.

    Snímek obrazovky znázorňující jednu z ověřených e-mailových domén je teď připojená

  5. E-mail byl úspěšně odeslán.

    Snímek obrazovky znázorňující úspěšné odeslání e-mailu

  6. Teď můžete také zkopírovat ukázkový fragment kódu a odeslat e-mail, který použijete v ukázkovém projektu k odesílání oznámení.

    • Vyberte jazyk podle svého výběru.

    • Klikněte na Vložit moje připojení.

    • Klikněte na Kopírovat.

      Snímek obrazovky znázorňující fragment kódu pro odeslání e-mailu

  7. Fragment kódu e-mailu je teď připravený k použití v projektu oznámení.

Začínáme se službou Azure Communication Services pomocí rozšíření komunikace Rozhraní příkazového řádku Azure k odesílání e-mailových zpráv

Dokončením tohoto rychlého startu se v účtu Azure účtují malé náklady na pár centů nebo méně USD.

Požadavky

Kontrola požadovaných součástí

  • V terminálu nebo příkazovém okně spusťte az --version příkaz a zkontrolujte, jestli jsou nainstalované Rozhraní příkazového řádku Azure a rozšíření komunikace.
  • Pokud chcete zobrazit domény ověřené pomocí vašeho prostředku e-mailové komunikace, přihlaste se k webu Azure Portal. Vyhledejte prostředek e-mailové komunikace a v levém navigačním podokně otevřete kartu Zřizovací domény .

Nastavení

Přidání rozšíření

Pomocí příkazu přidejte rozšíření Azure Communication Services pro Azure CLI az extension .

az extension add --name communication

Přihlášení k Azure CLI

Musíte se přihlásit k Azure CLI. Můžete se přihlásit spuštěním az login příkazu z terminálu a zadat své přihlašovací údaje.

Uložení připojovací řetězec do proměnné prostředí

Proměnnou AZURE_COMMUNICATION_CONNECTION_STRING prostředí můžete nakonfigurovat tak, aby používala operace klíčů Azure CLI, aniž byste museli předávat --connection_string připojovací řetězec. Pokud chcete nakonfigurovat proměnnou prostředí, otevřete okno konzoly a na následujících kartách vyberte operační systém. Nahraďte <connectionString> skutečnými připojovací řetězec.

Poznámka:

Neukládejte připojovací řetězec jako nešifrovanou proměnnou prostředí pro produkční prostředí. To je určené jenom pro účely testování. V produkčních prostředích byste měli vygenerovat nové připojovací řetězec. Doporučujeme vám šifrovat připojovací řetězec a pravidelně je měnit.

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Po přidání proměnné prostředí možná bude nutné restartovat všechny spuštěné programy, které budou potřebovat číst tuto proměnnou prostředí, a to včetně okna konzoly. Pokud například jako editor používáte Sadu Visual Studio, restartujte sadu Visual Studio před spuštěním příkladu.

Odeslání e-mailové zprávy

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."

Proveďte tyto nahrazení v kódu:

  • Nahraďte <yourConnectionString> připojovací řetězec.
  • Nahraďte <emailalias@emaildomain.com> e-mailovou adresou, na kterou chcete poslat zprávu.
  • Nahraďte <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> adresou MailFrom vaší ověřené domény.

Výše uvedený příkaz také provede dotazování na id zprávy a vrátí stav doručení e-mailu. Stav může být jeden z následujících:

Název stavu Popis
NotStarted V tuto chvíli tento stav neodesíláme z naší služby.
Spuštěno Právě probíhá a zpracovává se operace odeslání e-mailu.
Úspěšný Operace odeslání e-mailu se dokončila bez chyby a e-mail je k doručení. Jakýkoli podrobný stav o doručení e-mailu nad rámec této fáze je možné získat prostřednictvím služby Azure Monitor nebo prostřednictvím služby Azure Event Grid. Zjistěte, jak se přihlásit k odběru e-mailových událostí.
Neúspěšný Operace odeslání e-mailu nebyla úspěšná a došlo k chybě. E-mail se neodeslal. Výsledek obsahuje objekt chyby s dalšími podrobnostmi o důvodu selhání.

Volitelné parametry

V Azure CLI jsou k dispozici následující volitelné parametry.

  • --html místo textu e-mailu html lze použít --text .

  • --importance nastaví typ důležitosti e-mailu. Známé hodnoty jsou: vysoká, normální a nízká. Výchozí hodnota je normální.

  • --to nastaví seznam příjemců e-mailu.

  • --cc nastaví e-mailové adresy pro kopírování uhlíku.

  • --bcc nastaví e-mailové adresy pro slepou kopii.

  • --reply-to nastaví e-mailovou adresu odpovědět.

  • --disable-tracking označuje, jestli by pro tuto žádost mělo být zakázáno sledování zapojení uživatelů.

  • --attachments nastaví seznam e-mailových příloh.

  • --attachment-types nastaví seznam typů příloh e-mailu ve stejném pořadí jako přílohy.

Můžete také použít seznam příjemců s --cc podobnými a --bcc podobnými --to. Musí existovat alespoň jeden příjemce nebo --to --cc --bcc.

Začněte se službou Azure Communication Services pomocí e-mailové klientské knihovny komunikačních služeb C# k odesílání e-mailových zpráv.

Tip

Přeskočením přímo na Základní odesílání e-mailů a pokročilým odesíláním e-mailů na GitHubu můžete začít s prostředím pro odesílání e-mailů pomocí Azure Communication Services.

Principy modelu objektu e-mailu

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí e-mailové knihovny e-mailových služeb Azure pro C#.

Název Popis
EmailAddress Tato třída obsahuje e-mailovou adresu a možnost zobrazovaného jména.
Připojení e-mailu Tato třída vytvoří e-mailovou přílohu přijetím jedinečného ID, řetězcem typu MIME přílohy e-mailu, binárními daty pro obsah a volitelným ID obsahu, které ji definuje jako vloženou přílohu.
EmailClient Tato třída je potřebná pro všechny funkce e-mailu. Vytvoříte instanci s připojovací řetězec a použijete ji k odesílání e-mailových zpráv.
EmailClientOptions Tuto třídu je možné přidat do instance EmailClient pro cílení na konkrétní verzi rozhraní API.
EmailContent Tato třída obsahuje předmět a text e-mailové zprávy. Musíte zadat alespoň jeden z obsahu PlainText nebo Html.
EmailCustomHeader Tato třída umožňuje přidání dvojice názvů a hodnot pro vlastní hlavičku. Důležitost e-mailu lze také zadat prostřednictvím těchto hlaviček pomocí názvu záhlaví x-priority nebo x-msmail-priority.
EmailMessage Tato třída kombinuje odesílatele, obsah a příjemce. Můžete také přidat vlastní záhlaví, přílohy a e-mailové adresy pro odpovědi.
E-mailRecipients Tato třída obsahuje seznamy objektů EmailAddress pro příjemce e-mailové zprávy, včetně volitelných seznamů pro příjemce kopie a skryté kopie.
EmailSendOperation Tato třída představuje asynchronní operaci odeslání e-mailu a je vrácena z volání rozhraní API pro odesílání e-mailů.
EmailSendResult Tato třída obsahuje výsledky operace odeslání e-mailu. Má ID operace, stav operace a objekt chyby (pokud je k dispozici).

Funkce EmailSendResult vrátí následující stav provedené e-mailové operace.

Status Popis
NotStarted V tuto chvíli tento stav neodesíláme z naší služby.
Spuštěno Právě probíhá a zpracovává se operace odeslání e-mailu.
Úspěšný Operace odeslání e-mailu se dokončila bez chyby a e-mail je k doručení. Jakýkoli podrobný stav o doručení e-mailu nad rámec této fáze je možné získat prostřednictvím služby Azure Monitor nebo prostřednictvím služby Azure Event Grid. Zjistěte, jak se přihlásit k odběru e-mailových událostí.
Neúspěšný Operace odeslání e-mailu nebyla úspěšná a došlo k chybě. E-mail se neodeslal. Výsledek obsahuje objekt chyby s dalšími podrobnostmi o důvodu selhání.

Požadavky

Dokončením tohoto rychlého startu se v účtu Azure účtují malé náklady na pár centů nebo méně USD.

Poznámka:

Můžeme také poslat e-mail z naší vlastní ověřené domény. Přidání vlastních ověřených domén do e-mailové komunikační služby

Kontrola požadovaných součástí

  • V terminálu nebo příkazovém okně spusťte dotnet příkaz a zkontrolujte, jestli je nainstalovaná klientská knihovna .NET.
  • Pokud chcete zobrazit subdomény přidružené k vašemu prostředku e-mailové komunikační služby, přihlaste se k webu Azure Portal, vyhledejte prostředek e-mailové komunikační služby a v levém navigačním podokně otevřete kartu Zřizovací domény .

Vytvoření nové aplikace jazyka C#

V okně konzoly (například cmd, PowerShell nebo Bash) pomocí dotnet new příkazu vytvořte novou konzolovou aplikaci s názvem EmailQuickstart. Tento příkaz vytvoří jednoduchý projekt "Hello World" C# s jedním zdrojovým souborem: Program.cs.

dotnet new console -o EmailQuickstart

Změňte adresář na nově vytvořenou složku aplikace a pomocí dotnet build příkazu zkompilujte aplikaci.

cd EmailQuickstart
dotnet build

Nainstalujte balíček .

V adresáři aplikace nainstalujte pomocí příkazu klientskou knihovnu e-mailových služeb Azure Communication Services pro balíček dotnet add package .NET.

dotnet add package Azure.Communication.Email

Vytvoření e-mailového klienta s ověřováním

Otevřete Program.cs a nahraďte stávající kód následujícími direktivami pro přidání using direktiv pro zahrnutí Azure.Communication.Email oboru názvů a výchozího bodu pro spuštění programu.

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)
    {

    }
  }
}

Pro ověřování e-mailového klienta je k dispozici několik různých možností:

Otevřete Program.cs v textovém editoru a nahraďte text Main metody kódem, který inicializuje EmailClient připojovací řetězec. Následující kód načte připojovací řetězec pro prostředek z proměnné prostředí s názvem COMMUNICATION_SERVICES_CONNECTION_STRING. Zjistěte, jak spravovat připojovací řetězec vašeho prostředku.

// 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);

Poznámka:

K odeslání e-mailu doporučujeme použít ruční dotazování (odeslat e-mail s asynchronním dotazováním stavu).

Základní odesílání e-mailů

Vytvoření e-mailové zprávy

Pokud chcete poslat e-mailovou zprávu, musíte:

  • Definujte předmět a text e-mailu.
  • Definujte adresu odesílatele. Vytvořte e-mailovou zprávu s informacemi odesílatele, které získáte z vaší ověřené domény adresu MailFrom.
  • Definujte adresu příjemce.
  • Volejte metodu SendAsync. Přidejte tento kód na konec Main metody v Program.cs:

Nahraďte podrobnosti o vaší doméně a podle potřeby upravte obsah, podrobnosti o příjemci.


//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";

Odeslání a získání stavu odeslání e-mailu

Když zavoláte SendAsync s Azure.WaitUntil.Started, vaše metoda se vrátí zpět po spuštění operace. Metoda vrátí EmailSendOperation objekt. K aktualizaci stavu e-mailové operace můžete volat metodu UpdateStatusAsync.

Vrácený Objekt EmailSendOperation obsahuje Objekt EmailSendStatus, který obsahuje:

  • Aktuální stav operace Odeslání e-mailu
  • Objekt chyby s podrobnostmi o selhání, pokud je aktuální stav ve stavu selhání.

/// 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}");

Spusťte aplikaci z adresáře aplikace pomocí dotnet run příkazu.

dotnet run

Ukázkový kód

Ukázkovou aplikaci si můžete stáhnout z GitHubu.

Začněte se službou Azure Communication Services pomocí e-mailové knihovny JS komunikačních služeb k odesílání e-mailových zpráv.

Tip

Přeskočením přímo na Základní odesílání e-mailů a pokročilým odesíláním e-mailů na GitHubu můžete začít s prostředím pro odesílání e-mailů pomocí Azure Communication Services.

Principy e-mailového objektového modelu

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí e-mailové knihovny e-mailových služeb Azure pro JavaScript.

Název Popis
EmailAddress Tato třída obsahuje e-mailovou adresu a možnost zobrazovaného jména.
Připojení e-mailu Tato třída vytvoří e-mailovou přílohu přijetím jedinečného ID, řetězcem typu MIME přílohy e-mailu, binárními daty pro obsah a volitelným ID obsahu, které ji definuje jako vloženou přílohu.
EmailClient Tato třída je potřebná pro všechny funkce e-mailu. Vytvoříte instanci s připojovací řetězec a použijete ji k odesílání e-mailových zpráv.
EmailClientOptions Tuto třídu je možné přidat do instance EmailClient pro cílení na konkrétní verzi rozhraní API.
EmailContent Tato třída obsahuje předmět a text e-mailové zprávy. Musíte zadat alespoň jeden obsah PlainText nebo Html.
EmailCustomHeader Tato třída umožňuje přidání dvojice názvů a hodnot pro vlastní hlavičku. Důležitost e-mailu lze také zadat prostřednictvím těchto hlaviček pomocí názvu záhlaví x-priority nebo x-msmail-priority.
EmailMessage Tato třída kombinuje odesílatele, obsah a příjemce. Můžete také přidat vlastní záhlaví, přílohy a e-mailové adresy pro odpovědi.
E-mailRecipients Tato třída obsahuje seznamy objektů EmailAddress pro příjemce e-mailové zprávy, včetně volitelných seznamů pro příjemce kopie a skryté kopie.
EmailSendResult Tato třída obsahuje výsledky operace odeslání e-mailu. Má ID operace, stav operace a objekt chyby (pokud je k dispozici).
EmailSendStatus Tato třída představuje sadu stavů operace odeslání e-mailu.

Funkce EmailSendResult vrátí následující stav provedené e-mailové operace.

Název stavu Popis
isStarted Vrátí hodnotu true, pokud právě probíhá operace odeslání e-mailu a zpracovává se.
isCompleted Vrátí hodnotu true, pokud se operace odeslání e-mailu dokončila bez chyby a e-mail je mimo doručení. Jakýkoli podrobný stav o doručení e-mailu nad rámec této fáze je možné získat prostřednictvím služby Azure Monitor nebo prostřednictvím služby Azure Event Grid. Zjistěte, jak se přihlásit k odběru e-mailových událostí.
result Vlastnost, která existuje, pokud operace odeslání e-mailu skončila.
chyba Vlastnost, která existuje, pokud operace odeslání e-mailu nebyla úspěšná a došlo k chybě. E-mail se neodeslal. Výsledek obsahuje objekt chyby s dalšími podrobnostmi o důvodu selhání.

Požadavky

Dokončením tohoto rychlého startu se v účtu Azure účtují malé náklady na pár centů nebo méně USD.

Poznámka:

Můžeme také poslat e-mail z naší vlastní ověřené domény. Přidání vlastních ověřených domén do e-mailové komunikační služby

Kontrola požadovaných součástí

  • V terminálu nebo příkazovém okně spusťte kontrolu node --version , jestli je nainstalovaná Node.js.
  • Pokud chcete zobrazit domény ověřené prostředkem e-mailové komunikační služby, přihlaste se k webu Azure Portal, vyhledejte prostředek e-mailové komunikační služby a v levém navigačním podokně otevřete kartu Zřizovat domény .

Nastavení aplikačního prostředí

Vytvoření nové aplikace Node.js

Nejprve otevřete terminál nebo příkazové okno, vytvořte pro aplikaci nový adresář a přejděte na něj.

mkdir email-quickstart && cd email-quickstart

Spuštěním příkazu npm init -y vytvořte soubor package.json s výchozím nastavením.

npm init -y

Pomocí textového editoru vytvořte soubor s názvem send-email.js v kořenovém adresáři projektu. Změňte vlastnost main v package.json na send-email.js. Následující část ukazuje, jak přidat zdrojový kód pro tento rychlý start do nově vytvořeného souboru.

Nainstalujte balíček .

npm install Pomocí příkazu nainstalujte klientskou knihovnu e-mailových služeb Azure Communication Services pro JavaScript.

npm install @azure/communication-email --save

Tato --save možnost vypíše knihovnu jako závislost v souboru package.json .

Vytvoření e-mailového klienta s ověřováním

Pro ověřování e-mailového klienta je k dispozici několik různých možností:

Naimportujte e-mailový klient z klientské knihovny a vytvořte instanci pomocí svého připojovací řetězec.

Následující kód načte připojovací řetězec prostředku z proměnné prostředí pojmenované COMMUNICATION_SERVICES_CONNECTION_STRING pomocí balíčku dotenv. npm install Pomocí příkazu nainstalujte balíček dotenv. Zjistěte, jak spravovat připojovací řetězec vašeho prostředku.

npm install dotenv

Do send-email.js přidejte následující kód:

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);

Pro zjednodušení tento rychlý start používá připojovací řetězec, ale v produkčních prostředích doporučujeme používat instanční objekty.

Základní odesílání e-mailů

Odeslání e-mailové zprávy

Pokud chcete odeslat e-mailovou beginSend zprávu, zavolejte funkci z EmailClient. Tato metoda vrátí poller, který zkontroluje stav operace a po dokončení načte výsledek.


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();

Proveďte tyto nahrazení v kódu:

  • Nahraďte <emailalias@emaildomain.com> e-mailovou adresou, na kterou chcete poslat zprávu.
  • Nahraďte <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> adresou MailFrom vaší ověřené domény.

Spuštění kódu

pomocí příkazu node spusťte kód, který jste přidali do souboru send-email.js.

node ./send-email.js

Ukázkový kód

Ukázkovou aplikaci si můžete stáhnout z GitHubu.

Začínáme se službou Azure Communication Services pomocí e-mailové sady SDK pro komunikační služby Java k odesílání e-mailových zpráv

Tip

Přeskočením přímo na Základní odesílání e-mailů a pokročilým odesíláním e-mailů na GitHubu můžete začít s prostředím pro odesílání e-mailů pomocí Azure Communication Services.

Principy e-mailového objektového modelu

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí e-mailové sady SDK služby Azure Communication Services pro Python.

Název Popis
EmailAddress Tato třída obsahuje e-mailovou adresu a možnost zobrazovaného jména.
Připojení e-mailu Toto rozhraní vytvoří e-mailovou přílohu tím, že přijme jedinečné ID, řetězec typu MIME přílohy e-mailu, řetězec bajtů obsahu a volitelné ID obsahu, které ji definuje jako vloženou přílohu.
EmailClient Tato třída je potřebná pro všechny funkce e-mailu. Vytvoříte instanci s připojovací řetězec a použijete ji k odesílání e-mailových zpráv.
EmailMessage Tato třída kombinuje odesílatele, obsah a příjemce. Můžete také přidat vlastní záhlaví, přílohy a e-mailové adresy pro odpovědi.
EmailSendResult Tato třída obsahuje výsledky operace odeslání e-mailu. Má ID operace, stav operace a objekt chyby (pokud je k dispozici).
EmailSendStatus Tato třída představuje sadu stavů operace odeslání e-mailu.

Funkce EmailSendResult vrátí následující stav provedené e-mailové operace.

Název stavu Popis
NOT_STARTED V tuto chvíli tento stav neodesíláme z naší služby.
IN_PROGRESS Právě probíhá a zpracovává se operace odeslání e-mailu.
SUCCESSFULLY_COMPLETED Operace odeslání e-mailu se dokončila bez chyby a e-mail je k doručení. Jakýkoli podrobný stav o doručení e-mailu nad rámec této fáze je možné získat prostřednictvím služby Azure Monitor nebo prostřednictvím služby Azure Event Grid. Zjistěte, jak se přihlásit k odběru e-mailových událostí.
CHYBA Operace odeslání e-mailu nebyla úspěšná a došlo k chybě. E-mail se neodeslal. Výsledek obsahuje objekt chyby s dalšími podrobnostmi o důvodu selhání.

Požadavky

Při dokončení tohoto rychlého zprovoznění vzniknou ve vašem účtu Azure náklady ve výši několika centů USD (nebo menší).

Poznámka:

Můžeme také odeslat e-mail z naší vlastní ověřené domény Přidat vlastní ověřené domény do e-mailové komunikační služby.

Kontrola požadovaných součástí

  • V terminálu nebo příkazovém okně spusťte kontrolu mvn -v , jestli je maven nainstalovaný.
  • Pokud chcete zobrazit domény ověřené pomocí vašeho prostředku e-mailové komunikace, přihlaste se k webu Azure Portal. Vyhledejte prostředek e-mailové komunikace a v levém navigačním podokně otevřete kartu Zřizovací domény .

Nastavení aplikačního prostředí

Pokud chcete nastavit prostředí pro odesílání e-mailů, postupujte podle kroků v následujících částech.

Vytvoření nové aplikace v Javě

Otevřete terminál nebo příkazové okno a přejděte do adresáře, do kterého chcete vytvořit aplikaci v Javě. Spuštěním následujícího příkazu vygenerujte projekt Java ze šablony 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"

Cíl generate vytvoří adresář se stejným názvem jako artifactId hodnota. V tomto adresáři obsahuje adresář src/main/java zdrojový kód projektu, adresář src/test/java obsahuje zdroj testů a soubor pom.xml je projektový objektový model (POM).

Nainstalujte balíček .

Otevřete soubor pom.xml v textovém editoru. Do skupiny závislostí přidejte následující prvek závislosti.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-email</artifactId>
    <version>1.0.0-beta.2</version>
</dependency>

Nastavení architektury aplikace

Otevřete /src/main/java/com/communication/quickstart/App.java v textovém editoru, přidejte direktivy importu System.out.println("Hello world!"); a odeberte příkaz:

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.
    }
}

Vytvoření e-mailového klienta s ověřováním

Pro ověřování e-mailového klienta je k dispozici několik různých možností.

Pokud chcete ověřit klienta, vytvořte instanci EmailClient s připojovací řetězec. Zjistěte, jak spravovat připojovací řetězec vašeho prostředku. Klienta můžete také inicializovat pomocí libovolného vlastního klienta HTTP, který implementuje com.azure.core.http.HttpClient rozhraní.

Pokud chcete vytvořit instanci synchronního klienta, přidejte do main metody následující kód:

// 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();

Pokud chcete vytvořit instanci asynchronního klienta, přidejte do main metody následující kód:

// 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();

Pro zjednodušení tento rychlý start používá připojovací řetězec, ale v produkčních prostředích doporučujeme používat instanční objekty.

Základní odesílání e-mailů

E-mailovou zprávu lze vytvořit pomocí objektu EmailMessage v sadě 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.");

Proveďte tyto nahrazení v kódu:

  • Nahraďte <emailalias@emaildomain.com> e-mailovou adresou, na kterou chcete poslat zprávu.
  • Nahraďte <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> adresou MailFrom vaší ověřené domény.

Chcete-li odeslat e-mailovou beginSend zprávu, zavolejte funkci z funkce EmailClient.

Volání beginSend synchronizačního klienta vrátí SyncPoller objekt, který se dá použít ke kontrole stavu operace a načtení výsledku po dokončení operace. Všimněte si, že počáteční požadavek na odeslání e-mailu se odešle hned po beginSend zavolání metody. Odeslání e-mailu je dlouhotrvající operace. Je důležité poznamenat, že getFinalResult() metoda na poller je blokující operace, dokud se nedosáhl stav terminálu (SUCCESSFULLY_COMPLETED nebo FAILED). Doporučenou metodou je provést ruční dotazování v intervalu, který je vhodný pro potřeby vaší aplikace, jak je znázorněno v ukázce níže.

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();
        System.out.println("Email send poller status: " + pollResponse.getStatus());

        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());
}

Spuštění kódu

  1. Přejděte do adresáře, který obsahuje soubor pom.xml , a pomocí příkazu zkompilujte projekt mvn .

    mvn compile

  2. Sestavte balíček.

    mvn package

  3. Spuštěním následujícího mvn příkazu spusťte aplikaci.

    mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"

Ukázkový kód

Ukázkovou aplikaci si můžete stáhnout z GitHubu.

Začněte se službou Azure Communication Services pomocí e-mailové sady SDK pro komunikační služby Python k odesílání e-mailových zpráv.

Tip

Přeskočením přímo na Základní odesílání e-mailů a pokročilým odesíláním e-mailů na GitHubu můžete začít s prostředím pro odesílání e-mailů pomocí Azure Communication Services.

Principy e-mailového objektového modelu

Následující objekt šablony zpráv JSON a odpovědi předvádí některé z hlavních funkcí e-mailové sady SDK služby Azure Communication Services pro 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.
    }
}

Hodnoty response.status jsou vysvětleny dále v následující tabulce.

Název stavu Popis
Probíhající Právě probíhá a zpracovává se operace odeslání e-mailu.
Úspěšný Operace odeslání e-mailu se dokončila bez chyby a e-mail je k doručení. Jakýkoli podrobný stav o doručení e-mailu nad rámec této fáze je možné získat prostřednictvím služby Azure Monitor nebo prostřednictvím služby Azure Event Grid. Zjistěte, jak se přihlásit k odběru e-mailových událostí.
Neúspěšný Operace odeslání e-mailu nebyla úspěšná a došlo k chybě. E-mail se neodeslal. Výsledek obsahuje objekt chyby s dalšími podrobnostmi o důvodu selhání.

Požadavky

Dokončením tohoto rychlého startu se v účtu Azure účtují malé náklady na pár centů nebo méně USD.

Poznámka:

Můžeme také poslat e-mail z naší vlastní ověřené domény. Přidání vlastních ověřených domén do e-mailové komunikační služby

Kontrola požadovaných součástí

  • V terminálu nebo příkazovém okně spusťte python --version příkaz a zkontrolujte, jestli je Python nainstalovaný.
  • Pokud chcete zobrazit domény ověřené pomocí vašeho prostředku e-mailové komunikace, přihlaste se k webu Azure Portal. Vyhledejte prostředek e-mailové komunikace a v levém navigačním podokně otevřete kartu Zřizovací domény .

Nastavení aplikačního prostředí

Pokud chcete nastavit prostředí pro odesílání e-mailů, postupujte podle kroků v následujících částech.

Vytvoření nové aplikace v Pythonu

  1. Otevřete terminál nebo příkazové okno. Pak pomocí následujícího příkazu vytvořte virtuální prostředí a aktivujte ho. Tento příkaz vytvoří pro vaši aplikaci nový adresář.

    python -m venv email-quickstart

  2. Přejděte do kořenového adresáře virtuálního prostředí a aktivujte ho pomocí následujících příkazů.

    cd email-quickstart
.\Scripts\activate

  3. Pomocí textového editoru vytvořte soubor s názvem send-email.py v kořenovém adresáři projektu a přidejte strukturu programu, včetně základního zpracování výjimek.

    import os
from azure.communication.email import EmailClient

try:
    # Quickstart code goes here.
except Exception as ex:
    print('Exception:')
    print(ex)

V následujících částech přidáte veškerý zdrojový kód pro tento rychlý start do send-email.py souboru, který jste vytvořili.

Nainstalujte balíček .

V adresáři aplikace nainstalujte sadu SDK e-mailu služby Azure Communication Services pro Python pomocí následujícího příkazu.

pip install azure-communication-email

Vytvoření e-mailového klienta s ověřováním

Pro ověřování e-mailového klienta je k dispozici několik různých možností:

Vytvořte instanci e-mailového klienta pomocí svého připojovací řetězec. Zjistěte, jak spravovat připojovací řetězec vašeho prostředku.

# Create the EmailClient object that you use to send Email messages.
email_client = EmailClient.from_connection_string(<connection_string>)

Pro zjednodušení tento rychlý start používá připojovací řetězec, ale v produkčních prostředích doporučujeme používat instanční objekty.

Základní odesílání e-mailů

Odeslání e-mailové zprávy

Pokud chcete poslat e-mailovou zprávu, musíte:

  • Vytvořte zprávu s následujícími hodnotami:
    • senderAddress: Platná e-mailová adresa odesílatele, která se nachází v poli MailFrom v podokně přehledu domény propojené s prostředkem e-mailové komunikační služby.
    • recipients: Objekt se seznamem příjemců e-mailu a volitelně i seznamy příjemců e-mailu CC &BCC.
    • content: Objekt obsahující předmět a volitelně i prostý text nebo obsah HTML e-mailové zprávy.
  • Volání begin_send metoda, která vrátí výsledek operace.
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())

Proveďte tyto nahrazení v kódu:

  • Nahraďte <emailalias@emaildomain.com> e-mailovou adresou, na kterou chcete poslat zprávu.
  • Nahraďte <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> adresou MailFrom vaší ověřené domény.

Získání stavu doručení e-mailu

Můžeme se dotazovat na stav doručení e-mailu tak, že nastavíme smyčku u objektu stavu operace vráceného z metody EmailClient begin_send :

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)

Spuštění kódu

Spusťte aplikaci z adresáře aplikace pomocí python příkazu.

python send-email.py

Ukázkový kód

Ukázkovou aplikaci si můžete stáhnout z GitHubu.

Požadavky

  • Účet Azure s aktivním předplatným nebo si zdarma vytvořte účet Azure.

  • Aktivní prostředek služby Azure Communication Services nebo vytvořte prostředek služby Communication Services.

  • Aktivní prostředek Azure Logic Apps (aplikace logiky) a pracovní postup nebo vytvořte nový prostředek a pracovní postup aplikace logiky s triggerem, který chcete použít. E-mailový konektor Azure Communication Services v současné době poskytuje jenom akce, takže pracovní postup aplikace logiky vyžaduje minimálně aktivační událost. Můžete vytvořit prostředek aplikace logiky Consumption nebo Standard .

  • Prostředek e-mailu služby Azure Communication Services s nakonfigurovanou doménou nebo vlastní doménou.

  • Prostředek Azure Communication Services připojený k e-mailové doméně Azure.

Odeslat e-mail

Pokud chcete do pracovního postupu přidat nový krok pomocí e-mailového konektoru služby Azure Communication Services, postupujte takto:

  1. V návrháři otevřete pracovní postup aplikace logiky.

    Využití

    1. Pod krokem, do kterého chcete přidat novou akci, vyberte Nový krok. Pokud chcete přidat novou akci mezi kroky, přesuňte ukazatel myši na šipku mezi těmito kroky, vyberte znaménko plus (+) a vyberte Přidat akci.

    2. V části Zvolit vyhledávací pole operace vyberte Premium. Do vyhledávacího pole zadejte Komunikační e-mail Azure.

    3. V seznamu akcí vyberte Odeslat e-mail.

      Snímek obrazovky znázorňující akci Odeslání e-mailu pomocí e-mailového konektoru služby Azure Communication Services

    Standard

    1. V kroku, do kterého chcete přidat novou akci, vyberte znaménko plus (+). Pokud chcete přidat novou akci mezi kroky, přesuňte ukazatel myši na šipku mezi těmito kroky, vyberte znaménko plus (+) a vyberte Přidat akci.

    2. Pod vyhledávacím polem Přidat akci vyberte v rozevíracím seznamu modulu runtime Premium . Do vyhledávacího pole zadejte Komunikační e-mail Azure.

    3. V seznamu akcí vyberte Odeslat e-mail.

  2. Zadejte název připojení.

  3. Zadejte připojovací řetězec prostředku služby Azure Communications Service. Chcete-li najít tento řetězec, postupujte takto:

    1. Na webu Azure Portal otevřete prostředek služby Azure Communication Service.

    2. V nabídce prostředků v části Nastavení vyberte Klíče a zkopírujte připojovací řetězec.

      Snímek obrazovky znázorňující připojovací řetězec služby Azure Communication Services

  4. Až budete hotovi, vyberte Vytvořit.

  5. V poli Od použijte e-mailovou adresu, kterou jste nakonfigurovali v požadavcích. Zadejte hodnoty polí Do e-mailu, Předmět a Text , například:

    Snímek obrazovky znázorňující vstup e-mailové akce e-mailového konektoru e-mailových služeb Azure Communication Services

  6. Uložte pracovní postup. Na panelu nástrojů návrháře vyberte Uložit.

Otestování pracovního postupu

Na základě toho, jestli máte pracovní postup Consumption nebo Standard, spusťte pracovní postup ručně:

  • Spotřeba: Na panelu nástrojů návrháře vyberte Spustit spuštění triggeru>.
  • Standardní: V nabídce pracovního postupu vyberte Přehled. Na panelu nástrojů vyberte Spustit spuštění aktivační události>.

Pracovní postup vytvoří uživatele, vydá přístupový token pro daného uživatele a pak uživatele odebere a odstraní. Po úspěšném spuštění pracovního postupu můžete zkontrolovat výstupy těchto akcí.

Měli byste dostat e-mail na zadanou adresu. Pomocí akce Získat stav e-mailové zprávy můžete také zkontrolovat stav e-mailů odeslaných prostřednictvím akce Odeslat e-mail. Další akce najdete v referenční dokumentaci k e-mailovému konektoru služby Azure Communication Services.

Vyčištění prostředků pracovního postupu

Pokud chcete vyčistit prostředky aplikace logiky, pracovní postup a související prostředky, přečtěte si , jak vyčistit prostředky aplikace logiky Consumption nebo jak vyčistit prostředky standardní aplikace logiky.

Řešení problému

Doručování e-mailů

Pokud chcete vyřešit problémy související s doručováním e-mailů, můžete získat stav doručení e-mailu a zaznamenat podrobnosti o doručení.

Důležité

Výsledek úspěchu vrácený dotazem na stav operace odeslání ověří pouze skutečnost, že se e-mail úspěšně odeslal k doručení. Pokud chcete získat další informace o stavu doručení na konci příjemce, budete muset odkazovat na zpracování e-mailových událostí.

Omezení e-mailu

Pokud zjistíte, že aplikace je zablokovaná, může to být kvůli omezování odesílání e-mailů. Můžete to zpracovat prostřednictvím protokolování nebo implementací vlastních zásad.

Poznámka:

Toto nastavení sandboxu pomáhá vývojářům začít vytvářet aplikaci. Jakmile je aplikace připravená k živému provozu, můžete postupně požádat o zvýšení odesílajícího svazku. Odešlete žádost o podporu pro zvýšení požadovaného limitu odesílání, pokud požadujete odeslání objemu zpráv překračujících limity rychlosti.

Vyčištění prostředků služby Azure Communication Service

Pokud chcete vyčistit a odebrat předplatné komunikačních služeb, můžete odstranit prostředek nebo skupinu prostředků. Odstraněním skupiny prostředků se odstraní také všechny ostatní přidružené prostředky. Přečtěte si další informace o čištění prostředků.

Další kroky

V tomto rychlém startu jste zjistili, jak odesílat e-maily pomocí služeb Azure Communication Services. Můžete také chtít: