Reach

Grow

Manage

Automate

Reach

Grow

Manage

Automate

Template Email Tingkat Lanjut

Burung

25 Mar 2016

Email

1 min read

Template Email Tingkat Lanjut

Burung

25 Mar 2016

Email

1 min read

Template Email Tingkat Lanjut

Postingan ini ditujukan kepada pengembang yang ingin memanfaatkan kemampuan template email SparkPost secara maksimal. Diasumsikan Anda nyaman membaca konten JSON dan mengikuti alur pemrograman dasar. Ketika istilah yang mungkin baru bagi Anda diperkenalkan seperti RFC 5322, teks tersebut terhubung ke referensi sumbernya.

Business in a box.

Temukan solusi kami.

Posting ini ditujukan untuk pengembang yang ingin mendapatkan hasil maksimal dari kemampuan template email SparkPost. Diasumsikan bahwa Anda merasa nyaman membaca konten JSON dan mengikuti alur pemrograman dasar. Sebagai istilah yang mungkin baru bagi Anda diperkenalkan seperti RFC 5322, teks terhubung ke referensi sumbernya. Setelah itu, mari kita langsung terjun.

Kemampuan template dan transmisi SparkPost membuat pengiriman email menjadi mudah. Kemampuan tersebut menyediakan abstraksi untuk konten teks dan HTML yang berarti sebagian besar waktu tidak perlu langsung mengkodekan format email mentah yang didefinisikan dalam RFC 5322 yang sebelumnya dikenal sebagai (RFC 822). Namun terkadang Anda mungkin ingin membuat pesan yang lebih kompleks yang memiliki bagian Ekstensi Email Internet Multipurpose (MIME) lainnya yang tidak langsung terungkap melalui antarmuka RESTful SparkPost.

Penyusunan Email yang Disederhanakan

Pertama, mari kita tinjau skenario hari cerah untuk mengirim email. Gunakan endpoint transmisi untuk menyediakan teks dan konten HTML. Di balik layar, SparkPost menangani penyusunan email RFC 5322 yang valid. SparkPost akan memasukkan variabel substitusi dari substitution_data ke dalam teks dan konten HTML. Ini adalah cara yang ampuh untuk menghasilkan konten khusus untuk setiap penerima dalam template umum.

Berikut adalah contoh transmisi dengan konten HTML dan teks dengan substitution_data.

{
  "options": {
    "open_tracking": true,
    "click_tracking": true
  },
  "campaign_id": "christmas_campaign",
  "return_path": "bounces-christmas-campaign@domain.com",
  "metadata": {
    "user_type": "students"
  },
  "substitution_data": {
    "sender": "Big Store Team"
  },
  "recipients": [
    {
      "return_path": "123@bounces.domain.com",
      "address": {
        "email": "wilma@domain.com",
        "name": "Wilma Flintstone"
      },
      "tags": [
        "greeting",
        "prehistoric",
        "fred",
        "flintstone"
      ],
      "metadata": {
        "place": "Bedrock"
      },
      "substitution_data": {
        "customer_type": "Platinum"
      }
    }
  ],
  "content": {
    "from": {
      "name": "Fred Flintstone",
      "email": "fred@domain.com"
    },
    "subject": "Big Christmas savings!",
    "reply_to": "Christmas Sales <sales@domain.com>",
    "headers": {
      "X-Customer-Campaign-ID": "christmas_campaign"
    },
    "text": "Hi {{address.name}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get huge discount\n Hurry, this offer is only to {{user_type}}\n {{sender}}",
    "html": "<p>Hi {{address.name}} <br>Save big this Christmas in your area {{place}}! <br>Click <a href=\"http://www.mysite.com\">here</a> and get huge discount</p><p>Hurry, this offer is only to {{user_type}}</p><p>{{sender}}</p>"
  }
}

Substitusi Array Data

Banyak orang menyadari bahwa endpoint transmisi dan template SparkPost dapat melakukan substitusi konten sederhana di header email dan badan email. Namun banyak yang mengabaikan kemampuan untuk menyediakan konten bersyarat atau array data yang dapat disubstitusi juga. Anda juga dapat menyediakan konten unik per penerima. Dalam contoh ini kami mengirimkan array tautan unik kepada setiap penerima.

