Bagikan melalui

Mulai cepat: Cara mengirim email menggunakan Azure Communication Services

  • Artikel

Catatan

Harap bagikan pemikiran dan umpan balik Anda tentang Azure Communication Services dengan kami dengan mengambil survei singkat ini.

Mulai cepat ini menjelaskan cara mengirim email menggunakan SDK Email kami.

Mulai menggunakan Azure Communication Services dengan menggunakan Communication Services Coba Email untuk mengirim pesan Email.

Prasyarat

Menyelesaikan mulai cepat ini dikenakan biaya kecil kurang lebih sebanyak beberapa sen USD di akun Azure Anda.

Mengirim Email menggunakan Coba Email

Coba Email membantu Anda mulai mengirim email ke penerima yang diinginkan menggunakan Azure Communication Services, serta memverifikasi konfigurasi aplikasi Anda untuk mengirim email. Ini juga membantu memulai pengembangan pemberitahuan email Anda dengan cuplikan kode dalam pilihan bahasa pilihan Anda.

Untuk mengirim pesan ke penerima, dan untuk menentukan subjek dan isi pesan,

  1. Dari halaman gambaran umum sumber daya Azure Communication Service yang disediakan, klik Coba Email di panel navigasi kiri di bawah Email.

    Cuplikan layar yang memperlihatkan panel navigasi kiri untuk Coba Email.

  2. Pilih salah satu domain terverifikasi dari menu drop-down.

    Cuplikan layar yang memperlihatkan domain yang diverifikasi dari menu drop-down.

  3. Buat email yang akan dikirim

    • Masukkan Alamat email penerima
    • Masukkan Subjek
    • Menulis Isi Email

    Cuplikan layar yang memperlihatkan cara memfilter dan memilih salah satu domain email terverifikasi untuk disambungkan.

  4. Klik Kirim

    Cuplikan layar yang memperlihatkan salah satu domain email terverifikasi sekarang tersambung.

  5. Email Berhasil Dikirim.

    Cuplikan layar yang memperlihatkan pengiriman email yang berhasil.

  6. Sekarang Anda juga dapat menyalin sampel Cuplikan Kode untuk mengirim email yang akan digunakan dalam proyek sampel Anda untuk mengirim pemberitahuan.

    • Pilih Bahasa pilihan Anda

    • Klik Sisipkan Koneksi saya

    • Klik Salin

      Cuplikan layar yang memperlihatkan cuplikan kode untuk mengirim email.

  7. Cuplikan Kode Email sekarang siap digunakan dalam proyek pemberitahuan Anda.

Mulai menggunakan Azure Communication Services dengan menggunakan ekstensi komunikasi Azure CLI untuk mengirim pesan Email.

Menyelesaikan mulai cepat ini dikenakan biaya kecil kurang lebih sebanyak beberapa sen USD di akun Azure Anda.

Prasyarat

Pemeriksaan prasyarat

  • Di terminal atau jendela perintah, jalankan az --version perintah untuk memeriksa apakah Azure CLI dan ekstensi komunikasi diinstal.
  • Untuk melihat domain yang diverifikasi dengan sumber daya Email Communication Services Anda, masuk ke portal Azure. Temukan sumber daya Email Communication Services Anda dan buka tab Provisi domain dari panel navigasi kiri.

Menyiapkan

Menambahkan ekstensi

Tambahkan ekstensi Azure Communication Services untuk Azure CLI dengan menggunakan az extension perintah .

az extension add --name communication

Masuk ke Azure CLI

Anda perlu masuk ke Azure CLI. Anda dapat masuk menjalankan az login perintah dari terminal dan memberikan kredensial Anda.

Simpan string koneksi Anda dalam variabel lingkungan

Anda dapat mengonfigurasi AZURE_COMMUNICATION_CONNECTION_STRING variabel lingkungan untuk menggunakan operasi kunci Azure CLI tanpa harus menggunakan --connection_string untuk meneruskan string koneksi. Untuk mengonfigurasi variabel lingkungan, buka jendela konsol dan pilih sistem operasi Anda dari tab di bawah ini. Ganti <connectionString> dengan string koneksi aktual Anda.

Catatan

Jangan simpan string koneksi Anda sebagai variabel lingkungan yang tidak terenkripsi untuk lingkungan produksi. Ini dimaksudkan hanya untuk tujuan pengujian. Untuk lingkungan produksi, Anda harus menghasilkan string koneksi baru. Kami mendorong Anda untuk mengenkripsi string koneksi dan mengubahnya secara teratur.

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Setelah Anda menambahkan variabel lingkungan, Anda mungkin perlu menghidupkan ulang program yang sedang berjalan yang perlu membaca variabel lingkungan, termasuk jendela konsol. Misalnya, jika Anda menggunakan Visual Studio sebagai editor, mulai ulang Visual Studio sebelum menjalankan contoh.

