Quickstart: Een e-mailbericht verzenden met behulp van Azure Communication Services

  • Artikel

Notitie

Deel uw ideeën en feedback over Azure Communication Services met ons door deze korte enquête te nemen.

In deze quickstart wordt beschreven hoe u e-mail verzendt met behulp van onze E-mail-SDK's.

Ga aan de slag met Azure Communication Services met behulp van de Communication Services Try Email om e-mailberichten te verzenden.

Vereisten

Voor het voltooien van deze quickstart worden kleine kosten in rekening gebracht van een paar dollarcenten of minder in uw Azure-account.

Een e-mailbericht verzenden met e-mail uitproberen

Met e-mail kunt u e-mailberichten snel verzenden naar de gewenste geadresseerden met behulp van Azure Communication Services, en de configuratie controleren voor uw toepassing om e-mail te verzenden. Het helpt ook om snel aan de slag te gaan met de ontwikkeling van uw e-mailmeldingen met het codefragment in de gewenste taal.

Een bericht verzenden naar een geadresseerde en het onderwerp en de hoofdtekst van het bericht opgeven

  1. Klik op de overzichtspagina van een ingerichte Azure Communication Service-resource op E-mail proberen in het linkernavigatievenster onder E-mail.

    Schermopname van het linkernavigatievenster voor E-mail uitproberen.

  2. Selecteer een van de geverifieerde domeinen in de vervolgkeuzelijst.

    Schermopname van het verifieerbare domein in de vervolgkeuzelijst.

  3. Het e-mailbericht opstellen dat moet worden verzonden

    • E-mailadres van geadresseerde invoeren
    • Onderwerp invoeren
    • De hoofdtekst van de e-mail schrijven

    Schermopname die laat zien hoe u een van de geverifieerde e-maildomeinen filtert en selecteert om verbinding te maken.

  4. Klik op Verzenden

    Schermopname van een van de geverifieerde e-maildomeinen is nu verbonden.

  5. E-mail verzonden.

    Schermopname van geslaagde e-mail verzenden.

  6. U kunt nu ook het voorbeeldcodefragment kopiëren om een e-mailbericht te verzenden dat u in uw voorbeeldproject kunt gebruiken om meldingen te verzenden.

    • Taal van uw keuze selecteren

    • Klik op Mijn Verbinding maken invoegen

    • Klik op Kopiëren

      Schermopname van het codefragment voor het verzenden van e-mail.

  7. E-mailcodefragment is nu klaar voor gebruik in uw meldingsproject.

Ga aan de slag met Azure Communication Services met behulp van de Azure CLI-communicatie-extensie om e-mailberichten te verzenden.

Voor het voltooien van deze quickstart worden kleine kosten in rekening gebracht van een paar dollarcenten of minder in uw Azure-account.

Vereisten

Controle van vereisten

  • Voer in een terminal- of opdrachtvenster de az --version opdracht uit om te controleren of Azure CLI en de communicatie-extensie zijn geïnstalleerd.
  • Meld u aan bij Azure Portal om de domeinen weer te geven die zijn geverifieerd met uw E-mail Communication Services-resource. Zoek uw E-mail Communication Services-resource en open het tabblad Domeinen inrichten vanuit het linkernavigatiedeelvenster.

Instellen

De extensie toevoegen

Voeg de Azure Communication Services-extensie voor Azure CLI toe met behulp van de az extension opdracht.

az extension add --name communication

Aanmelden bij Azure CLI

U moet zich aanmelden bij Azure CLI. U kunt zich aanmelden bij het uitvoeren van de az login opdracht vanuit de terminal en uw referenties opgeven.

De verbindingsreeks naar een omgevingsvariabele schrijven

U kunt de AZURE_COMMUNICATION_CONNECTION_STRING omgevingsvariabele configureren voor het gebruik van Bewerkingen van Azure CLI-sleutels zonder dat u de verbindingsreeks hoeft door te --connection_string geven. Als u een omgevingsvariabele wilt configureren, opent u een consolevenster en selecteert u het besturingssysteem op de onderstaande tabbladen. Vervang <connectionString> door de feitelijke verbindingsreeks.

Notitie

Sla uw verbindingsreeks niet op als een niet-versleutelde omgevingsvariabele voor productieomgevingen. Dit is alleen bedoeld voor testdoeleinden. Voor productieomgevingen moet u nieuwe verbindingsreeks genereren. We raden u aan om verbindingsreeks s te versleutelen en deze regelmatig te wijzigen.

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Nadat u de omgevingsvariabele hebt toegevoegd, moet u actieve programma's die de omgevingsvariabele moeten lezen, opnieuw starten. Start ook het consolevenster opnieuw. Als u Visual Studio bijvoorbeeld gebruikt als editor, start u Visual Studio opnieuw voordat u het voorbeeld uitvoert.

Een e-mailbericht verzenden

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