Ini dicapai dengan menyediakan array data JSON yang akan dimasukkan ke dalam badan email. Setelah data disediakan, SparkPost akan menggunakan logika dalam template untuk mengisinya.

Dalam contoh ini SparkPost akan mencari data substitusi yang disebut "files_html" dan melakukan "for each" pada setiap elemen dalam array. Ini akan membuat baris dengan nilai "file" dalam elemen "files_html". Perhatikan triple curly di sekitar "loop_var.file". Ini karena setiap elemen dari array berisi HTML dan kita perlu memberi tahu server untuk menggunakannya apa adanya dan tidak menggunakannya sebagai teks yang dihindari. Bagian teks akan menjadi label teks sederhana dan URL ke file.

<table>
  {{each files_html}}
    <tr>
      <td>{{{loop_var.file}}}</td>
    </tr>
  {{ end }}
</table>

Berikut adalah contoh cara kerjanya:

{
  "recipients": [
    {
      "address": {
        "email": "recipient1@domain.com"
      },
      "substitution_data": {
        "files_html": [
          {
            "file": "<a href=\"http://domain.com/file1a.txt\">File 1a Description</a>"
          },
          {
            "file": "<a href=\"http://domain.com/file2a.txt\">File 2a Description</a>"
          }
        ],
        "files_plain": [
          {
            "file": "File 1a -- http://domain.com/file1a.txt"
          },
          {
            "file": "File 2a -- http://domain.com/file2a.txt"
          }
        ]
      }
    },
    {
      "address": {
        "email": "recipient2@domain.com"
      },
      "substitution_data": {
        "files_html": [
          {
            "file": "<a href=\"http://domain.com/file1b.txt\">File 1b Description</a>"
          },
          {
            "file": "<a href=\"http://domain.com/file2b.txt\">File 2b Description</a>"
          }
        ],
        "files_plain": [
          {
            "file": "File 1b -- http://domain.com/file1b.txt"
          },
          {
            "file": "File 2b -- http://domain.com/file2b.txt"
          }
        ]
      }
    }
  ],
  "return_path": "chris@test.domain.com",
  "content": {
    "from": {
      "name": "chris@test.domain.com",
      "email": "chris@test.domain.com"
    },
    "subject": "Sending with SparkPost is Fun",
    "html": "<b>Your Files:</b><br>\n<table>\n  {{each files_html}}\n    <tr><td>{{{loop_var.file}}}</td></tr>\n  {{ end }}\n</table>\n",
    "text": "Your Files:\n{{each files_plain}} {{loop_var.file}}\n{{ end }}\n"
  }
}

Tips Profesional: Dalam kode Anda sebaiknya memisahkan markup tampilan dari data namun tujuan di sini adalah untuk membuat contoh sesederhana dan semudah mungkin diikuti sehingga kami membuat dua array. Satu array untuk bagian HTML dan satunya untuk bagian Teks. Dalam penggunaan produksi biasa memiliki satu set data dan menulis logika dalam kode template.

Lampiran dalam Kemampuan Transmisi

Endpoint transmisi juga menyediakan abstraksi untuk mengirim lampiran. Di bawah ini Anda akan melihat lampiran ditentukan dalam array content.attachments di mana setiap objek dalam array menggambarkan item lampiran individu. Sama seperti sebelumnya, SparkPost akan mengurus pengkodean teks, HTML, substitusi dan iterasi melalui array lampiran untuk mengkodekan pesan email yang terbentuk dengan baik.

Praktik terbaik menunjukkan bahwa mengirim lampiran sebaiknya dihindari kecuali benar-benar diperlukan sebagai bagian dari layanan Anda.

Berikut adalah bidang yang diperlukan untuk lampiran:

  • type: Jenis MIME dari lampiran

  • name: Nama file dari lampiran

  • data: Data file yang dikodekan Base64

Ini adalah tampilan lampiran di dalam bagian transmisi konten:

"content": {
  "attachments": [
    {
      "type": "audio/mp3",
      "name": "voicemail.mp3",
      "data": "TVAzIERhdGEK"
    }
  ]
}