Mengirim pesan email

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

Buat penggantian ini dalam kode:

  • Ganti <yourConnectionString> dengan string koneksi Anda.
  • Ganti <emailalias@emaildomain.com> dengan alamat email yang ingin Anda kirimi pesan.
  • Ganti <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> dengan alamat MailFrom domain terverifikasi Anda.

Perintah di atas juga melakukan polling pada messageId dan mengembalikan status pengiriman email. Status dapat berupa:

Nama Status Deskripsi
Belum Dimulai Saat ini kami tidak mengirim status ini dari layanan kami.
Sedang berjalan Operasi pengiriman email saat ini sedang berlangsung dan sedang diproses.
Berhasil Operasi pengiriman email telah selesai tanpa kesalahan dan email keluar untuk pengiriman. Setiap status terperinci tentang pengiriman email di luar tahap ini dapat diperoleh baik melalui Azure Monitor atau melalui Azure Event Grid. Pelajari cara berlangganan peristiwa email
Gagal Operasi pengiriman email tidak berhasil dan mengalami kesalahan. Email tidak dikirim. Hasilnya berisi objek kesalahan dengan detail lebih lanjut tentang alasan kegagalan.

Parameter opsional

Parameter opsional berikut tersedia di Azure CLI.

  • --html dapat digunakan alih-alih --text untuk isi email html.

  • --importance mengatur jenis kepentingan untuk email. Nilai yang diketahui adalah: tinggi, normal, dan rendah. Defaultnya adalah normal.

  • --to mengatur daftar penerima email.

  • --cc mengatur alamat email salinan karbon.

  • --bcc mengatur alamat email salinan karbon buta.

  • --reply-to mengatur alamat email Balas-Ke.

  • --disable-tracking menunjukkan apakah pelacakan keterlibatan pengguna harus dinonaktifkan untuk permintaan ini.

  • --attachments mengatur daftar lampiran email.

  • --attachment-types mengatur daftar jenis lampiran email, dalam urutan lampiran yang sama.

Selain itu, Anda dapat menggunakan daftar penerima dengan dan --bcc mirip --todengan --cc . Perlu ada setidaknya satu penerima di --to atau --cc atau --bcc.

Memulai Azure Communication Services dengan menggunakan pustaka klien Email C# Communication Services untuk mengirim pesan Email.

Tip

Mulai langsung pengalaman pengiriman email Anda dengan Azure Communication Services dengan melompat langsung ke kode sampel Pengiriman Email Dasar dan Pengiriman Email Tingkat Lanjut di GitHub.

Memahami model Objek Email

Kelas dan antarmuka berikut menangani beberapa fitur utama dari Pustaka klien Email Azure Communication Services untuk C#.

Nama Deskripsi
EmailAddress Kelas ini berisi alamat email dan opsi untuk nama tampilan.
EmailAttachment Kelas ini membuat lampiran email dengan menerima ID unik, string jenis MIME lampiran email, dan data biner untuk konten.
EmailClient Kelas ini diperlukan untuk semua fungsionalitas email. Anda membuat kelas dengan string koneksi dan menggunakannya untuk mengirim pesan email.
EmailClientOptions Kelas ini dapat ditambahkan ke pembuatan EmailClient untuk menargetkan versi API tertentu.
EmailContent Kelas ini berisi subjek dan isi pesan email. Anda harus menentukan setidaknya salah satu konten PlainText atau Html
EmailCustomHeader Kelas ini memungkinkan penambahan pasangan nama dan nilai untuk header kustom. Kepentingan email juga dapat ditentukan melalui header ini menggunakan nama header 'x-priority' atau 'x-msmail-priority'
EmailMessage Kelas ini menggabungkan pengirim, konten, dan penerima. Header kustom, lampiran, dan alamat email balasan juga dapat ditambahkan secara opsional.
EmailRecipients Kelas ini menyimpan daftar objek EmailAddress untuk penerima pesan email, termasuk daftar opsional untuk penerima CC & BCC.
EmailSendOperation Kelas ini mewakili operasi pengiriman email asinkron dan dikembalikan dari panggilan api pengiriman email.
EmailSendResult Kelas ini menyimpan hasil operasi pengiriman email. Ini memiliki ID operasi, status operasi, dan objek kesalahan (jika berlaku).

EmailSendResult mengembalikan status berikut pada operasi email yang dilakukan.