Voer de volgende vervangingen uit in de code:

  • Vervang <yourConnectionString> door uw verbindingsreeks.
  • Vervang <emailalias@emaildomain.com> door het e-mailadres waarnaar u een bericht wilt verzenden.
  • Vervang door <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> het MailFrom-adres van uw geverifieerde domein.

De bovenstaande opdracht voert ook een polling uit op de messageId en retourneert de status van de e-mailbezorging. De status kan een van de volgende zijn:

Statusnaam Beschrijving
NotStarted Deze status wordt momenteel niet verzonden vanuit onze service.
Wordt uitgevoerd De verzendbewerking voor e-mail wordt momenteel uitgevoerd en verwerkt.
Geslaagd De verzendbewerking voor e-mail is zonder fouten voltooid en het e-mailbericht is niet bezorgd. Elke gedetailleerde status van de e-mailbezorging buiten deze fase kan worden verkregen via Azure Monitor of via Azure Event Grid. Meer informatie over het abonneren op e-mailevenementen
Mislukt De verzendbewerking voor e-mail is mislukt en er is een fout opgetreden. Het e-mailbericht is niet verzonden. Het resultaat bevat een foutobject met meer informatie over de reden voor de fout.

Optionele parameters

De volgende optionele parameters zijn beschikbaar in Azure CLI.

  • --html kan worden gebruikt in plaats van voor de hoofdtekst van --text html-e-mail.

  • --importance stelt het urgentietype voor het e-mailbericht in. Bekende waarden zijn: hoog, normaal en laag. De standaardwaarde is normaal.

  • --to stelt de lijst met e-mailontvangers in.

  • --cc stelt e-mailadressen voor carbon copy in.

  • --bcc stelt e-mailadressen voor blind carbon copy in.

  • --reply-to hiermee stelt u het e-mailadres voor beantwoorden in.

  • --disable-tracking geeft aan of tracering van gebruikersbetrokkenheid moet worden uitgeschakeld voor deze aanvraag.

  • --attachments stelt de lijst met e-mailbijlagen in.

  • --attachment-types stelt de lijst met typen e-mailbijlagen in dezelfde volgorde van bijlagen in.

U kunt ook een lijst met geadresseerden met en --bcc vergelijkbaar met .--cc--to Er moet ten minste één geadresseerde zijn in --to of--cc.--bcc

Ga aan de slag met Azure Communication Services met behulp van de Clientbibliotheek voor C#-e-mail van Communication Services om e-mailberichten te verzenden.

Tip

Start uw e-mailverzendingservaring met Azure Communication Services door rechtstreeks over te slaan naar de voorbeeldcode Basic Email Verzenden en Geavanceerd e-mail verzenden op GitHub.

Informatie over het e-mailobjectmodel

De volgende klassen en interfaces verwerken enkele van de belangrijkste functies van de E-mailclientbibliotheek van Azure Communication Services voor C#.

Name Beschrijving
EmailAddress Deze klasse bevat een e-mailadres en een optie voor een weergavenaam.
E-mailbijlage Met deze klasse wordt een e-mailbijlage gemaakt door een unieke id, mime-type tekenreeks voor e-mailbijlagen en binaire gegevens voor inhoud te accepteren.
EmailClient Deze klasse is nodig voor alle e-mailfunctionaliteit. U maakt een instantie met uw verbindingsreeks en gebruikt deze om e-mailberichten te verzenden.
EmailClientOptions Deze klasse kan worden toegevoegd aan de instantie van EmailClient om een specifieke API-versie te targeten.
EmailContent Deze klasse bevat het onderwerp en de hoofdtekst van het e-mailbericht. U moet ten minste één van plaintext- of HTML-inhoud opgeven
EmailCustomHeader Met deze klasse kunt u een naam- en waardepaar toevoegen voor een aangepaste header. Het belang van e-mail kan ook worden opgegeven via deze headers met behulp van de headernaam 'x-priority' of 'x-msmail-priority'
EmailMessage Deze klasse combineert de afzender, inhoud en geadresseerden. Aangepaste kopteksten, bijlagen en e-mailadressen voor antwoorden kunnen ook worden toegevoegd.
EmailRecipients Deze klasse bevat lijsten met EmailAddress-objecten voor geadresseerden van het e-mailbericht, inclusief optionele lijsten voor CC & BCC-geadresseerden.
EmailSendOperation Deze klasse vertegenwoordigt de asynchrone verzendbewerking voor e-mail en wordt geretourneerd vanuit de API-aanroep voor e-mail verzenden.
EmailSendResult Deze klasse bevat de resultaten van de verzendbewerking voor e-mail. Het heeft een bewerkings-id, de bewerkingsstatus en het foutobject (indien van toepassing).

EmailSendResult retourneert de volgende status van de e-mailbewerking die is uitgevoerd.