Anda juga dapat mengirim "gambar inline" dalam transmisi. Ini sangat mirip dengan lampiran dan ditentukan dalam array content.inline_images di mana setiap objek inline_image mirip dengan objek lampiran yang ditunjukkan di atas.

Lampiran dalam Template

Sekarang setelah kita memiliki latar belakang yang tepat untuk mengirim lampiran dengan endpoint transmisi, mari kita lihat bagaimana melakukannya dengan template. Pada saat penulisan ini, tidak ada abstraksi lampiran seperti yang Anda temukan untuk transmisi inline. Satu mungkin menyimpulkan bahwa template tidak dapat dibuat dengan lampiran. Anda benar sebagian, tetapi ada solusi, meskipun Anda tidak akan lagi terisolasi dari format RFC 5322.

Anda dapat mencapai lampiran dalam template dengan mengodekan sendiri konten RFC 5322 yang mencakup lampiran. Kabar baiknya adalah Anda tidak akan kehilangan kemampuan untuk tetap menggunakan Substitution Data di header email, bagian HTML, dan bagian teks. Harap dicatat bahwa jenis template ini membatasi substitusi untuk header dan bagian pertama HTML dan teks pertama.

Berikut adalah contoh cara melakukannya.

Email RFC822

Buat email RFC 5322 Anda dengan data substitusi yang diinginkan. Saya membuatnya di klien email saya dan mengirimkannya pada diri saya sendiri. Setelah menerimanya, saya menyalin sumbernya dan mengganti bidang yang ingin saya substitusi secara dinamis.

MIME-Version: 1.0
Reply-To: {{replyto}}
Subject: {{subject}}
From: {{from}}
To: {{address.email}}
Content-Type: multipart/mixed; boundary="001a113c48b0b89d92052d3051da"
--001a113c48b0b89d92052d3051da
Content-Type: multipart/alternative; boundary="001a113c48b0b89d89052d3051d8"
--001a113c48b0b89d89052d3051d8
Content-Type: text/plain; charset=UTF-8
Email with a *text attachment*.
{{body2}}
--001a113c48b0b89d89052d3051d8
Content-Type: text/html; charset=UTF-8
<div dir="ltr">
  <div>Email with a <i>text attachment</i>.</div>
  {{body1}}
<

Bagian MIME terakhir dalam pesan ini Anda akan melihat Content-Disposition: lampiran; filename=myfile.txt”. Di situlah nama file didefinisikan. Konten lampiran Anda kemungkinan besar jauh lebih kompleks namun contoh ini mencoba untuk menyederhanakannya.

Template Tersimpan

Setelah Anda memiliki email RFC 5322 yang valid, simpan dengan menggunakan bentuk email_rfc822 dari endpoint template alih-alih menggunakan bidang teks dan HTML. Berikut adalah contoh tampilan konten untuk pesan itu:

{
  "content": {
    "email_rfc822": "MIME-Version: 1.0\nReply-To: {{replyto}}\nSubject: {{subject}}\nFrom: {{from}}\nTo: {{address.email}}\nContent-Type: multipart/mixed; boundary=001a113c48b0b89d92052d3051da\n\n--001a113c48b0b89d92052d3051da\nContent-Type: multipart/alternative; boundary=001a113c48b0b89d89052d3051d8\n\n--001a113c48b0b89d89052d3051d8\nContent-Type: text/plain; charset=UTF-8\n\nEmail with a *text attachment*.\n\n{{body2}}\n\n--001a113c48b0b89d89052d3051d8\nContent-Type: text/html; charset=UTF-8\n\n<div dir=\"ltr\"><div>Email with a <i>text attachment</i>.</div>\n\n{{body1}}\n</div>\n\n--001a113c48b0b89d89052d3051d8--\n--001a113c48b0b89d92052d3051da\nContent-Type: text/plain; charset=US-ASCII; name=\"myfile.txt\"\nContent-Disposition: attachment; filename=\"myfile.txt\"\nContent-Transfer-Encoding: base64\nX-Attachment-Id: f_ild455ce0\n\nVGhpcyBpcyBteSBzaW1wbGUgdGV4dCBmaWxlLgo=\n--001a113c48b0b89d92052d3051da--"
  },
  "name": "_TMP_TEMPLATE_TEST"
}