Keadaan Deskripsi
Belum Dimulai Saat ini kami tidak mengirim status ini dari layanan kami.
Sedang berjalan Operasi pengiriman email saat ini sedang berlangsung dan sedang diproses.
Berhasil Operasi pengiriman email telah selesai tanpa kesalahan dan email keluar untuk pengiriman. Setiap status terperinci tentang pengiriman email di luar tahap ini dapat diperoleh baik melalui Azure Monitor atau melalui Azure Event Grid. Pelajari cara berlangganan peristiwa email
Gagal Operasi pengiriman email tidak berhasil dan mengalami kesalahan. Email tidak dikirim. Hasilnya berisi objek kesalahan dengan detail lebih lanjut tentang alasan kegagalan.

Prasyarat

Menyelesaikan mulai cepat ini dikenakan biaya kecil kurang lebih sebanyak beberapa sen USD di akun Azure Anda.

Catatan

Kami juga dapat mengirim email dari domain terverifikasi kami sendiri. Tambahkan domain terverifikasi kustom ke Email Communication Service.

Pemeriksaan prasyarat

  • Di jendela terminal atau perintah, jalankan perintah dotnet untuk memeriksa apakah .NET SDK telah diinstal.
  • Untuk melihat subdomain yang terkait dengan sumber daya Communication Services Email Anda, masuk ke portal Microsoft Azure, cari sumber daya Communication Services Email dan buka tab Provisikan domain dari panel navigasi kiri.

Membuat aplikasi C# baru

Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan perintah dotnet new untuk membuat aplikasi konsol baru dengan nama EmailQuickstart. Perintah ini membuat proyek C# "Halo Dunia" sederhana dengan file sumber tunggal: Program.cs.

dotnet new console -o EmailQuickstart

Ubah direktori Anda ke folder aplikasi yang baru dibuat dan gunakan perintah dotnet build untuk mengompilasi aplikasi Anda.

cd EmailQuickstart
dotnet build

Pasang paket

Saat masih dalam direktori aplikasi, instal pustaka klien Email Azure Communication Services untuk paket .NET dengan menggunakan perintah dotnet add package.

dotnet add package Azure.Communication.Email

Membuat klien email dengan autentikasi

Buka Program.cs dan ganti kode yang ada dengan kode berikut untuk menambahkan arahan using guna menyertakan namespace Azure.Communication.Email dan titik awal eksekusi program Anda.

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

    }
  }
}

Ada beberapa opsi berbeda yang tersedia untuk mengautentikasi klien email:

Buka Program.cs di editor teks serta ganti isi metode Main dengan kode untuk menginisialisasi EmailClient dengan string koneksi Anda. Kode berikut mengambil string koneksi untuk sumber daya dari variabel lingkungan bernama COMMUNICATION_SERVICES_CONNECTION_STRING. Pelajari cara mengelola string koneksi sumber daya Anda.

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

Pengiriman email dasar

Membuat pesan email Anda

Untuk mengirim pesan email, Anda perlu:

  • Tentukan subjek dan isi email.
  • Tentukan Alamat Pengirim Anda. Buat pesan email Anda dengan informasi Pengirim, Anda mendapatkan alamat MailFrom dari domain terverifikasi Anda.
  • Tentukan Alamat Penerima.
  • Panggil metode SendAsync. Tambahkan kode ini pada akhir metode Main di Program.cs:

Mengganti dengan detail domain Anda dan ubah konten, detail penerima sesuai kebutuhan


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

Mengirim dan mendapatkan status pengiriman email

Untuk mengirim pesan email, Anda perlu:

  • Panggil metode SendAsync yang mengirim permintaan email sebagai operasi asinkron. Panggilan dengan Azure.WaitUntil.Completed jika metode Anda harus menunggu untuk kembali hingga operasi jangka panjang selesai pada layanan. Hubungi dengan Azure.WaitUntil.Started jika metode Anda harus kembali setelah memulai operasi.
  • Metode SendAsync mengembalikan EmailSendOperation yang mengembalikan EmailSendStatus "Berhasil" jika email keluar untuk pengiriman dan melempar pengecualian sebaliknya. Tambahkan kode ini pada akhir metode Main di 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}");
}

Mendapatkan status pengiriman email

EmailSendOperation hanya mengembalikan status operasi email. Untuk mendapatkan status pengiriman email aktual, Anda dapat berlangganan acara "EmailDeliveryReportReceived" yang dihasilkan saat pengiriman email selesai. Peristiwa mengembalikan status pengiriman berikut:

  • Disampaikan.
  • Gagal.
  • Dikarantina.

Lihat Menangani Peristiwa Email untuk detailnya.