-Status Beschrijving
NotStarted Deze status wordt momenteel niet verzonden vanuit onze service.
Wordt uitgevoerd De verzendbewerking voor e-mail wordt momenteel uitgevoerd en verwerkt.
Geslaagd De verzendbewerking voor e-mail is zonder fouten voltooid en het e-mailbericht is niet bezorgd. Elke gedetailleerde status van de e-mailbezorging buiten deze fase kan worden verkregen via Azure Monitor of via Azure Event Grid. Meer informatie over het abonneren op e-mailevenementen
Mislukt De verzendbewerking voor e-mail is mislukt en er is een fout opgetreden. Het e-mailbericht is niet verzonden. Het resultaat bevat een foutobject met meer informatie over de reden voor de fout.

Vereisten

Voor het voltooien van deze quickstart worden kleine kosten in rekening gebracht van een paar dollarcenten of minder in uw Azure-account.

Notitie

We kunnen ook een e-mail verzenden vanuit ons eigen geverifieerde domein. Aangepaste geverifieerde domeinen toevoegen aan e-mailcommunicatieservice.

Controle van vereisten

  • Voer in een terminal- of opdrachtvenster de opdracht dotnet uit om te controleren of de .NET-clientbibliotheek is geïnstalleerd.
  • Als u de subdomeinen wilt weergeven die zijn gekoppeld aan uw Resource voor e-mailcommunicatieservices, meldt u zich aan bij Azure Portal, zoekt u uw Resource voor e-mailcommunicatieservices en opent u het tabblad Domeinen inrichten in het linkernavigatiedeelvenster.

Een nieuwe C#-toepassing maken

Gebruik in een consolevenster (zoals cmd, PowerShell of Bash) de opdracht dotnet new om een nieuwe console-app te maken met de naam EmailQuickstart. Met deze opdracht maakt u een eenvoudig C#-project Hallo wereld met één bronbestand: Program.cs.

dotnet new console -o EmailQuickstart

Wijzig uw map in de zojuist gemaakte app-map en gebruik de opdracht dotnet build om uw toepassing te compileren.

cd EmailQuickstart
dotnet build

Het pakket installeren

Terwijl u zich nog in de toepassingsmap bevindt, installeert u de e-mailclientbibliotheek van Azure Communication Services voor .NET-pakket met behulp van de dotnet add package opdracht.

dotnet add package Azure.Communication.Email

De e-mailclient maken met verificatie

Open Program.cs en vervang de bestaande code door het volgende om instructies toe te voegen voor het toevoegen using van de Azure.Communication.Email naamruimte en een beginpunt voor uitvoering voor uw programma.

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

    }
  }
}

Er zijn enkele verschillende opties beschikbaar voor het verifiëren van een e-mailclient:

Open Program.cs in een teksteditor en vervang de hoofdtekst van de Main-methode door code om een EmailClient te initialiseren met uw verbindingsreeks. Met de volgende code wordt de verbindingsreeks voor de resource opgehaald uit een omgevingsvariabele met de naam COMMUNICATION_SERVICES_CONNECTION_STRING. Meer informatie over het beheren van de verbindingsreeks van uw resource.

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

Standaard-e-mail verzenden

Uw e-mailbericht samenstellen

Als u een e-mailbericht wilt verzenden, moet u het volgende doen:

  • Definieer het onderwerp en de hoofdtekst van het e-mailbericht.
  • Definieer uw Adres van verzender. Stel uw e-mailbericht samen met uw afzendergegevens en haal uw MailFrom-adres op uit uw geverifieerde domein.
  • Definieer het adres van de geadresseerde.
  • Roep de sendAsync-methode aan. Voeg deze code toe aan het einde van de Main-methode in Program.cs:

Vervang door uw domeingegevens en wijzig de inhoud, de details van de geadresseerde naar behoefte


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

De verzendstatus van het e-mailbericht verzenden en ophalen

Als u een e-mailbericht wilt verzenden, moet u het volgende doen:

  • Roep de SendAsync-methode aan waarmee de e-mailaanvraag wordt verzonden als asynchrone bewerking. Roep aan met Azure.WaitUntil.Completed als uw methode moet wachten totdat de langdurige bewerking is voltooid op de service. Roep aan met Azure.WaitUntil.Started als uw methode moet worden geretourneerd na het starten van de bewerking.
  • De sendAsync-methode retourneert EmailSendOperation die E-mailSendStatus retourneert als e-mail is verzonden en anders een uitzondering genereert. Voeg deze code toe aan het einde van de Main-methode in Program.cs:
try
{
    Console.WriteLine("Sending email...");
    EmailSendOperation emailSendOperation = await emailClient.SendAsync(
        Azure.WaitUntil.Completed,
        sender,
        recipient,
        subject,
        htmlContent);
    EmailSendResult statusMonitor = emailSendOperation.Value;
    
    Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");

    /// 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}");
}
catch (RequestFailedException ex)
{
    /// OperationID is contained in the exception message and can be used for troubleshooting purposes
    Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}");
}

E-mailbezorgingsstatus ophalen