Ketika permintaan selesai, SparkPost akan merespons dengan pengenal unik untuk template baru Anda. Sebagai contoh xxxxxxx.

Mengirimkan Template

Kabar baiknya adalah bahwa membuat konten RFC 5322 adalah bagian tersulit. Dari sini seterusnya, mengirim template itu dengan SparkPost sama saja seperti mengirimkan template lain.

Berikut adalah cara kami mengirimkan template tersebut dan mengisi data substitusi:

{
  "campaign_id": "MyCampaign",
  "return_path": "myReturnPath@yourdomain.com",
  "substitution_data": {
    "replyto": "myReplyToh@yourdomain.com",
    "from": "MyFrom@yourdomain.com",
    "subject": "my subject",
    "body1": "Extra content for the HTML part",
    "body2": "Extra content for the text part"
  },
  "recipients": [
    {
      "substitution_data": {},
      "address": {
        "email": "test1@domain.com",
        "name": "test1"
      }
    }
  ],
  "content": {
    "template_id": "xxxxxxx",
    "use_draft_template": true
  }
}

Template dari API Klien Mail

Jika Anda menggunakan bahasa pemrograman yang memiliki pustaka untuk menyusun email, Anda dapat menggunakannya untuk membuat template secara programatis atau bahkan mengirim pesan inline. Di sini adalah contoh penggunaan JavaMail untuk melakukan hal itu melalui endpoint transmisi SparkPost. Metode ini harus mudah diterjemahkan ke PHP atau bahasa pilihan Anda.

/**
 * Demonstration of using JavaMail MIME message with the SparkPost RESTful interface
 */
