Dit bericht is gericht aan de ontwikkelaar die het beste uit SparkPost’s email template mogelijkheden wil halen. Er wordt verondersteld dat je vertrouwd bent met het lezen van JSON-inhoud en het volgen van de basisprogrammeerflow. Als er termen worden geïntroduceerd die misschien nieuw voor je zijn, zoals RFC 5322, is de tekst gekoppeld aan de bronverwijzing. Nu we dat uit de weg hebben, laten we er meteen induiken.

SparkPost’s template en transmissie mogelijkheden 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 direct te coderen zoals gedefinieerd in RFC 5322 vroeger bekend als (RFC 822). Maar soms wil je misschien meer complexe berichten creëren die andere Multipurpose Internet Mail Extensions (MIME) onderdelen hebben die niet direct beschikbaar zijn via de RESTful interface van SparkPost.

Vereenvoudigde E-mail Samenstelling

Laten we eerst een zonnige dag scenario voor het verzenden van een e-mail doornemen. Gebruik het transmissie eindpunt om de tekst en HTML inhoud te leveren. Achter de schermen zorgt SparkPost voor het samenstellen van een geldige RFC 5322 e-mail. SparkPost zal substitutievariabelen van substitution_data invoegen in de tekst en HTML inhoud. Dit is een krachtige manier om aangepaste inhoud voor elke ontvanger in een gemeenschappelijk sjabloon te genereren.

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}} \nSave big this Christmas in your area {{place}}! \nClick http://www.mysite.com and get huge discount\n</p><p>Hurry, this offer is only to {{user_type}}\n</p><p>{{sender}}</p>"   } }

Substitutie Arrays van Gegevens 

Veel mensen realiseren zich dat SparkPost’s transmissie- en templates eindpunten eenvoudige inhoud substitutie kunnen uitvoeren in e-mailheaders en e-maillichamen. Maar velen overzien de mogelijkheid om ook voorwaardelijke inhoud of arrays van gegevens te leveren die ook kunnen worden gesubstitueerd. Je 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 aan te bieden die in de e-mailinhoud worden ingevuld. Zodra de gegevens zijn geleverd, zal SparkPost logica in het sjabloon gebruiken om deze in te vullen.

In dit voorbeeld zal SparkPost op zoek gaan naar substitutiegegevens genaamd “files_html” en een “voor elke” uitvoeren op elk element in de array. Het zal een rij maken met de waarde van “file” in het “files_html” element. Let op de drievoudige krul om “loop_var.file“. Dit komt omdat elk element van de array HTML bevat en we de server moeten vertellen deze te gebruiken zoals die is en niet te ontsnappen. Het tekstgedeelte zal een eenvoudig tekstlabel zijn en de URL naar het bestand.

<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 Beschrijving</a>"                     },                     {                         "file": "<a href=\"http://domain.com/file2a.txt\">File 2a Beschrijving</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 Beschrijving</a>"                     },                     {                         "file": "<a href=\"http://domain.com/file2b.txt\">File 2b Beschrijving</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"         },         "html": "<b>Uw Bestanden:</b><br>\n<table>\n{{each files_html}}    <tr><td> {{{loop_var.file}}} </td></tr>\n{{ end }} </table>\n\n",         "text": "Uw Bestanden:\n{{each files_plain}} {{loop_var.file}} \n{{ end }} \n\n\n\n",         "subject": "Verzenden met SparkPost is leuk"     } }

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. Een array is voor HTML-gedeelte en de andere is voor het tekstgedeelte. In productiegebruik is het gebruikelijk om één set gegevens te hebben en de logica in de sjablooncode te schrijven.

Bijlagen in Transmissiemogelijkheden

Het transmissie eindpunt biedt ook een abstractie voor het verzenden van bijlagen. Hieronder zie je dat bijlagen gespecificeerd worden in de content.attachments array waar elk object in de array een individueel bijlage-item beschrijft. Net zoals voorheen zal SparkPost zorgen voor het coderen van tekst, HTML, substituties en het itereren door de bijlagearray om een correct gevormde e-mailboodschap te coderen.

Best practices dicteren dat het verzenden van bijlagen het beste vermeden kan worden, tenzij expliciet vereist als onderdeel van je dienst.

naamtypeHet MIME-type van de bijlagenaamDe bestandsnaam van de bijlagegegevensBase64 gecodeerde bestandsgegevens