Anda juga sekarang dapat berlangganan log Operasional Email yang menyediakan informasi terkait metrik pengiriman untuk pesan yang dikirim dari layanan Email.

  • Log operasional Email Kirim Email - menyediakan informasi terperinci yang terkait dengan layanan Email yang mengirim permintaan email.
  • Log operasional Pembaruan Status Email - menyediakan pembaruan status pengiriman tingkat pesan dan penerima yang terkait dengan layanan Email mengirim permintaan email.

Akses log untuk Layanan Komunikasi Email.

Menjalankan kode

Menjalankan aplikasi dari direktori aplikasi Anda dengan perintah dotnet run.

dotnet run

Kode Sampel

Anda dapat mengunduh aplikasi contoh dari GitHub

Memulai Azure Communication Services dengan menggunakan pustaka klien Email Communication Services JS untuk mengirim pesan Email.

Tip

Mulai langsung pengalaman pengiriman email Anda dengan Azure Communication Services dengan melompat langsung ke kode sampel Pengiriman Email Dasar dan Pengiriman Email Tingkat Lanjut di GitHub.

Memahami model objek email

Kelas dan antarmuka berikut menangani beberapa fitur utama dari Pustaka klien Email Azure Communication Services untuk JavaScript.

Nama Deskripsi
EmailAddress Kelas ini berisi alamat email dan opsi untuk nama tampilan.
EmailAttachment Kelas ini membuat lampiran email dengan menerima ID unik, string jenis MIME lampiran email, dan data biner untuk konten.
EmailClient Kelas ini diperlukan untuk semua fungsionalitas email. Anda membuat kelas dengan string koneksi dan menggunakannya untuk mengirim pesan email.
EmailClientOptions Kelas ini dapat ditambahkan ke pembuatan EmailClient untuk menargetkan versi API tertentu.
EmailContent Kelas ini berisi subjek dan isi pesan email. Anda harus menentukan setidaknya salah satu konten PlainText atau Html.
EmailCustomHeader Kelas ini memungkinkan penambahan pasangan nama dan nilai untuk header kustom. Kepentingan email juga dapat ditentukan melalui header ini menggunakan nama header 'x-priority' atau 'x-msmail-priority'.
EmailMessage Kelas ini menggabungkan pengirim, konten, dan penerima. Header kustom, lampiran, dan alamat email balasan juga dapat ditambahkan secara opsional.
EmailRecipients Kelas ini menyimpan daftar objek EmailAddress untuk penerima pesan email, termasuk daftar opsional untuk penerima CC & BCC.
EmailSendResult Kelas ini menyimpan hasil operasi pengiriman email. Ini memiliki ID operasi, status operasi, dan objek kesalahan (jika berlaku).
EmailSendStatus Kelas ini mewakili sekumpulan status operasi pengiriman email.

EmailSendResult mengembalikan status berikut pada operasi email yang dilakukan.

Nama Status Deskripsi
isStarted Mengembalikan true jika operasi pengiriman email saat ini sedang berlangsung dan sedang diproses.
isCompleted Mengembalikan true jika operasi pengiriman email telah selesai tanpa kesalahan dan email keluar untuk pengiriman. Setiap status terperinci tentang pengiriman email di luar tahap ini dapat diperoleh baik melalui Azure Monitor atau melalui Azure Event Grid. Pelajari cara berlangganan peristiwa email
hasil Properti yang ada jika operasi pengiriman email telah disimpulkan.
kesalahan Properti yang ada jika operasi pengiriman email tidak berhasil dan mengalami kesalahan. Email tidak dikirim. Hasilnya berisi objek kesalahan dengan detail lebih lanjut tentang alasan kegagalan.

Prasyarat

Menyelesaikan mulai cepat ini dikenakan biaya kecil kurang lebih sebanyak beberapa sen USD di akun Azure Anda.

Catatan

Kami juga dapat mengirim email dari domain terverifikasi kami sendiri. Tambahkan domain terverifikasi kustom ke Email Communication Service.

Pemeriksaan prasyarat

  • Di terminal atau jendela perintah, jalankan node --version untuk memeriksa apakah Node.js sudah dipasang.
  • Untuk melihat domain yang diverifikasi dengan sumber daya Communication Services Email Anda, masuk ke portal Microsoft Azure, temukan sumber daya Communication Services Email Anda, dan buka tab Provisikan domain dari panel navigasi kiri.

Menyiapkan lingkungan aplikasi

Membuat aplikasi Node.js baru

Pertama, buka jendela perintah atau terminal, buat direktori baru untuk aplikasi Anda, dan arahkan ke sana.