EmailSendOperation retourneert alleen de status van de e-mailbewerking. Als u de werkelijke e-mailbezorgingsstatus wilt ophalen, kunt u zich abonneren op de gebeurtenis 'EmailDeliveryReportReceived' die wordt gegenereerd wanneer de e-mailbezorging is voltooid. De gebeurtenis retourneert de volgende leveringsstatus:

  • Geleverd.
  • Mislukt.
  • In quarantaine geplaatst.

Zie E-mail gebeurtenissen afhandelen voor meer informatie.

U kunt zich nu ook abonneren op operationele e-maillogboeken die informatie bieden met betrekking tot metrische gegevens over bezorging voor berichten die vanuit de e-mailservice worden verzonden.

  • Operationele e-maillogboeken voor e-mail verzenden- biedt gedetailleerde informatie met betrekking tot het verzenden van e-mailaanvragen door de e-mailservice.
  • Operationele logboeken voor het bijwerken van e-mailstatussen: biedt statusupdates op bericht- en geadresseerdeniveau met betrekking tot het verzenden van e-mailaanvragen door de e-mailservice.

Toegang tot logboeken voor e-mailcommunicatieservice.

De code uitvoeren

Voer de toepassing uit vanuit uw toepassingsmap met de opdracht dotnet run.

dotnet run

Voorbeeldcode

U kunt de voorbeeld-app downloaden uit GitHub.

Ga aan de slag met Azure Communication Services met behulp van de Clientbibliotheek voor JS-e-mail van Communication Services om e-mailberichten te verzenden.

Tip

Start uw e-mailverzendingservaring met Azure Communication Services door rechtstreeks over te slaan naar de voorbeeldcode Basic Email Verzenden en Geavanceerd e-mail verzenden op GitHub.

Informatie over het e-mailobjectmodel

De volgende klassen en interfaces verwerken enkele van de belangrijkste functies van de Azure Communication Services-clientbibliotheek voor e-mail voor JavaScript.

Name Beschrijving
EmailAddress Deze klasse bevat een e-mailadres en een optie voor een weergavenaam.
E-mailbijlage Met deze klasse wordt een e-mailbijlage gemaakt door een unieke id, mime-type tekenreeks voor e-mailbijlagen en binaire gegevens voor inhoud te accepteren.
EmailClient Deze klasse is nodig voor alle e-mailfunctionaliteit. U maakt een instantie met uw verbindingsreeks en gebruikt deze om e-mailberichten te verzenden.
EmailClientOptions Deze klasse kan worden toegevoegd aan de instantie van EmailClient om een specifieke API-versie te targeten.
EmailContent Deze klasse bevat het onderwerp en de hoofdtekst van het e-mailbericht. U moet ten minste één van plaintext- of HTML-inhoud opgeven.
EmailCustomHeader Met deze klasse kunt u een naam- en waardepaar toevoegen voor een aangepaste header. Het belang van e-mail kan ook worden opgegeven via deze headers met behulp van de koptekstnaam 'x-priority' of 'x-msmail-priority'.
EmailMessage Deze klasse combineert de afzender, inhoud en geadresseerden. Aangepaste kopteksten, bijlagen en e-mailadressen voor antwoorden kunnen ook worden toegevoegd.
EmailRecipients Deze klasse bevat lijsten met EmailAddress-objecten voor geadresseerden van het e-mailbericht, inclusief optionele lijsten voor CC & BCC-geadresseerden.
EmailSendResult Deze klasse bevat de resultaten van de verzendbewerking voor e-mail. Het heeft een bewerkings-id, de bewerkingsstatus en het foutobject (indien van toepassing).
EmailSendStatus Deze klasse vertegenwoordigt de set statussen van een verzendbewerking per e-mail.

EmailSendResult retourneert de volgende status van de e-mailbewerking die is uitgevoerd.

Statusnaam Beschrijving
isStarted Retourneert waar als de verzendbewerking voor e-mail momenteel wordt uitgevoerd en wordt verwerkt.
isCompleted Retourneert waar als de verzendbewerking voor e-mail zonder fouten is voltooid en de e-mail is uitgeschakeld voor bezorging. Elke gedetailleerde status van de e-mailbezorging buiten deze fase kan worden verkregen via Azure Monitor of via Azure Event Grid. Meer informatie over het abonneren op e-mailevenementen
resultaat Eigenschap die bestaat als de verzendbewerking voor e-mail is afgesloten.
error Eigenschap die bestaat als de verzendbewerking voor e-mail niet is geslaagd en er een fout is opgetreden. Het e-mailbericht is niet verzonden. Het resultaat bevat een foutobject met meer informatie over de reden voor de fout.

Vereisten

Voor het voltooien van deze quickstart worden kleine kosten in rekening gebracht van een paar dollarcenten of minder in uw Azure-account.

Notitie

We kunnen ook een e-mail verzenden vanuit ons eigen geverifieerde domein. Aangepaste geverifieerde domeinen toevoegen aan e-mailcommunicatieservice.

