Deze post is gericht aan de ontwikkelaar die het meeste uit SparkPost’s e-mail sjabloonmogelijkheden wil halen. Er wordt aangenomen dat je vertrouwd bent met het lezen van JSON-inhoud en het volgen van basis programmeerstromen. Aangezien termen die misschien nieuw voor je zijn zoals RFC 5322 worden geïntroduceerd, is de tekst gekoppeld aan de bronvermelding. Nu dat uit de weg is, laten we er meteen inspringen.
SparkPost’s sjabloon en verzendmogelijkheden maken het verzenden van e-mails eenvoudig. Die mogelijkheden bieden een abstractie voor tekst en HTML-inhoud, wat betekent dat er meestal geen noodzaak is om het ruwe e-mailformaat dat is gedefinieerd in RFC 5322, voorheen bekend als (RFC 822), direct te coderen. Maar soms wil je misschien complexere berichten maken die andere Multipurpose Internet Mail Extensions (MIME) delen bevatten die niet direct worden blootgesteld via de RESTful interface van SparkPost.
Vereenvoudigde E-mailmoderatie
Laten we eerst een scenario met zonneschijn bekijken voor het verzenden van een e-mail. Gebruik het transmissie eindpunt om de tekst
en HTML inhoud te verzorgen. Achter de schermen zorgt SparkPost voor het samenstellen van een geldige RFC 5322 e-mail. SparkPost zal substitutievormen invoegen van substitution_data in de tekst- en HTML-inhoud. Dit is een krachtige manier om aangepaste inhoud te genereren voor elke ontvanger in een gemeenschappelijk sjabloon.
Hier is een voorbeeld transmissie met HTML en tekstinhoud met 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>"
}
}
Substitutie Arrays van Gegevens
Veel mensen realiseren zich dat de transmissie- en sjabloon eindpunten van SparkPost eenvoudige inhoud substitutie kunnen doen in e-mailheaders en e-mailteksten. Maar velen overzien het vermogen om conditionele inhoud of gegevensarrays te bieden die ook kunnen worden vervangen. Je kunt ook unieke inhoud per ontvanger bieden. In dit voorbeeld sturen we een array van unieke links naar elke ontvanger.
Dit wordt bereikt door een JSON-array met gegevens te verstrekken die in de e-mailtekst zal worden geplaatst. Zodra de gegevens zijn verstrekt, zal SparkPost de logica in het sjabloon gebruiken om het in te vullen.
In dit voorbeeld zal SparkPost op zoek gaan naar substitutiegegevens genaamd “files_html” en een “for each” uitvoeren op elk element in de array. Het zal een rij maken met de waarde van “bestand” in het “files_html” element. Let op de driedubbele krul rond “loop_var.file“. Dit komt omdat elk element van de array HTML bevat en we de server moeten vertellen het te gebruiken zoals het is en niet te ontsnappen. De tekstgedeelte zal een eenvoudig tekstlabel en de URL naar het bestand zijn.
<table>
{{each files_html}}
<tr>
<td>{{{loop_var.file}}}</td>
</tr>
{{ end }}
</table>
Hier is het voltooide werkende voorbeeld:
{
"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: In je code is het raadzaam om de weergave-opmaak gescheiden te houden van de gegevens, maar het doel hier was om het voorbeeld zo eenvoudig en gemakkelijk mogelijk te maken, dus we hebben twee arrays gemaakt. Eén array is voor het HTML-deel en de andere voor het Tekstdeel. In productie zou het gebruikelijk zijn om één set gegevens te hebben en de logica in de sjablooncode te schrijven.
Bijlagen in Transmissie-Mogelijkheden
Het transmissie-eindpunt biedt ook een abstractie voor het verzenden van bijlagen. Hieronder zie je dat bijlagen worden gespecificeerd in de content.attachments array waar elk object in de array een individuele bijlage-eenheid beschrijft. Net als voorheen zorgt SparkPost voor het coderen van tekst, HTML, vervangingen en het doorlopen van de bijlagen array om een correct gevormd e-mailbericht te coderen.
Best practices dicteren dat het verzenden van bijlagen het beste vermeden kan worden tenzij expliciet vereist als onderdeel van je service.
Hieronder staan de vereiste velden voor een bijlage:
type: Het MIME-type van de bijlage
naam: De bestandsnaam van de bijlage
data: Base64-gecodeerde bestandgegevens
Dit is hoe een bijlage eruitziet binnen een transmissie inhoudspassage:
"content": {
"attachments": [
{
"type": "audio/mp3",
"name": "voicemail.mp3",
"data": "TVAzIERhdGEK"
}
]
}
Je kunt ook “inline afbeeldingen” verzenden in een transmissie. Deze zijn erg vergelijkbaar met bijlagen en worden gespecificeerd in de content.inline_images-array waar elk van de inline_image-objecten vergelijkbaar zijn met het bijlage-object hierboven afgebeeld.
Bijlagen in Sjablonen
Nu we de juiste achtergrond hebben voor het verzenden van bijlagen met het transmissie-eindpunt, laten we eens kijken hoe we dit met sjablonen kunnen doen. Op het moment van schrijven is er geen bijlage-abstractie zoals je vindt voor inline transmissies. Men zou kunnen concluderen dat sjablonen niet met bijlagen kunnen worden gemaakt. Je zou gedeeltelijk gelijk hebben, maar er is een omweg, hoewel je niet langer geïsoleerd zult zijn van het RFC 5322-formaat.
Je kunt bijlagen in sjablonen bereiken door zelf RFC 5322 inhoud te coderen, inclusief de bijlagen. Het goede nieuws is dat je nog steeds de mogelijkheid hebt om Substitution Data te gebruiken in je e-mailheaders, HTML en tekst delen. Wees je ervan bewust dat dit type sjabloon de substituties beperkt tot de headers en het eerste HTML en eerste tekst deel.
Hier is een voorbeeld van hoe het is gedaan.
RFC822 E-mail
Maak je RFC 5322 e-mail met de substitutiegegevens die je wilt. Ik heb deze in mijn e-mailclient gemaakt en naar mezelf gestuurd. Nadat ik het ontving, kopieerde ik de bron en verving de velden die ik dynamisch wilde vervangen.
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}}
<
Het laatste MIME-gedeelte in dit bericht zie je Content-Disposition: attachment; filename=myfile.txt”. Dat is waar de naam van het bestand wordt gedefinieerd. Jouw bijlage-inhoud zal hoogstwaarschijnlijk veel complexer zijn, maar dit voorbeeld probeert het simpel te houden.
Opgeslagen Sjabloon
Zodra je een geldige RFC 5322 e-mail hebt opgeslagen met behulp van de email_rfc822 vorm van het sjabloon eindpunt in plaats van het gebruik van tekst en HTML velden. Hier is een voorbeeld van hoe de content eruitziet voor dat bericht:
{
"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"
}
Wanneer het verzoek voltooid is, reageert SparkPost met een unieke identificatie voor je nieuwe sjabloon. Bijvoorbeeld xxxxxxx.
Het Verzenden van de Sjabloon
Het goede nieuws is dat het creëren van de RFC 5322 inhoud het moeilijke deel was. Vanaf hier is het verzenden van die sjabloon met SparkPost precies hetzelfde als het verzenden van elke andere sjabloon.
Hier is hoe we die sjabloon verzenden en de substitutiegegevens invullen:
{
"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
}
}
Sjablonen van een Mailclient’s API
Als je een programmeertaal gebruikt die een bibliotheek heeft voor het samenstellen van een e-mail, kun je die gebruiken om het sjabloon programmeermatig te maken of zelfs het bericht inline te verzenden. Hier is een voorbeeld van het gebruik van JavaMail om precies dat te doen via het transmissie-eindpunt van SparkPost. Deze methode zou gemakkelijk vertaald moeten kunnen worden naar PHP of je voorkeurstaal.
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();
}
}
}
}
Conclusie
Nu je ziet hoe SparkPost kan worden gebruikt om e-mail te verzenden van bijna elke complexiteit, wil je misschien eens kijken naar “SparkPost Ondersteunt Het Verzenden van E-mail op Apple Watch” of eens kijken naar de substitution syntax om te zien hoe het kan worden gebruikt met “als dan anders”, “expressies in voorwaardelijke uitspraken” of “array Iteratie” direct binnen je sjabloon of transmissie inhoud.