mkdir email-quickstart && cd email-quickstart

Jalankan npm init -y untuk membuat file package.json dengan pengaturan default.

npm init -y

Gunakan editor teks untuk membuat file bernama send-email.js di direktori root proyek. Ubah properti "main" di package.json menjadi "send-email.js". Bagian berikut menunjukkan cara menambahkan kode sumber untuk mulai cepat ini ke file yang baru dibuat.

Pasang paket

Gunakan perintah npm install untuk menginstal pustaka klien Email Azure Communication Services untuk JavaScript.

npm install @azure/communication-email --save

Opsi --save mencantumkan pustaka sebagai dependensi di file package.json Anda.

Membuat klien email dengan autentikasi

Ada beberapa opsi berbeda yang tersedia untuk mengautentikasi klien email:

Impor EmailClient dari pustaka klien dan buat EmailClient dengan string koneksi Anda.

Kode berikut mengambil string koneksi untuk sumber daya dari variabel lingkungan bernama COMMUNICATION_SERVICES_CONNECTION_STRING menggunakan paket dotenv. Gunakan perintah npm install untuk menginstal paket dotenv. Pelajari cara mengelola string koneksi sumber daya Anda.

npm install dotenv

Tambahkan kode berikut ke 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);

Untuk kesederhanaan, mulai cepat ini menggunakan string koneksi, tetapi di lingkungan produksi, sebaiknya gunakan perwakilan layanan.

Pengiriman email dasar

Mengirim pesan email

Untuk mengirim pesan email, panggil beginSend fungsi dari EmailClient. Metode ini mengembalikan poller yang memeriksa status operasi dan mengambil hasil setelah selesai.


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

Buat penggantian ini dalam kode:

  • Ganti <emailalias@emaildomain.com> dengan alamat email yang ingin Anda kirimi pesan.
  • Ganti <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> dengan alamat MailFrom domain terverifikasi Anda.

Menjalankan kode

gunakan perintah node untuk menjalankan kode yang Anda tambahkan ke file send-email.js.

node ./send-email.js

Kode Sampel

Anda dapat mengunduh aplikasi contoh dari GitHub

Mulai menggunakan Azure Communication Services dengan menggunakan SDK Email Java Communication Services untuk mengirim pesan Email.

Tip

Mulai langsung pengalaman pengiriman email Anda dengan Azure Communication Services dengan melompat langsung ke kode sampel Pengiriman Email Dasar dan Pengiriman Email Tingkat Lanjut di GitHub.

Memahami model objek email

Kelas dan antarmuka berikut menangani beberapa fitur utama SDK Email Azure Communication Services untuk Python.

Nama Deskripsi
EmailAddress Kelas ini berisi alamat email dan opsi untuk nama tampilan.
EmailAttachment Antarmuka ini membuat lampiran email dengan menerima ID unik, string jenis MIME lampiran email, dan string byte konten.
EmailClient Kelas ini diperlukan untuk semua fungsionalitas email. Anda membuat kelas dengan string koneksi dan menggunakannya untuk mengirim pesan email.
EmailMessage Kelas ini menggabungkan pengirim, konten, dan penerima. Header kustom, lampiran, dan alamat email balasan juga dapat ditambahkan secara opsional.
EmailSendResult Kelas ini menyimpan hasil operasi pengiriman email. Ini memiliki ID operasi, status operasi, dan objek kesalahan (jika berlaku).
EmailSendStatus Kelas ini mewakili sekumpulan status operasi pengiriman email.

EmailSendResult mengembalikan status berikut pada operasi email yang dilakukan.

Nama Status Deskripsi
NOT_STARTED Saat ini kami tidak mengirim status ini dari layanan kami.
SEDANG_BERLANGSUNG Operasi pengiriman email saat ini sedang berlangsung dan sedang diproses.
SUCCESSFULLY_COMPLETED Operasi pengiriman email telah selesai tanpa kesalahan dan email keluar untuk pengiriman. Setiap status terperinci tentang pengiriman email di luar tahap ini dapat diperoleh baik melalui Azure Monitor atau melalui Azure Event Grid. Pelajari cara berlangganan peristiwa email
FAILED Operasi pengiriman email tidak berhasil dan mengalami kesalahan. Email tidak dikirim. Hasilnya berisi objek kesalahan dengan detail lebih lanjut tentang alasan kegagalan.

Prasyarat

Menyelesaikan panduan mulai cepat ini dikenakan biaya kecil berupa beberapa sen USD atau kurang di akun Azure Anda.

Catatan

Kami juga dapat mengirim email dari domain terverifikasi kami sendiri Menambahkan domain terverifikasi kustom ke Email Communication Service.