Controle van vereisten

  • Voer node --version in een terminal of opdrachtvenster uit om te controleren of Node.js is geïnstalleerd.
  • Als u de domeinen wilt weergeven die zijn geverifieerd met uw E-mail Communication Services-resource, meldt u zich aan bij De Azure-portal, zoekt u uw E-mail Communication Services-resource en opent u het tabblad Domeinen inrichten in het linkernavigatiedeelvenster.

De toepassingsomgeving instellen

Een nieuwe Node.js-toepassing maken

Open eerst uw terminal of opdrachtvenster, maak een nieuwe map voor uw app en navigeer daar naartoe.

mkdir email-quickstart && cd email-quickstart

Voer npm init -y uit om een package.json-bestand te maken met de standaardinstellingen.

npm init -y

Gebruik een teksteditor om een bestand met de naam send-email.js te maken in de hoofdmap van het project. Wijzig de eigenschap 'main' in package.json in 'send-email.js'. In de volgende sectie ziet u hoe u de broncode voor deze quickstart toevoegt aan het zojuist gemaakte bestand.

Het pakket installeren

Gebruik de npm install opdracht om de e-mailclientbibliotheek van Azure Communication Services voor JavaScript te installeren.

npm install @azure/communication-email --save

De optie --save geeft de bibliotheek weer als afhankelijkheid in het package.json-bestand.

De e-mailclient maken met verificatie

Er zijn enkele verschillende opties beschikbaar voor het verifiëren van een e-mailclient:

Importeer de EmailClient uit de clientbibliotheek en maak er een exemplaar van met uw verbindingsreeks.

Met de volgende code wordt de verbindingsreeks voor de resource opgehaald uit een omgevingsvariabele met COMMUNICATION_SERVICES_CONNECTION_STRING behulp van het dotenv-pakket. Gebruik de npm install opdracht om het dotenv-pakket te installeren. Meer informatie over het beheren van de verbindingsreeks van uw resource.

npm install dotenv

Voeg de volgende code toe aan 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);

Voor het gemak gebruikt deze quickstart verbindingsreeks s, maar in productieomgevingen raden we u aan service-principals te gebruiken.

Standaard-e-mail verzenden

Een e-mailbericht verzenden

Als u een e-mailbericht wilt verzenden, roept u de functie aan vanuit de beginSend EmailClient. Deze methode retourneert een poller die de status van de bewerking controleert en het resultaat ophaalt zodra deze is voltooid.


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

Voer de volgende vervangingen uit in de code:

  • Vervang <emailalias@emaildomain.com> door het e-mailadres waarnaar u een bericht wilt verzenden.
  • Vervang door <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> het MailFrom-adres van uw geverifieerde domein.

De code uitvoeren

gebruik de knooppuntopdracht om de code uit te voeren die u hebt toegevoegd aan het send-email.js-bestand.

node ./send-email.js

Voorbeeldcode

U kunt de voorbeeld-app downloaden uit GitHub.

Ga aan de slag met Azure Communication Services met behulp van de Java Email SDK voor Communication Services om e-mailberichten te verzenden.

Tip

Start uw e-mailverzendingservaring met Azure Communication Services door rechtstreeks over te slaan naar de voorbeeldcode Basic Email Verzenden en Geavanceerd e-mail verzenden op GitHub.

Informatie over het e-mailobjectmodel

De volgende klassen en interfaces verwerken enkele van de belangrijkste functies van de Azure Communication Services Email SDK voor Python.

Name Beschrijving
EmailAddress Deze klasse bevat een e-mailadres en een optie voor een weergavenaam.
E-mailbijlage Deze interface maakt een e-mailbijlage door een unieke id, MIME-type tekenreeks voor e-mailbijlagen en een tekenreeks met inhoudsbytes te accepteren.
EmailClient Deze klasse is nodig voor alle e-mailfunctionaliteit. U maakt een instantie met uw verbindingsreeks en gebruikt deze om e-mailberichten te verzenden.
EmailMessage Deze klasse combineert de afzender, inhoud en geadresseerden. Aangepaste kopteksten, bijlagen en e-mailadressen voor antwoorden kunnen ook worden toegevoegd.
EmailSendResult Deze klasse bevat de resultaten van de verzendbewerking voor e-mail. Het heeft een bewerkings-id, de bewerkingsstatus en het foutobject (indien van toepassing).
EmailSendStatus Deze klasse vertegenwoordigt de set statussen van een verzendbewerking per e-mail.

EmailSendResult retourneert de volgende status van de e-mailbewerking die is uitgevoerd.

Statusnaam Beschrijving
NOT_STARTED Deze status wordt momenteel niet verzonden vanuit onze service.
WORDT_UITGEVOERD De verzendbewerking voor e-mail wordt momenteel uitgevoerd en verwerkt.
SUCCESSFULLY_COMPLETED De verzendbewerking voor e-mail is zonder fouten voltooid en het e-mailbericht is niet bezorgd. Elke gedetailleerde status van de e-mailbezorging buiten deze fase kan worden verkregen via Azure Monitor of via Azure Event Grid. Meer informatie over het abonneren op e-mailevenementen
MISLUKT De verzendbewerking voor e-mail is mislukt en er is een fout opgetreden. Het e-mailbericht is niet verzonden. Het resultaat bevat een foutobject met meer informatie over de reden voor de fout.