Dit is hoe een bijlage eruitziet binnen de transmissie-inhoud stanza:

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

Je kunt ook “inline afbeeldingen” in een transmissie versturen. Deze zijn heel vergelijkbaar met bijlagen en worden gespecificeerd in de content.inline_afbeeldingen array waar elk van de inline_afbeelding objecten vergelijkbaar zijn met het boven getoonde bijlageobject.

Bijlagen in Sjablonen

Nu we de juiste achtergrond hebben voor het verzenden van bijlagen met het transmissie-eindpunt laten we eens kijken hoe je dit kunt doen met sjablonen. Op het moment van schrijven is er geen bijlagenabstractie zoals je die vindt voor inline transmissies. Men zou kunnen concluderen dat sjablonen niet gemaakt kunnen worden met bijlagen. Je hebt gedeeltelijk gelijk, maar er is een omweg, hoewel je niet langer geïsoleerd kunt zijn van het RFC 5322-formaat.

Je kunt bijlagen in sjablonen realiseren door zelf RFC 5322 inhoud te coderen, inclusief de bijlagen. Het goede nieuws is dat je de mogelijkheid om nog steeds Substitution Data te gebruiken in je e-mailheaders, HTML en tekst delen niet verliest. 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 hoe het wordt gedaan.

RFC822 Email

Maak je RFC 5322 email met de substitutiegegevens die je wilt. Ik heb deze gemaakt in mijn mailclient en naar mezelf gestuurd. Toen ik het ontving, kopieerde ik de bron en verving de velden die ik dynamisch wil substitueren.

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 met een *tekstbijlage*.   {{body2}}   --001a113c48b0b89d89052d3051d8 Content-Type: text/html; charset=UTF-8   <div dir="ltr"><div>E-mail met een <i>tekstbijlage</i>.</div>   {{body1}} </div>   --001a113c48b0b89d89052d3051d8-- --001a113c48b0b89d92052d3051da Content-Type: text/plain; charset=US-ASCII; name="myfile.txt" Content-Disposition: attachment; filename="myfile.txt" Content-Transfer-Encoding: base64 X-Attachment-Id: f_ild455ce0   VGhpcyBpcyBteSBzaW1wbGUgdGV4dCBmaWxlLgo= --001a113c48b0b89d92052d3051da--

Het laatste MIME deel in dit bericht zie je Content-Disposition: attachment; filename=myfile.txt”. Dat is waar de naam van het bestand is gedefinieerd. Je bijlageninhoud zal hoogstwaarschijnlijk veel complexer zijn, maar dit voorbeeld probeert het eenvoudig te houden.

Opgeslagen Sjabloon

Zodra je een geldige RFC 5322-email hebt, sla je deze op met behulp van de email_rfc822 vorm van het sjablooneindpunt 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 met een *tekstbijlage*.\n\n{{body2}}\n\n--001a113c48b0b89d89052d3051d8\nContent-Type: text/html; charset=UTF-8\n\n<div dir=\"ltr\"><div>Email met een <i>tekstbijlage</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, zal SparkPost reageren met een unieke identificatie voor je nieuwe sjabloon. Bijvoorbeeld xxxxxxx.

Het Verzenden van de Sjabloon

Het goede nieuws is dat het maken van de RFC 5322-inhoud het moeilijke gedeelte 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":"mijn onderwerp",         "body1": "Extra inhoud voor het HTML-gedeelte",         "body2": "Extra inhoud voor het tekstgedeelte"     },     "recipients": [         {             "substitution_data": {},             "address": {                 "email": "test1@domain.com",                 "name": "test1"             }         }     ],     "content": {         "template_id": "xxxxxxx",         "use_draft_template":true     } }

Sjablonen vanuit een E-mail Client API

Als je een programmeertaal gebruikt die een bibliotheek heeft voor het samenstellen van een e-mail, kun je die gebruiken om programmeerbaar de sjabloon te maken of zelfs het bericht inline te verzenden. Hier is een voorbeeld van het gebruik van JavaMail om dat heel goed te doen via het transmissie-eindpunt van SparkPost. Deze methode zou gemakkelijk kunnen worden vertaald naar PHP of je voorkeursprogrammeertaal.