Pemeriksaan prasyarat

  • Di terminal atau jendela perintah, jalankan mvn -v untuk memeriksa apakah Maven diinstal.
  • Untuk melihat domain yang diverifikasi dengan sumber daya Email Communication Services Anda, masuk ke portal Azure. Temukan sumber daya Email Communication Services Anda dan buka tab Provisi domain dari panel navigasi kiri.

Menyiapkan lingkungan aplikasi

Untuk menyiapkan lingkungan untuk mengirim email, lakukan langkah-langkah di bagian berikut.

Membuat aplikasi Java baru

Buka terminal atau jendela perintah Anda dan arahkan ke direktori tempat Anda ingin membuat aplikasi Java. Jalankan perintah berikut untuk menghasilkan proyek Java dari templat 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"

Tujuannya generate membuat direktori dengan nama artifactId yang sama dengan nilai . Di bawah direktori ini, direktori src/main/java berisi kode sumber proyek, direktori src/test/java berisi sumber pengujian, dan file pom.xml adalah Project Object Model (POM) proyek.

Pasang paket

Buka file pom.xml di editor teks Anda. Tambahkan elemen dependensi berikut ke grup dependensi.

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

Menyiapkan kerangka kerja aplikasi

Buka /src/main/java/com/communication/quickstart/App.java di editor teks, tambahkan arahan impor, dan hapus System.out.println("Hello world!"); pernyataan:

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

Membuat klien email dengan autentikasi

Ada beberapa opsi berbeda yang tersedia untuk mengautentikasi klien email.

Untuk mengautentikasi klien, Anda membuat instans EmailClient dengan string koneksi Anda. Pelajari cara mengelola string koneksi sumber daya Anda. Anda juga dapat menginisialisasi klien dengan klien HTTP kustom apa pun yang mengimplementasikan com.azure.core.http.HttpClient antarmuka.

Untuk membuat instans klien sinkron, tambahkan kode berikut ke main metode :

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

Untuk membuat instans klien asinkron, tambahkan kode berikut ke main metode :

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

Untuk kesederhanaan, mulai cepat ini menggunakan string koneksi, tetapi di lingkungan produksi, sebaiknya gunakan perwakilan layanan.

Pengiriman email dasar

Pesan email dapat dibuat menggunakan EmailMessage objek di 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.");

Buat penggantian ini dalam kode:

  • Ganti <emailalias@emaildomain.com> dengan alamat email yang ingin Anda kirimi pesan.
  • Ganti <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> dengan alamat MailFrom domain terverifikasi Anda.

Untuk mengirim pesan email, panggil beginSend fungsi dari EmailClient.

Memanggil beginSend klien sinkronisasi mengembalikan SyncPoller objek, yang dapat digunakan untuk memeriksa status operasi dan mengambil hasilnya setelah selesai. Perhatikan bahwa permintaan awal untuk mengirim email akan dikirim segera setelah metode dipanggil beginSend . Mengirim email adalah operasi jangka panjang. Penting untuk dicatat bahwa getFinalResult() metode pada poller adalah operasi pemblokiran sampai status terminal (SUCCESSFULLY_COMPLETED atau FAILED) tercapai. Metode yang disarankan adalah melakukan polling manual pada interval yang sesuai untuk kebutuhan aplikasi Anda seperti yang ditunjukkan dalam sampel di bawah ini.

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

Menjalankan kode

  1. Navigasi ke direktori yang berisi file pom.xml dan kompilasi proyek dengan menggunakan mvn perintah .

    mvn compile

  2. Buat paket.

    mvn package

  3. Jalankan perintah mvn berikut untuk menjalankan aplikasi.

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

Kode Sampel

Anda dapat mengunduh aplikasi contoh dari GitHub

Mulai menggunakan Azure Communication Services dengan menggunakan Communication Services Python Email SDK untuk mengirim pesan Email.

Tip

Mulai langsung pengalaman pengiriman email Anda dengan Azure Communication Services dengan melompat langsung ke kode sampel Pengiriman Email Dasar dan Pengiriman Email Tingkat Lanjut di GitHub.

Memahami model objek email

Templat pesan JSON berikut & objek respons menunjukkan beberapa fitur utama SDK Email Azure Communication Services untuk 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.
    }
}

Nilai response.status dijelaskan lebih lanjut dalam tabel berikut.