Vereisten

Voor het voltooien van deze quickstart worden kosten van een paar dollarcent of minder in rekening gebracht bij uw Azure-account.

Notitie

We kunnen ook een e-mail verzenden vanuit ons eigen geverifieerde domein Aangepaste geverifieerde domeinen toevoegen aan e-mailcommunicatieservice.

Controle van vereisten

  • Voer in een terminal- of opdrachtvenster uit mvn -v om te controleren of Maven is geïnstalleerd.
  • Meld u aan bij Azure Portal om de domeinen weer te geven die zijn geverifieerd met uw E-mail Communication Services-resource. Zoek uw E-mail Communication Services-resource en open het tabblad Domeinen inrichten vanuit het linkernavigatiedeelvenster.

De toepassingsomgeving instellen

Als u een omgeving wilt instellen voor het verzenden van e-mailberichten, voert u de stappen in de volgende secties uit.

Een nieuwe Java-toepassing maken

Open uw terminal- of opdrachtvenster en navigeer naar de map waarin u uw Java-toepassing wilt maken. Voer de volgende opdracht uit om het Java-project te genereren op basis van de maven-archetype-quickstart-sjabloon.

mvn archetype:generate -DarchetypeArtifactId="maven-archetype-quickstart" -DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" -DgroupId="com.communication.quickstart" -DartifactId="communication-quickstart"

Het generate doel maakt een map met dezelfde naam als de artifactId waarde. Onder deze map bevat de src/main/java-map de broncode van het project, bevat de src/test/java-map de testbron en het pom.xml bestand is het Project Object Model (POM) van het project.

Het pakket installeren

Open het bestand pom.xml in uw teksteditor. Voeg het volgende afhankelijkheidselement toe aan de groep met afhankelijkheden.

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

Stel het app-framework in

Open /src/main/java/com/communication/quickstart/App.java in een teksteditor, voeg importrichtlijnen toe en verwijder de System.out.println("Hello world!"); instructie:

package com.communication.quickstart;

import com.azure.communication.email.models.*;
import com.azure.communication.email.*;
import com.azure.core.util.polling.PollResponse;
import com.azure.core.util.polling.SyncPoller;

public class App
{
    public static void main( String[] args )
    {
        // Quickstart code goes here.
    }
}

De e-mailclient maken met verificatie

Er zijn enkele verschillende opties beschikbaar voor het verifiëren van een e-mailclient:

Als u een client wilt verifiëren, instantieert u een EmailClient instantie met uw verbindingsreeks. Meer informatie over het beheren van de verbindingsreeks van uw resource. U kunt de client ook initialiseren met elke aangepaste HTTP-client die de com.azure.core.http.HttpClient interface implementeert.

Als u een client wilt instantiëren, voegt u de volgende code toe aan de main methode:

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

Voor het gemak gebruikt deze quickstart verbindingsreeks s, maar in productieomgevingen raden we u aan service-principals te gebruiken.

Standaard-e-mail verzenden

Als u een e-mailbericht wilt verzenden, roept u de beginSend functie aan vanuit de EmailClient. Deze methode retourneert een poller, die kan worden gebruikt om de status van de bewerking te controleren en het resultaat op te halen zodra deze is voltooid. Houd er rekening mee dat de eerste aanvraag voor het verzenden van een e-mailbericht pas wordt verzonden nadat de poll methode is aangeroepen of dat we wachten op voltooiing van de poller.

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

try
{
    SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);

    PollResponse<EmailSendResult> pollResponse = null;

    Duration timeElapsed = Duration.ofSeconds(0);
    Duration POLLER_WAIT_TIME = Duration.ofSeconds(10);

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

Voer de volgende vervangingen uit in de code:

  • Vervang <emailalias@emaildomain.com> door het e-mailadres waarnaar u een bericht wilt verzenden.
  • Vervang door <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> het MailFrom-adres van uw geverifieerde domein.

De code uitvoeren

  1. Navigeer naar de map met het pom.xml-bestand en compileer het project met behulp van de mvn opdracht.

    mvn compile

  2. Bouw het pakket.

    mvn package

  3. Voer de volgende mvn-opdracht uit om de app uit te voeren.

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

Voorbeeldcode

U kunt de voorbeeld-app downloaden uit GitHub.

Ga aan de slag met Azure Communication Services met behulp van de Python Email SDK voor Communication Services om e-mailberichten te verzenden.

Tip

Start uw e-mailverzendingservaring met Azure Communication Services door rechtstreeks over te slaan naar de voorbeeldcode Basic Email Verzenden en Geavanceerd e-mail verzenden op GitHub.