/**  * Deze demonstratie van het gebruik van JavaMail MIME-bericht met de SparkPosts 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();           // Converteer JavaMail-bericht in een string voor transmissie         String rfc822Content = getMessageAsString(message);                   // Voeg een To en een From veld toe die zullen worden ingevuld met SparkPost substitutiedata         rfc822Content = "To: {{address.email}}\r\nFrom: {{from}}\r\n" + rfc822Content;           // Laadt een e-mail om te versturen van het bestandssysteem         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();           // Vul Ontvangers         List<RecipientAttributes> recipientArray = new ArrayList<RecipientAttributes>();         for (String recipient : recipients) {             RecipientAttributes recipientAttribs = new RecipientAttributes();             recipientAttribs.setAddress(new AddressAttributes(recipient));             recipientArray.add(recipientAttribs);         }         transmission.setRecipientArray(recipientArray);           transmission.setReturnPath(from);           // Vul Substitutiedata         Map<String, String> substitutionData = new HashMap<String, String>();         substitutionData.put("from", from);                   // SparkPost zal velden instellen in HTML en/of Plain delen met de waarde hier         // Zie: https://developers.sparkpost.com/api/#/introduction/substitutions-reference         substitutionData.put("name", "Your Name Here");                   transmission.setSubstitutionData(substitutionData);           // Vul E-mailinhoud         TemplateContentAttributes contentAttributes = new TemplateContentAttributes();         contentAttributes.setEmailRFC822(email);         transmission.setContentAttributes(contentAttributes);           // Verstuur de E-mail         RestConnection connection = new RestConnection(sparkpostClient, getEndPoint());           Response response = ResourceTransmissions.create(connection, 0, transmission);         if (response.getResponseCode() == 200) {             // Bericht succesvol verzonden             System.out.println("Transmission Response: " + response);         } else {             // Een fout opgetreden             System.err.println("TRANSMISSION ERROR: " + response);         }     }       /**      * Bouwt een e-mail met een tekst, HTML, en bijlagengedeelte      *      * @return een JavaMail bericht      * @throws MessagingException      */     private Message createMultipartMessage() throws MessagingException {         Properties props = new Properties();         // Dit wordt niet gebruikt, maar we moeten het instellen voor JavaMail om het         // bericht te maken         props.put("mail.smtp.host", "none");           Session session = Session.getDefaultInstance(props, null);         Message message = new MimeMessage(session);           message.setSubject("Een multipart MIME-bericht demo");                   Multipart multiPart = new MimeMultipart("alternative");           // Maak een tekstdeel         MimeBodyPart textPart = new MimeBodyPart();         textPart.setText("{{name}},\r\nplain text content", "utf-8");           // Bouw HTML-gedeelte van e-mail         MimeBodyPart htmlPart = new MimeBodyPart();         htmlPart.setContent("<b>{{name}},<br><br>Onze HTML-inhoud</b>", "text/html; charset=utf-8");           // Zet alle delen samen         multiPart.addBodyPart(textPart);         multiPart.addBodyPart(htmlPart);         message.setContent(multiPart);                   // Voeg een bijlage toe aan e-mail         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);                   return message;     }       /**      * Zet een JavaMail-bericht om in RFC822 inhoud      *      * @param msg      *            het bericht dat zal worden omgezet      * @return RFC822 inhoud      * @throws MessagingException      * @throws IOException      */     private String getMessageAsString(Message msg) throws IOException, MessagingException {         String content = "";         ByteArrayOutputStream out = new ByteArrayOutputStream();         try {             msg.writeTo(out);             content = new String(out.toByteArray(), "UTF-8");             return content;           } catch (UnsupportedEncodingException e) {             // Dit zou nooit mogen gebeuren, maar als dat gebeurt, stop hier alles             throw new Throwable("UTF-8 niet gevonden! " + e.getMessage());         } finally {             try {                 out.close();             } catch (IOException e) {                 e.printStackTrace();             }         }           // Fout         return null;     } }

Conclusie

Nu je ziet hoe SparkPost kan worden gebruikt om e-mails van bijna elke complexiteit te verzenden, wil je misschien eens kijken naar “SparkPost Ondersteunt het Verzenden van E-mail op Apple Watch” of eens kijken naar de substitutie syntaxis om te zien hoe het kan worden gebruikt met “als dan anders”, “expressies in conditionals” of “array Iteratie” direct in je sjabloon of transmissie inhoud.