Product

Solusi

Sumber Daya

Company

Product

Solusi

Sumber Daya

Company

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 memanfaatkan sepenuhnya kemampuan template email SparkPost. Diasumsikan Anda sudah nyaman membaca konten JSON dan mengikuti alur pemrograman dasar. Ketika istilah-istilah baru bagi Anda diperkenalkan seperti RFC 5322, teks akan terhubung ke referensi sumbernya. Dengan menjelaskan hal tersebut, mari langsung lompat masuk.

Kemampuan template dan transmission SparkPost membuat pengiriman email menjadi sederhana. Kemampuan ini menyediakan abstraksi untuk konten text dan HTML yang berarti kebanyakan waktu tidak perlu secara langsung meng-encode format email mentah yang didefinisikan dalam RFC 5322 yang sebelumnya dikenal dengan (RFC 822). Namun terkadang Anda mungkin ingin membuat pesan yang lebih kompleks dengan bagian Multipurpose Internet Mail Extensions (MIME) lain yang tidak langsung diekspos melalui antarmuka RESTful SparkPost.

Penyusunan Email yang Disederhanakan

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

Berikut adalah contoh transmission 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>"
  }
}

Subsitusi Array Data

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

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

Dalam contoh ini SparkPost akan mencari data substitusi bernama “files_html” dan melakukan “for each” pada setiap elemen dalam array. Ini akan membuat baris dengan nilai dari “file” dalam elemen “files_html”. Perhatikan tanda kurung kurawal tiga kali 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 mengeskapnya. Bagian teks akan berupa label teks sederhana dan URL ke file.

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

Berikut adalah contoh kerja yang telah selesai:

{
  "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"
  }
}

Pro Tip: Dalam kode Anda, disarankan untuk menyimpan markup tampilan terpisah dari data tetapi tujuannya di sini adalah untuk menjaga contoh semudah dan sejelas mungkin sehingga kami membuat dua array. Satu array untuk bagian HTML dan yang lainnya untuk bagian Teks. Dalam penggunaan produksi akan umum untuk memiliki satu set data dan menulis logika dalam kode template.

Lampiran dalam Kemampuan Pengiriman

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 meng-encode text, HTML, substitutions dan iterasi melalui array lampiran untuk meng-encode pesan email yang terbentuk dengan baik.

Praktik terbaik menyarankan bahwa pengiriman lampiran sebaiknya dihindari kecuali secara eksplisit diperlukan sebagai bagian dari layanan Anda.

Di bawah ini adalah bidang yang diperlukan untuk lampiran:

  • type: Jenis MIME dari lampiran

  • name: Nama file dari lampiran

  • data: Data file yang telah di-encode menggunakan Base64

Beginilah tampilan lampiran di dalam stanza konten transmisi:

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

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

Lampiran dalam Templates

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

Anda dapat mencapainya dengan meng-encode konten RFC 5322 Anda sendiri yang meliputi lampiran. Kabar baiknya adalah Anda tidak akan kehilangan kemampuan untuk tetap menggunakan Substitution Data dalam email headers, HTML, dan bagian text Anda. Harap perhatikan bahwa jenis template ini membatasi substitusi pada headers dan bagian HTML pertama dan bagian text pertama.

Berikut adalah contoh cara melakukannya.

Email RFC822

Buat email RFC 5322 Anda dengan data substitusi yang Anda inginkan. Saya membuat yang ini di klien email saya dan mengirimkannya ke diri saya sendiri. Begitu saya menerimanya, saya menyalin sumber 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: attachment; filename=myfile.txt”. Di situlah nama file ditentukan. Konten lampiran Anda tentu saja akan jauh lebih kompleks tetapi contoh ini mencoba menjaga agar tetap sederhana.

Stored Template

Begitu Anda memiliki email RFC 5322 yang valid, simpanlah menggunakan form email_rfc822 dari endpoint template bukan menggunakan bidang text dan HTML. Berikut adalah contoh bagaimana content terlihat untuk pesan tersebut:

{
  "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. Misalnya xxxxxxx.

Mengirim Template

Kabar baiknya adalah membuat konten RFC 5322 adalah bagian yang sulit. Dari sini seterusnya mengirimkan template tersebut dengan SparkPost persis sama seperti mengirimkan template lainnya.

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 Email

Jika Anda menggunakan bahasa pemrograman yang memiliki pustaka untuk menyusun email, Anda dapat menggunakan itu untuk secara programatik membuat template atau bahkan mengirim pesan secara inline. Berikut adalah contoh menggunakan JavaMail 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 kerumitan, Anda mungkin ingin melihat "SparkPost Supports Sending Email on Apple Watch" atau melihat substitution syntax untuk melihat bagaimana itu dapat digunakan dengan "if then else", "ekspresi dalam kondisi" atau "Iterasi array" langsung di dalam template atau konten transmisi Anda.

A person is standing at a desk while typing on a laptop.

Platform AI-native lengkap yang dapat beradaptasi dengan pertumbuhan bisnis Anda.

Product

Solusi

Sumber Daya

Company

Pengaturan privasi

Segera hadir

Sosial

Newsletter

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

Daftar

© 2025 Bird

A person is standing at a desk while typing on a laptop.

Platform AI-native lengkap yang dapat beradaptasi dengan pertumbuhan bisnis Anda.

Product

Solusi

Sumber Daya

Company

Pengaturan privasi

Sosial

Newsletter

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

Daftar

© 2025 Bird