Nama Status Deskripsi
SedangBerlangsung Operasi pengiriman email saat ini sedang berlangsung dan sedang diproses.
Berhasil Operasi pengiriman email telah selesai tanpa kesalahan dan email keluar untuk pengiriman. Setiap status terperinci tentang pengiriman email di luar tahap ini dapat diperoleh baik melalui Azure Monitor atau melalui Azure Event Grid. Pelajari cara berlangganan peristiwa email
Gagal Operasi pengiriman email tidak berhasil dan mengalami kesalahan. Email tidak dikirim. Hasilnya berisi objek kesalahan dengan detail lebih lanjut tentang alasan kegagalan.

Prasyarat

Menyelesaikan mulai cepat ini dikenakan biaya kecil kurang lebih sebanyak beberapa sen USD di akun Azure Anda.

Catatan

Kami juga dapat mengirim email dari domain terverifikasi kami sendiri. Tambahkan domain terverifikasi kustom ke Email Communication Service.

Pemeriksaan prasyarat

  • Di terminal atau jendela perintah, jalankan perintah python --version untuk memeriksa apakah Python dipasang.
  • Untuk melihat domain yang diverifikasi dengan sumber daya Email Communication Services Anda, masuk ke portal Azure. Temukan sumber daya Email Communication Services Anda dan buka tab Provisi domain dari panel navigasi kiri.

Menyiapkan lingkungan aplikasi

Untuk menyiapkan lingkungan untuk mengirim email, lakukan langkah-langkah di bagian berikut.

Membuat aplikasi Python baru

  1. Buka jendela perintah atau terminal Anda. Kemudian gunakan perintah berikut untuk membuat lingkungan virtual dan mengaktifkannya. Perintah ini membuat direktori baru untuk aplikasi Anda.

    python -m venv email-quickstart

  2. Navigasikan ke direktori akar lingkungan virtual dan aktifkan menggunakan perintah berikut.

    cd email-quickstart
.\Scripts\activate

  3. Gunakan editor teks untuk membuat file yang disebut send-email.py di direktori akar proyek dan menambahkan struktur untuk program, termasuk penanganan pengecualian dasar.

    import os
from azure.communication.email import EmailClient

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

Di bagian berikut, Anda menambahkan semua kode sumber untuk mulai cepat ini ke file send-email.py yang Anda buat.

Pasang paket

Saat masih berada di direktori aplikasi, instal paket SDK Email Azure Communication Services untuk Python dengan menggunakan perintah berikut.

pip install azure-communication-email

Membuat klien email dengan autentikasi

Ada beberapa opsi berbeda yang tersedia untuk mengautentikasi klien email:

Buat instans EmailClient dengan string koneksi Anda. Pelajari cara mengelola string koneksi sumber daya Anda.

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

Untuk kesederhanaan, mulai cepat ini menggunakan string koneksi, tetapi di lingkungan produksi, sebaiknya gunakan perwakilan layanan.

Pengiriman email dasar

Mengirim pesan email

Untuk mengirim pesan email, Anda perlu:

  • Buat pesan dengan nilai berikut:
    • senderAddress: Alamat email pengirim yang valid, ditemukan di bidang MailFrom di panel gambaran umum domain yang ditautkan ke Sumber Daya Email Communication Services Anda.
    • recipients: Objek dengan daftar penerima email, dan secara opsional, daftar penerima email CC & BCC.
    • content: Objek yang berisi subjek, dan secara opsional konten teks biasa atau HTML, dari pesan email.
  • Panggil metode begin_send, yang mengembalikan hasil operasi.
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())

Buat penggantian ini dalam kode:

  • Ganti <emailalias@emaildomain.com> dengan alamat email yang ingin Anda kirimi pesan.
  • Ganti <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> dengan alamat MailFrom domain terverifikasi Anda.

Mendapatkan status pengiriman email

Kita dapat melakukan polling untuk status pengiriman email dengan mengatur perulangan pada objek status operasi yang dikembalikan dari metode 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)

Menjalankan kode

Menjalankan aplikasi dari direktori aplikasi Anda dengan perintah python.

python send-email.py

Kode Sampel

Anda dapat mengunduh aplikasi contoh dari GitHub

Prasyarat

Kirim email

