Product

Oplossingen

Resources

Company

Product

Oplossingen

Resources

Company

Geavanceerde E-mailsjablonen

Bird

25 mrt 2016

E-mail

1 min read

Geavanceerde E-mailsjablonen

Deze post is gericht aan de ontwikkelaar die het meeste uit de e-mailsjabloonmogelijkheden van SparkPost wil halen. Er wordt aangenomen dat je vertrouwd bent met het lezen van JSON-inhoud en het volgen van de basisprogrammaflow. Wanneer er termen worden geïntroduceerd die mogelijk nieuw voor je zijn, zoals RFC 5322, is de tekst gekoppeld aan de bronreferentie.

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.

/**
 * 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();
            }
        }
    }
}

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.

Andere nieuws

Lees meer uit deze categorie

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

Het complete AI-native platform dat met uw bedrijf meegroeit.

Product

Oplossingen

Resources

Binnenkort beschikbaar

Sociaal

Nieuwsbrief

Blijf op de hoogte met Bird via wekelijkse updates in je inbox.

Signup

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

Het complete AI-native platform dat met uw bedrijf meegroeit.

Product

Oplossingen

Resources

Sociaal

Nieuwsbrief

Blijf op de hoogte met Bird via wekelijkse updates in je inbox.

Signup