Informatie over het e-mailobjectmodel

In het volgende JSON-berichtsjabloon en antwoordobject ziet u enkele van de belangrijkste functies van de Azure Communication Services Email SDK voor 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.
    }
}

De response.status waarden worden verder uitgelegd in de volgende tabel.

Statusnaam Beschrijving
InProgress De verzendbewerking voor e-mail wordt momenteel uitgevoerd en verwerkt.
Geslaagd De verzendbewerking voor e-mail is zonder fouten voltooid en het e-mailbericht is niet bezorgd. Elke gedetailleerde status van de e-mailbezorging buiten deze fase kan worden verkregen via Azure Monitor of via Azure Event Grid. Meer informatie over het abonneren op e-mailevenementen
Mislukt De verzendbewerking voor e-mail is mislukt en er is een fout opgetreden. Het e-mailbericht is niet verzonden. Het resultaat bevat een foutobject met meer informatie over de reden voor de fout.

Vereisten

Voor het voltooien van deze quickstart worden kleine kosten in rekening gebracht van een paar dollarcenten of minder in uw Azure-account.

Notitie

We kunnen ook een e-mail verzenden vanuit ons eigen geverifieerde domein. Aangepaste geverifieerde domeinen toevoegen aan e-mailcommunicatieservice.

Controle van vereisten

  • Voer in een terminal- of opdrachtvenster de opdracht python --version uit om te controleren of Python is geïnstalleerd.
  • Meld u aan bij Azure Portal om de domeinen weer te geven die zijn geverifieerd met uw E-mail Communication Services-resource. Zoek uw E-mail Communication Services-resource en open het tabblad Domeinen inrichten vanuit het linkernavigatiedeelvenster.

De toepassingsomgeving instellen

Als u een omgeving wilt instellen voor het verzenden van e-mailberichten, voert u de stappen in de volgende secties uit.

Een nieuwe Python-toepassing maken

  1. Open uw terminal-of opdrachtvenster. Gebruik vervolgens de volgende opdracht om een virtuele omgeving te maken en deze te activeren. Met deze opdracht maakt u een nieuwe map voor uw app.

    python -m venv email-quickstart

  2. Navigeer naar de hoofdmap van de virtuele omgeving en activeer deze met behulp van de volgende opdrachten.

    cd email-quickstart
.\Scripts\activate

  3. Gebruik een teksteditor om een bestand met de naam send-email.py te maken in de hoofdmap van het project en de structuur voor het programma toe te voegen, inclusief eenvoudige verwerking van uitzonderingen.

    import os
from azure.communication.email import EmailClient

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

In de volgende secties voegt u alle broncode voor deze quickstart toe aan het send-email.py bestand dat u hebt gemaakt.

Het pakket installeren

Installeer, terwijl u zich nog in de toepassingsmap bevindt, de Azure Communication Services Email SDK voor Python-pakket met behulp van de volgende opdracht.

pip install azure-communication-email

De e-mailclient maken met verificatie

Er zijn enkele verschillende opties beschikbaar voor het verifiëren van een e-mailclient:

Instantieer een EmailClient met uw verbindingsreeks. Meer informatie over het beheren van de verbindingsreeks van uw resource.

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

Voor het gemak gebruikt deze quickstart verbindingsreeks s, maar in productieomgevingen raden we u aan service-principals te gebruiken.

Standaard-e-mail verzenden

Een e-mailbericht verzenden

Als u een e-mailbericht wilt verzenden, moet u het volgende doen:

  • Maak het bericht met de volgende waarden:
    • senderAddress: Een geldig e-mailadres van afzender, te vinden in het veld MailFrom in het overzichtsvenster van het domein dat is gekoppeld aan uw E-mail Communication Services-resource.
    • recipients: Een object met een lijst met e-mailontvangers en optioneel lijsten met CC & BCC-e-mailontvangers.
    • content: Een object met het onderwerp en eventueel de tekst zonder opmaak of HTML-inhoud van een e-mailbericht.
  • Roep de methode begin_send aan, die het resultaat van de bewerking retourneert.
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())

Voer de volgende vervangingen uit in de code:

  • Vervang <emailalias@emaildomain.com> door het e-mailadres waarnaar u een bericht wilt verzenden.
  • Vervang door <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> het MailFrom-adres van uw geverifieerde domein.

De status van de e-mailbezorging ophalen

We kunnen de status van de e-mailbezorging peilen door een lus in te stellen voor het bewerkingsstatusobject dat wordt geretourneerd door de methode e-mailclient 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)

De code uitvoeren

Voer de toepassing uit vanuit uw toepassingsmap met de opdracht python.

python send-email.py

Voorbeeldcode

U kunt de voorbeeld-app downloaden uit GitHub.

Vereisten

E-mailbericht versturen