Untuk menambahkan langkah baru ke alur kerja Anda dengan menggunakan konektor Email Azure Communication Services, ikuti langkah-langkah berikut:

  1. Di perancang, buka alur kerja aplikasi logika Anda.

    Consumption

    1. Di bawah langkah di mana Anda ingin menambahkan tindakan baru, pilih Langkah baru. Atau, untuk menambahkan tindakan baru di antara langkah-langkah, pindahkan penunjuk Anda ke panah di antara langkah-langkah tersebut, pilih tanda plus (+), dan pilih Tambahkan tindakan.

    2. Di bawah kotak pencarian Pilih operasi , pilih Standar. Dalam kotak pencarian, masukkan Email Communication Services.

    3. Dari daftar tindakan, pilih Kirim email.

      Cuplikan layar yang memperlihatkan tindakan Kirim email konektor Email Azure Communication Services.

    Standard

    1. Di bawah langkah di mana Anda ingin menambahkan tindakan baru, pilih tanda plus (+). Atau, untuk menambahkan tindakan baru di antara langkah-langkah, pindahkan penunjuk Anda ke panah di antara langkah-langkah tersebut, pilih tanda plus (+), dan pilih Tambahkan tindakan.

    2. Di bagian kotak telusur Pilih operasi, pilih Azure. Dalam kotak pencarian, masukkan Email Communication Services.

    3. Dari daftar tindakan, pilih Kirim email.

  2. Masukkan nama untuk koneksi.

  3. Masukkan string koneksi untuk sumber daya Azure Communications Service Anda. Untuk menemukan string ini, ikuti langkah-langkah berikut:

    1. Di portal Azure, buka sumber daya Azure Communication Service Anda.

    2. Pada menu sumber daya, di bawah Pengaturan, pilih Kunci, dan salin string koneksi.

      Cuplikan layar yang memperlihatkan String Koneksi Azure Communication Services.

  4. Jika sudah selesai, pilih Buat.

  5. Di bidang Dari, gunakan alamat email yang Anda konfigurasi dalam prasyarat. Masukkan nilai untuk bidang Kepada, Subjek, dan Isi , misalnya:

    Cuplikan layar yang memperlihatkan konektor Email Azure Communication Services Mengirim input tindakan email.

  6. Simpan alur kerja Anda. Di bar alat perancang, pilih Simpan.

Menguji alur kerja

Berdasarkan apakah Anda memiliki alur kerja Konsumsi atau Standar, mulai alur kerja Anda secara manual:

  • Konsumsi: Pada toolbar perancang, pilih Jalankan Eksekusi Pemicu>.
  • Standar: Pada menu alur kerja, pilih Gambaran Umum. Pada toolbar, pilih Jalankan Eksekusi Pemicu>.

Alur kerja membuat pengguna, mengeluarkan token akses untuk pengguna tersebut, lalu menghapus dan menghapus pengguna. Anda dapat memeriksa output tindakan ini setelah alur kerja berhasil berjalan.

Anda harus mendapatkan email di alamat yang ditentukan. Selain itu , Anda dapat menggunakan tindakan Dapatkan status pesan email untuk memeriksa status email yang dikirim melalui tindakan Kirim email . Untuk tindakan lainnya, tinjau dokumentasi referensi konektor Email Azure Communication Services.

Membersihkan sumber daya alur kerja

Untuk membersihkan sumber daya aplikasi logika, alur kerja, dan sumber daya terkait, tinjau cara membersihkan sumber daya aplikasi logika Konsumsi atau cara membersihkan sumber daya aplikasi logika Standar.

Pemecahan Masalah

Pengiriman Email

Untuk memecahkan masalah yang terkait dengan pengiriman email, Anda bisa mendapatkan status pengiriman email untuk mengambil detail pengiriman.

Penting

Hasil keberhasilan yang dikembalikan oleh polling untuk status operasi pengiriman hanya memvalidasi fakta bahwa email telah berhasil dikirim untuk pengiriman. Untuk mendapatkan informasi tambahan tentang status pengiriman di akhir penerima, Anda harus mereferensikan cara menangani peristiwa email.

Pembatasan Email

Jika Anda melihat bahwa aplikasi Anda menggantungnya bisa disebabkan oleh pengiriman email yang dibatasi. Anda dapat menangani ini melalui pengelogan atau dengan menerapkan kebijakan kustom.

Catatan

Penyiapan kotak pasir ini untuk membantu pengembang mulai membangun aplikasi. Anda dapat secara bertahap meminta untuk meningkatkan volume pengiriman setelah aplikasi siap untuk ditayangkan. Kirim permintaan dukungan untuk menaikkan batas pengiriman yang Anda inginkan jika Anda memerlukan pengiriman volume pesan yang melebihi batas tarif.

Membersihkan sumber daya Azure Communication Service

Untuk membersihkan dan menghapus langganan Communication Services, Anda dapat menghapus grup sumber daya atau sumber daya. Menghapus grup sumber daya juga menghapus sumber daya terkait lainnya. Pelajari selengkapnya tentang membersihkan sumber daya.

Langkah berikutnya

Dalam mulai cepat ini, Anda mempelajari cara mengirim email menggunakan Azure Communication Services. Anda mungkin juga ingin: