Dit bericht is gericht aan de ontwikkelaar die het meeste uit de e-mailtemplate mogelijkheden van SparkPost wil halen. Er wordt verondersteld dat u comfortabel bent met het lezen van JSON-inhoud en het volgen van basis programmeerlogica. Als termen die misschien nieuw voor u zijn worden geïntroduceerd zoals RFC 5322, is de tekst gekoppeld aan de bronreferentie. Nu dat uit de weg is, laten we er meteen induiken.
De template en transmissiemogelijkheden van SparkPost maken het verzenden van e-mails eenvoudig. Die mogelijkheden bieden een abstractie voor tekst en HTML inhoud, wat betekent dat er meestal geen directe codering van het onbewerkte e-mailformaat nodig is zoals dat is gedefinieerd in RFC 5322 voorheen bekend als (RFC 822). Maar soms wilt u wellicht complexere berichten maken die andere multipurpose Internet Mail Extensions (MIME) onderdelen hebben die niet direct via de RESTful interface van SparkPost beschikbaar zijn.
Vereenvoudigde E-mailopstelling
Laten we eerst een scenario op een zonnige dag voor het verzenden van een e-mail bekijken. Gebruik het transmission eindpunt om de tekst en HTML inhoud te leveren. Achter de schermen zorgt SparkPost ervoor dat er een geldige RFC 5322 e-mail wordt samengesteld. SparkPost zal vervangingsvariabelen uit substitution_data invoegen in de tekst- en HTML-inhoud. Dit is een krachtige manier om aangepaste inhoud voor elke ontvanger te genereren in een gemeenschappelijk sjabloon.
Hier is een voorbeeld van transmission 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 van Gegevensarrays
Veel mensen realiseren zich dat de transmission en template eindpunten van SparkPost eenvoudige inhouds substitutie kunnen doen in e-mailheaders en e-maillichamen. Maar velen overzien de mogelijkheid om voorwaardelijke inhoud of gegevensarrays aan te bieden die ook kunnen worden vervangen. U kunt ook unieke inhoud per ontvanger aanbieden. In dit voorbeeld sturen we een array van unieke links naar elke ontvanger.
Dit wordt bereikt door een JSON-array van gegevens te verstrekken die in het e-maillichaam worden geplaatst. Zodra de gegevens zijn verstrekt zal SparkPost logica in de template gebruiken om het te vullen.
In dit voorbeeld zal SparkPost zoeken naar substitutiedata genaamd "files_html” en een “voor elk” uitvoeren op elk element in de array. Het zal een rij maken met de waarde van “bestand” in het “files_html” element. Noteer de driedubbele krullen rond “loop_var.file“. Dit komt omdat elk element van de array HTML bevat en we de server moeten vertellen om het zo te gebruiken en niet te ontsnappen. Het 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 uw code wordt geadviseerd om de weergave opmaak gescheiden van de gegevens te houden, maar het doel hier was om het voorbeeld zo eenvoudig en gemakkelijk te volgen mogelijk te maken, dus hebben we twee arrays gemaakt. Eén array is voor het HTML-gedeelte en de andere is voor het tekstgedeelte. In productieomgevingen is het gebruikelijk om één dataset te hebben en de logica in de templatecode te schrijven.
Bijlagen in Transmissiemogelijkheden
Het transmission eindpunt biedt ook een abstractie voor het verzenden van bijlagen. Hieronder ziet u dat bijlagen worden gespecificeerd in de content.attachments array waar elk object in de array een afzonderlijk bijlage-item beschrijft. Net zoals voorheen zal SparkPost zorgen voor de codering van tekst, HTML, vervangingen en door de bijlage-array itereren om een correct gevormd e-mailbericht te coderen.
Beste praktijken dicteren dat het verzenden van bijlagen het beste vermeden kan worden tenzij expliciet vereist als onderdeel van uw service.
Hieronder staan de vereiste velden voor een bijlage:
type: Het MIME-type van de bijlage
name: De bestandsnaam van de bijlage
data: Base64-gecodeerde bestandsgegevens
Dit is hoe een bijlage er uitziet binnen de transmissiecontent stanza:
"content": {
"attachments": [
{
"type": "audio/mp3",
"name": "voicemail.mp3",
"data": "TVAzIERhdGEK"
}
]
}U kunt ook “inline beelden” verzenden in een transmission. Deze zijn zeer vergelijkbaar met bijlagen en worden gespecificeerd in de content.inline_images array waar elk van de inline_image objecten vergelijkbaar zijn met het hierboven getoonde bijlage-object.
Bijlagen in Sjablonen
Nu we de juiste achtergrond hebben voor het verzenden van bijlagen met het transmission eindpunt, laten we eens kijken hoe we dit met sjablonen kunnen doen. Op het moment van schrijven is er geen abstractie voor bijlagen zoals u die vindt voor inline transmissies. Men kan concluderen dat sjablonen niet met bijlagen kunnen worden gemaakt. Dit zou gedeeltelijk correct zijn maar er is een omweg, hoewel u niet langer geïsoleerd bent van het RFC 5322-formaat.
U kunt bijlagen in sjablonen bereiken door zelf RFC 5322 inhoud te coderen inclusief de bijlagen. Het goede nieuws is dat u het vermogen om nog steeds Substitution Data te gebruiken in uw e-mailheaders, HTML en tekst delen niet verliest. Wees u 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 gedaan wordt.
RFC822 E-mail
Maak uw RFC 5322 e-mail met de gewenste substitutiedata. Ik heb deze in mijn mailclient gemaakt en naar mezelf verzonden. Zodra ik het ontving kopieerde ik de bron en verving de velden die ik dynamisch wil 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-deel van dit bericht ziet u Content-Disposition: attachment; filename=myfile.txt”. Dat is waar de naam van het bestand wordt gedefinieerd. Uw bijlageninhoud zal vrijwel zeker veel complexer zijn, maar dit voorbeeld probeert het eenvoudig te houden.
Opgeslagen Sjabloon
Zodra u een geldige RFC 5322 e-mail hebt, sla die op gebruikmakend van de email_rfc822 vorm van het sjabloon eindpunt in plaats van de tekst en HTML velden. Hier is een voorbeeld van hoe de inhoud voor dat bericht eruitziet:
{
"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 is voltooid, zal SparkPost reageren met een unieke identificatie voor uw nieuwe sjabloon. Bijvoorbeeld xxxxxxx.
Het Verzenden van het Sjabloon
Het goede nieuws is dat het creëren van de RFC 5322-inhoud het moeilijke deel was. Vanaf hier is het verzenden van dat sjabloon met SparkPost precies hetzelfde als het verzenden van elk ander sjabloon.
Hier is hoe we dat sjabloon verzenden en de substitutiedata 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 E-mail Client’s API
Als u een programmeertaal gebruikt die een bibliotheek voor het samenstellen van een e-mail heeft, kunt u dat gebruiken om het sjabloon programmatisch te maken of zelfs de boodschap inline te verzenden. Hier is een voorbeeld van het gebruik van JavaMail via het transmissie-eindpunt van SparkPost. Deze methode zou eenvoudig vertaald kunnen worden naar PHP of uw taal naar keuze.
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 u ziet hoe SparkPost kan worden gebruikt om e-mails van bijna elke complexiteit te verzenden, wilt u wellicht eens kijken naar “SparkPost Ondersteunt Het Verzenden van E-mail naar Apple Watch” of kijkt u naar de substitutiesyntaxis om te zien hoe het kan worden gebruikt met "als dan anders", "expressies in voorwaardelijke zinnen" of "array-iteratie" direct in uw sjabloon of transmissie-inhoud.