Voer de volgende stappen uit om een nieuwe stap toe te voegen aan uw werkstroom met behulp van de e-mailconnector van Azure Communication Services:

  1. Open uw werkstroom voor logische apps in de ontwerpfunctie.

    Verbruik

    1. Selecteer nieuwe stap onder de stap waar u de nieuwe actie wilt toevoegen. Als u de nieuwe actie tussen stappen wilt toevoegen, verplaatst u de aanwijzer over de pijl tussen deze stappen, selecteert u het plusteken (+) en selecteert u Een actie toevoegen.

    2. Selecteer Standard onder het zoekvak Een bewerking kiezen. Voer in het zoekvak Communication Services-e-mail in.

    3. Selecteer e-mail verzenden in de lijst met acties.

      Schermopname van de e-mailactie e-mail verzenden van azure Communication Services-connector.

    Standaard

    1. Selecteer onder de stap waar u de nieuwe actie wilt toevoegen het plusteken (+). Als u de nieuwe actie tussen stappen wilt toevoegen, verplaatst u de aanwijzer over de pijl tussen deze stappen, selecteert u het plusteken (+) en selecteert u Een actie toevoegen.

    2. Selecteer Azure onder het zoekvak Een bewerking kiezen. Voer in het zoekvak Communication Services-e-mail in.

    3. Selecteer e-mail verzenden in de lijst met acties.

  2. Geef een naam op voor de verbinding.

  3. Voer de verbindingsreeks in voor uw Azure Communications Service-resource. Volg deze stappen om deze tekenreeks te vinden:

    1. Open uw Azure Communication Service-resource in Azure Portal.

    2. Selecteer sleutels in het resourcemenu onder Instellingen en kopieer de verbindingsreeks.

      Schermopname van de azure Communication Services Verbinding maken ion String.

  4. Selecteer Maken als u klaar bent.

  5. Gebruik in het veld Van het e-mailadres dat u hebt geconfigureerd in de vereisten. Voer de waarden in voor de velden Aan, Onderwerp en Hoofdtekst , bijvoorbeeld:

    Schermopname van de E-mailactie-invoer verzenden van de Azure Communication Services-connector.

  6. Sla uw werkstroom op. Selecteer in de werkbalk van de ontwerper Opslaan.

Uw werkstroom testen

Op basis van of u een verbruiks- of standaardwerkstroom hebt, start u uw werkstroom handmatig:

  • Verbruik: Selecteer Op de werkbalk van de ontwerpfunctie de optie Triggeruitvoering>uitvoeren.
  • Standaard: Selecteer Overzicht in het werkstroommenu. Selecteer Uitvoeren van trigger>uitvoeren op de werkbalk op de werkbalk.

De werkstroom maakt een gebruiker, geeft een toegangstoken voor die gebruiker uit, verwijdert en verwijdert de gebruiker. U kunt de uitvoer van deze acties controleren nadat de werkstroom is uitgevoerd.

U ontvangt een e-mailbericht op het opgegeven adres. U kunt ook de actie Status van e-mailbericht ophalen gebruiken om de status van e-mailberichten te controleren die worden verzonden via de actie E-mail verzenden. Raadpleeg de referentiedocumentatie voor de Azure Communication Services-e-mailconnector voor meer acties.

Werkstroombronnen opschonen

Als u de resource, werkstroom en gerelateerde resources van uw logische app wilt opschonen, bekijkt u hoe u logische app-resources voor verbruik opschoont of hoe u Resources van de logische standaard-app opschoont.

Probleemoplossing

E-mailbezorging

Als u problemen met betrekking tot e-mailbezorging wilt oplossen, kunt u de status van de e-mailbezorging ophalen om details van de bezorging vast te leggen.

Belangrijk

Het resultaat dat is geretourneerd door te peilen naar de status van de verzendbewerking, valideert alleen het feit dat het e-mailbericht is verzonden voor bezorging. Als u meer informatie wilt over de status van de bezorging aan het einde van de geadresseerde, moet u verwijzen naar het afhandelen van e-mailevenementen.

Beperking van e-mail

Als u ziet dat uw toepassing vasthangt, kan dit komen doordat het verzenden van e-mail wordt beperkt. U kunt dit afhandelen via logboekregistratie of door een aangepast beleid te implementeren.

Notitie

Deze sandbox-installatie is bedoeld om ontwikkelaars te helpen bij het bouwen van de toepassing. U kunt geleidelijk aanvragen om het verzendvolume te verhogen zodra de toepassing klaar is om live te gaan. Dien een ondersteuningsaanvraag in om de gewenste verzendlimiet te verhogen als u een aantal berichten wilt verzenden dat de frequentielimieten overschrijdt.

Azure Communication Service-resources opschonen

Als u een Communication Services-abonnement wilt opschonen en verwijderen, kunt u de resource of resourcegroep verwijderen. Als u de resourcegroep verwijdert, worden ook alle andere gekoppelde resources verwijderd. Meer informatie over het opschonen van resources.

Volgende stappen

In deze quickstart hebt u geleerd hoe u e-mailberichten verzendt met behulp van Azure Communication Services. U kunt ook het volgende doen: