Ten post jest skierowany do deweloperów, którzy chcą jak najlepiej wykorzystać możliwości szablonów e-mail SparkPost. Zakłada się, że jesteś zaznajomiony z czytaniem treści JSON i śledzeniem podstawowego przepływu programowania. Gdy wprowadzane są terminy, które mogą być dla Ciebie nowe, takie jak RFC 5322, tekst jest połączony z jego źródłem. Z tym już za nami, przejdźmy do rzeczy.
Możliwości szablonów i transmisji SparkPost sprawiają, że wysyłanie e-maili jest proste. Te możliwości zapewniają abstrakcję dla treści tekstowej i HTML, co oznacza, że w większości przypadków nie ma potrzeby bezpośredniego kodowania surowego formatu e-mail, który jest zdefiniowany w RFC 5322, wcześniej znanym jako (RFC 822). Ale czasami możesz chcieć stworzyć bardziej złożone wiadomości, które mają inne elementy Multipurpose Internet Mail Extensions (MIME), które nie są bezpośrednio ujawnione przez interfejs RESTful SparkPost.
Uproszczone Tworzenie E-maili
Najpierw przeanalizujmy scenariusz w słoneczny dzień, aby wysłać e-mail. Użyj punktu końcowego transmisji, aby dostarczyć tekst i treść HTML. W tle SparkPost zajmuje się tworzeniem prawidłowego e-maila zgodnego z RFC 5322. SparkPost wstawi zmienne substytucji z substitution_data do treści tekstowej i HTML. To potężna metoda generowania spersonalizowanej treści dla każdego odbiorcy w wspólnym szablonie.
Oto przykładowa transmisja z treścią HTML i tekstową z danymi substytucji.
{
"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>"
}
}
Zastępowanie Tablic Danych
Wielu ludzi zdaje sobie sprawę, że punkty końcowe transmisji i szablonów SparkPost mogą wykonywać prostą substytucję treści w nagłówkach e-maili i treściach e-maili. Ale wiele osób przeocza zdolność do dostarczania warunkowej treści lub tablic danych, które mogą być również zastępowane. Możesz także dostarczyć unikalną treść dla każdego odbiorcy. W tym przykładzie wysyłamy tablicę unikalnych linków do każdego odbiorcy.
Osiąga się to poprzez dostarczenie tablicy JSON danych, która zostanie umieszczona w treści e-maila. Gdy dane zostaną dostarczone, SparkPost użyje logiki w szablonie, aby je umieścić.
W tym przykładzie SparkPost będzie szukać danych substytucji o nazwie „files_html” i wykona „dla każdego” na każdym elemencie tablicy. Utworzy wiersz z wartością „file” w elemencie „files_html”. Zauważ potrójne nawiasy klamrowe wokół „loop_var.file“. Jest to dlatego że każdy element tablicy zawiera HTML i musimy powiedzieć serwerowi, aby używał go tak, jak jest, i nie maskował go. Część tekstowa będzie prostą etykietą tekstową i adresem URL do pliku.
<table>
{{each files_html}}
<tr>
<td>{{{loop_var.file}}}</td>
</tr>
{{ end }}
</table>
Oto ukończony działający przykład:
{
"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: W Twoim kodzie zaleca się oddzielić znacznik widoku od danych, ale celem tutaj było utrzymanie przykładu tak prostym i łatwym do zrozumienia, jak to możliwe, więc stworzyliśmy dwie tablice. Jedna tablica jest dla części HTML, a druga dla części Tekstowej. W produkcji byłoby to powszechne, aby mieć jeden zestaw danych i pisać logikę w kodzie szablonu.
Załączniki w Możliwosciach Transmisji
Punkt końcowy transmisji zapewnia również abstrakcję do wysyłania załączników. Poniżej zobaczysz, że załączniki są określone w tablicy content.attachments, gdzie każdy obiekt w tablicy opisuje pojedynczy element załącznika. Tak jak wcześniej, SparkPost zajmie się kodowaniem tekst, HTML, substytucji oraz przeglądaniem tablicy załączników, aby zakodować poprawnie sformułowaną wiadomość e-mail.
Dobre praktyki sugerują, że wysyłanie załączników najlepiej unikać, chyba że jest to wyraźnie wymagane jako część Twojej usługi.
Poniżej znajdują się wymagane pola dla załącznika:
type: Typ MIME załącznika
name: Nazwa pliku załącznika
data: Dane pliku zakodowane w Base64
Tak wygląda załącznik w wezwaniu do transmisji:
"content": {
"attachments": [
{
"type": "audio/mp3",
"name": "voicemail.mp3",
"data": "TVAzIERhdGEK"
}
]
}
Możesz także wysyłać „obrazy inline” w transmisji. Są one bardzo podobne do załączników i są określone w tablicy content.inline_images, gdzie każde z obiektów inline_image są podobne do pokazanego wcześniej obiektu załącznika.
Załączniki w Szablonach
Teraz, gdy mamy odpowiednie tło dotyczące wysyłania załączników za pomocą punktu końcowego transmisji, przyjrzyjmy się, jak to zrobić za pomocą szablonów. W chwili pisania tego artykułu nie ma abstrakcji załączników, jaką można znaleźć dla inline transmisji. Można by wywnioskować, że szablonów nie można tworzyć z załącznikami. Byłbyś częściowo poprawny, ale istnieje rozwiązanie, choć nie będziesz już odizolowany od formatu RFC 5322.
Możesz wykonać załączniki w szablonach, kodując samą treść RFC 5322, która zawiera załączniki. Dobrą wiadomością jest to, że nadal nie tracisz zdolności do korzystania z Substitution Data w nagłówkach e-maili, częściach HTML i tekstowych. Pamiętaj, że tego rodzaju szablon ogranicza substytucje do nagłówków i pierwszej części HTML oraz pierwszej części tekstowej.
Oto przykład, jak to się robi.
RFC822 E-mail
Utwórz swój e-mail RFC 5322 z danymi substytucji, które chcesz. Stworzyłem to w moim kliencie poczty i wysłałem do siebie. Po otrzymaniu skopiowałem źródło i zastąpiłem pola, które chcę dynamicznie zamienić.
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}}
<
W ostatniej części MIME tej wiadomości zobaczysz Content-Disposition: attachment; filename=myfile.txt”. Tam określa się nazwę pliku. Twoja zawartość załącznika z pewnością będzie znacznie bardziej złożona, ale ten przykład stara się go utrzymać prostym.
Przechowywany Szablon
Gdy już masz poprawny e-mail RFC 5322, przechowaj go, używając formularza email_rfc822 punktu końcowego szablonu, zamiast używać pól tekstu i HTML. Oto przykład, jak wygląda content dla tej wiadomości:
{
"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"
}
Gdy żądanie zostanie ukończone, SparkPost odpowie z unikalnym identyfikatorem dla Twojego nowego szablonu. Na przykład xxxxxxx.
Wysyłanie Szablonu
Dobrą wiadomością jest to, że stworzenie treści RFC 5322 było trudną częścią. Od teraz wysyłanie tego szablonu przy użyciu SparkPost jest dokładnie takie samo jak wysyłanie dowolnego innego szablonu.
Oto jak wysyłamy ten szablon i wypełniamy dane substytucji:
{
"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
}
}
Szablony z API Klienta Poczty
Jeśli używasz języka programowania, który ma bibliotekę do tworzenia e-maili, możesz jej użyć do programowego tworzenia szablonu lub nawet wysłania wiadomości inline. Tutaj znajdziesz przykład użycia JavaMail do zrobienia tego przez punkt końcowy transmisji SparkPost. Ta metoda powinna być łatwo przetłumaczona na PHP lub inny język, który preferujesz.
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();
String rfc822Content = getMessageAsString(message);
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();
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);
Map<String, String> substitutionData = new HashMap<>();
substitutionData.put("from", from);
substitutionData.put("name", "Your Name Here");
transmission.setSubstitutionData(substitutionData);
TemplateContentAttributes contentAttributes = new TemplateContentAttributes();
contentAttributes.setEmailRFC822(email);
transmission.setContentAttributes(contentAttributes);
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);
}
}
private Message createMultipartMessage() throws MessagingException {
Properties props = new Properties();
props.put("mail.smtp.host", "none");
Session session = Session.getDefaultInstance(props, null);
Message message = new MimeMessage(session);
message.setSubject("A multipart MIME message demo");
Multipart multiPart = new MimeMultipart("mixed");
MimeMultipart altPart = new MimeMultipart("alternative");
MimeBodyPart textPart = new MimeBodyPart();
textPart.setText("{{name}},\r\nplain text content", "utf-8");
MimeBodyPart htmlPart = new MimeBodyPart();
htmlPart.setContent("<b>{{name}},<br><br>Our HTML content</b>", "text/html; charset=utf-8");
altPart.addBodyPart(textPart);
altPart.addBodyPart(htmlPart);
MimeBodyPart altBodyPart = new MimeBodyPart();
altBodyPart.setContent(altPart);
multiPart.addBodyPart(altBodyPart);
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);
message.setContent(multiPart);
return message;
}
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();
}
}
}
}
Podsumowanie
Teraz, gdy widzisz, jak SparkPost może zostać użyty do wysyłania e-maili o niemal dowolnym poziomie złożoności, możesz chcieć przyjrzeć się „SparkPost Supports Sending Email on Apple Watch” lub zapoznać się z składnią zamiany, zobaczyć, jak można ją wykorzystać z „if then else”, „wyrażeniami w warunkach” lub „iteracją tablicy” wewnątrz Twojej treści szablonu lub transmisji.