public class App extends SparkPostBaseApp {
    public static void main(String[] args) throws Exception {
        Logger.getRootLogger().setLevel(Level.DEBUG);
        App app = new App();
        app.runApp();
    }
    private void runApp() throws Exception {
        Message message = createMultipartMessage();
        // Convert JavaMail message into a string for transmission
        String rfc822Content = getMessageAsString(message);
        // Add dynamic To and From using SparkPost substitution syntax
        rfc822Content = "To: {{address.email}}\r\nFrom: {{from}}\r\n" + rfc822Content;
        String fromAddress = getFromAddress();
        String[] recipients = getTestRecipients();
        sendEmail(fromAddress, recipients, rfc822Content);
    }
    private void sendEmail(String from, String[] recipients, String email)
            throws SparkPostException, IOException {
        Client sparkpostClient = newConfiguredClient();
        TransmissionWithRecipientArray transmission = new TransmissionWithRecipientArray();
        // Populate Recipients
        List<RecipientAttributes> recipientArray = new ArrayList<>();
        for (String recipient : recipients) {
            RecipientAttributes recipientAttribs = new RecipientAttributes();
            recipientAttribs.setAddress(new AddressAttributes(recipient));
            recipientArray.add(recipientAttribs);
        }
        transmission.setRecipientArray(recipientArray);
        transmission.setReturnPath(from);
        // Populate Substitution Data
        Map<String, String> substitutionData = new HashMap<>();
        substitutionData.put("from", from);
        substitutionData.put("name", "Your Name Here");
        transmission.setSubstitutionData(substitutionData);
        // Populate Email Body with RFC822 MIME
        TemplateContentAttributes contentAttributes = new TemplateContentAttributes();
        contentAttributes.setEmailRFC822(email);
        transmission.setContentAttributes(contentAttributes);
        // Send Email
        RestConnection connection = new RestConnection(sparkpostClient, getEndPoint());
        Response response = ResourceTransmissions.create(connection, 0, transmission);
        if (response.getResponseCode() == 200) {
            System.out.println("✅ Transmission Response: " + response);
        } else {
            System.err.println("❌ TRANSMISSION ERROR: " + response);
        }
    }
    /**
     * Builds an email with text, HTML, and attachment parts
     */
    private Message createMultipartMessage() throws MessagingException {
        Properties props = new Properties();
        props.put("mail.smtp.host", "none"); // Required for JavaMail to work
        Session session = Session.getDefaultInstance(props, null);
        Message message = new MimeMessage(session);
        message.setSubject("A multipart MIME message demo");
        // Main multipart container
        Multipart multiPart = new MimeMultipart("mixed");
        // Sub multipart for text + HTML
        MimeMultipart altPart = new MimeMultipart("alternative");
        // Text part
        MimeBodyPart textPart = new MimeBodyPart();
        textPart.setText("{{name}},\r\nplain text content", "utf-8");
        // HTML part
        MimeBodyPart htmlPart = new MimeBodyPart();
        htmlPart.setContent("<b>{{name}},<br><br>Our HTML content</b>", "text/html; charset=utf-8");
        // Add text and HTML to the alternative container
        altPart.addBodyPart(textPart);
        altPart.addBodyPart(htmlPart);
        // Wrap alternative part in a MimeBodyPart so it can be added to mixed container
        MimeBodyPart altBodyPart = new MimeBodyPart();
        altBodyPart.setContent(altPart);
        // Add alternative section to mixed container
        multiPart.addBodyPart(altBodyPart);
        // Add attachment
        MimeBodyPart attachmentPart = new MimeBodyPart();
        String filename = "java_SparkPost_background.pdf";
        DataSource source = new FileDataSource(filename);
        attachmentPart.setDataHandler(new DataHandler(source));
        attachmentPart.setFileName(filename);
        multiPart.addBodyPart(attachmentPart);
        // Set full content
        message.setContent(multiPart);
        return message;
    }
    /**
     * Converts a JavaMail message into an RFC822 string
     */
    private String getMessageAsString(Message msg) throws IOException, MessagingException {
        ByteArrayOutputStream out = new ByteArrayOutputStream();
        try {
            msg.writeTo(out);
            return out.toString("UTF-8");
        } catch (UnsupportedEncodingException e) {
            throw new RuntimeException("UTF-8 not found! " + e.getMessage());
        } finally {
            try {
                out.close();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }
}

Kesimpulan

Sekarang setelah Anda melihat bagaimana SparkPost dapat digunakan untuk mengirim email dengan hampir semua kompleksitas, Anda mungkin ingin melihat "SparkPost Mendukung Pengiriman Email pada Apple Watch" atau melihat sintaks substitusi untuk melihat bagaimana itu dapat digunakan dengan "jika maka sebaliknya", "ekspresi dalam kondisional" atau "Iterasi array" langsung di dalam konten template atau transmisi Anda.

Mari hubungkan Anda dengan pakar Bird.
Lihat kekuatan penuh dari Bird dalam 30 menit.

Dengan mengirimkan, Anda setuju Bird dapat menghubungi Anda tentang produk dan layanan kami.

Anda dapat berhenti berlangganan kapan saja. Lihat Pernyataan Privasi Bird untuk detail tentang pemrosesan data.

Perusahaan

Newsletter

Tetap terinformasi dengan Bird melalui pembaruan mingguan ke kotak masuk Anda.

Mari hubungkan Anda dengan pakar Bird.
Lihat kekuatan penuh dari Bird dalam 30 menit.

Dengan mengirimkan, Anda setuju Bird dapat menghubungi Anda tentang produk dan layanan kami.

Anda dapat berhenti berlangganan kapan saja. Lihat Pernyataan Privasi Bird untuk detail tentang pemrosesan data.

Perusahaan

Newsletter

Tetap terinformasi dengan Bird melalui pembaruan mingguan ke kotak masuk Anda.

Mari hubungkan Anda dengan pakar Bird.
Lihat kekuatan penuh dari Bird dalam 30 menit.

Dengan mengirimkan, Anda setuju Bird dapat menghubungi Anda tentang produk dan layanan kami.

Anda dapat berhenti berlangganan kapan saja. Lihat Pernyataan Privasi Bird untuk detail tentang pemrosesan data.

R

Reach

G

Grow

M

Manage

A

Automate

Perusahaan

Newsletter

Tetap terinformasi dengan Bird melalui pembaruan mingguan ke kotak masuk Anda.