Erweiterte E-Mail-Vorlagen

Vogel

25.03.2016

E-Mail

1 min read

Erweiterte E-Mail-Vorlagen

Dieser Beitrag richtet sich an den Entwickler, der das Beste aus den E-Mail-Vorlagenfunktionen von SparkPost herausholen möchte. Es wird davon ausgegangen, dass Sie mit dem Lesen von JSON-Inhalten und dem Folgen grundlegender Programmabläufe vertraut sind. Wenn Begriffe, die Ihnen möglicherweise neu sind, wie RFC 5322 eingeführt werden, wird der Text mit der entsprechenden Quellenreferenz verlinkt.

Dieser Beitrag richtet sich an den Entwickler, der das Beste aus den E-Mail-Vorlagenfunktionen von SparkPost herausholen möchte. Es wird angenommen, dass Sie mit dem Lesen von JSON-Inhalten und dem Befolgen grundlegender Programmierabläufe vertraut sind. Begriffe, die Ihnen möglicherweise neu sind, wie RFC 5322, sind im Text mit ihrer Quellenreferenz verlinkt. Damit das aus dem Weg geräumt ist, lassen Sie uns direkt eintauchen.

Die Vorlagen- und Übertragungsfunktionen von SparkPost machen das Senden von E-Mails unkompliziert. Diese Funktionen bieten eine Abstraktion für Text und HTML-Inhalte, was bedeutet, dass es meistens nicht notwendig ist, das rohe E-Mail-Format, das in RFC 5322 früher bekannt als (RFC 822) definiert ist, direkt zu codieren. Aber manchmal möchten Sie vielleicht komplexere Nachrichten erstellen, die andere Multipurpose Internet Mail Extensions (MIME) Teile enthalten, die nicht direkt über die RESTful-Schnittstelle von SparkPost zugänglich sind.

Vereinfachte E-Mail-Komposition

Zuerst lassen Sie uns ein Sonnenschein-Szenario für das Senden einer E-Mail durchgehen. Verwenden Sie den transmission-Endpunkt, um den text und HTML Inhalt bereitzustellen. Hinter den Kulissen kümmert sich SparkPost um die Zusammenstellung einer gültigen RFC 5322 E-Mail. SparkPost fügt Ersetzungsvariablen aus substitution_data in den Text und HTML-Content ein. Dies ist eine mächtige Möglichkeit, benutzerdefinierte Inhalte für jeden Empfänger in einer gängigen Vorlage zu generieren.

Hier ist ein Beispiel für eine Übertragung mit HTML- und Textinhalten mit 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>"
  }
}

Ersetzen von Datenarrays

Viele merken, dass die Übertragungs- und Vorlagenendpunkte von SparkPost einfache Ersetzungen im E-Mail-Header und im E-Mail-Body durchführen können. Aber viele übersehen die Möglichkeit, bedingte Inhalte oder Arrays von Daten bereitzustellen, die ebenfalls ersetzt werden können. Sie können auch eindeutige Inhalte pro Empfänger bereitstellen. In diesem Beispiel senden wir ein Array von eindeutigen Links an jeden Empfänger.

Dies wird erreicht, indem ein JSON-Array von Daten bereitgestellt wird, das in den E-Mail-Body eingefügt wird. Sobald die Daten bereitgestellt sind, verwendet SparkPost Logik in der Vorlage, um sie zu füllen.

In diesem Beispiel sucht SparkPost nach Ersetzungsdaten namens „files_html“ und führt ein „for each“ für jedes Element im Array durch. Es wird eine Zeile mit dem Wert von „file“ im „files_html“-Element erstellt. Beachten Sie das dreifache geschweifte um „loop_var.file“. Dies liegt daran, dass jedes Element des Arrays HTML enthält und wir dem Server mitteilen müssen, es so zu verwenden, wie es ist, und es nicht zu maskieren. Der Textteil wird ein einfacher Textbezeichner und die URL zur Datei sein.

<table>
  {{each files_html}}
    <tr>
      <td>{{{loop_var.file}}}</td>
    </tr>
  {{ end }}
</table>

Hier ist das vollständige funktionierende Beispiel:

{
  "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 Tipp: In Ihrem Code ist es ratsam, die Ansichts-Markup von den Daten zu trennen, aber das Ziel hier war, das Beispiel so einfach und leicht nachvollziehbar wie möglich zu halten, also haben wir zwei Arrays erstellt. Ein Array ist für den HTML-Teil und das andere für den Textteil. In der Produktion wäre es üblich, einen Satz von Daten zu haben und die Logik im Vorlagencode zu schreiben.

Anhänge in Übertragungsfunktionen

Der Übertragungsendpunkt bietet auch eine Abstraktion für das Senden von Anhängen. Unten sehen Sie, dass Anhänge im content.attachments-Array angegeben sind, wobei jedes Objekt im Array ein einzelnes Anhängelement beschreibt. Wie zuvor kümmert sich SparkPost um das Codieren von Text, HTML, Ersetzungen und dem Durchlaufen des Anhänge-Arrays, um eine richtig formatierte E-Mail-Nachricht zu codieren.

Best Practices besagen, dass das Senden von Anhängen am besten vermieden werden sollte, es sei denn, dies ist ausdrücklich als Bestandteil Ihres Dienstes erforderlich.

Unten sind die erforderlichen Felder für einen Anhang:

  • type: Der MIME-Type des Anhangs

  • name: Der Dateiname des Anhangs

  • data: Base64-kodierte Datei-Daten

So sieht ein Anhang im Übertragungs-Content-Stanza aus:

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

Sie können auch "inline images" in einer Übertragung senden. Diese sind den Anhängen sehr ähnlich und werden im content.inline_images-Array angegeben, wobei jedes inline_image-Objekt dem oben gezeigten Anhangsobjekt ähnelt.

Anhänge in Vorlagen

Da wir nun den richtigen Hintergrund für das Senden von Anhängen mit dem Übertragungsendpunkt haben, lassen Sie uns einen Blick darauf werfen, wie dies mit Vorlagen gemacht wird. Zum Zeitpunkt der Erstellung dieses Textes gibt es keine Anhängeabstraktion wie bei Inline-Übertragungen. Man könnte den Schluss ziehen, dass Vorlagen nicht mit Anhängen erstellt werden können. Sie hätten teilweise recht, aber es gibt einen Workaround, obwohl Sie nicht mehr vom RFC 5322-Format isoliert sind.

Sie können Anhänge in Vorlagen umsetzen, indem Sie den RFC 5322-Inhalt selbst codieren, der die Anhänge umfasst. Die gute Nachricht ist, dass Sie nicht die Möglichkeit verlieren, Ersetzungsdaten weiterhin in Ihren E-Mail-Headern, HTML und Text-Teilen zu verwenden. Beachten Sie, dass dieser Vorlagentyp die Ersetzungen auf die Header und den ersten HTML- und ersten Text-Teil beschränkt.

Hier ist ein Beispiel, wie es gemacht wird.

RFC822 E-Mail

Erstellen Sie Ihre RFC 5322-E-Mail mit den gewünschten Ersetzungsdaten. Ich habe diese in meinem Mail-Client erstellt und an mich selbst gesendet. Sobald ich sie erhalten hatte, kopierte ich die Quelle und ersetzte die Felder, die ich dynamisch ersetzen möchte.

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}}
<

Der letzte MIME-Teil in dieser Nachricht, die Sie sehen, ist Content-Disposition: Anhang; Dateiname=myfile.txt“. Dort wird der Dateiname definiert. Ihr Anhangsinhalt wird sicherlich viel komplexer sein, aber dieses Beispiel versucht, es einfach zu halten.

Gespeicherte Vorlage

Sobald Sie eine gültige RFC 5322-E-Mail haben, speichern Sie sie mit dem email_rfc822-Formular des Vorlagenendpunkts anstelle der Verwendung von Text und HTML-Felder. Hier ist ein Beispiel, wie der Content für diese Nachricht aussieht:

{
  "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"
}

Wenn die Anfrage abgeschlossen ist, antwortet SparkPost mit einer eindeutigen Kennung für Ihre neue Vorlage. Zum Beispiel xxxxxxx.

Senden der Vorlage

Die gute Nachricht ist, dass das Erstellen des RFC 5322-Inhalts der schwierige Teil war. Ab jetzt ist das Senden dieser Vorlage mit SparkPost genau dasselbe wie das Senden einer anderen Vorlage.

Hier erfahren Sie, wie wir diese Vorlage senden und die Ersetzungsdaten einfügen:

{
  "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
  }
}

Vorlagen aus der API eines Mail-Clients

Wenn Sie eine Programmiersprache verwenden, die über eine Bibliothek zur Erstellung von E-Mails verfügt, können Sie diese verwenden, um die Vorlage programmgesteuert zu erstellen oder die Nachricht sogar inline zu senden. Hier ist ein Beispiel für die Verwendung von JavaMail über den Übertragungsendpunkt von SparkPost. Diese Methode sollte sich leicht in PHP oder Ihre bevorzugte Sprache übersetzen lassen.

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

Schlussfolgerung

Nachdem Sie nun gesehen haben, wie SparkPost verwendet werden kann, um E-Mails von fast jeder Komplexität zu senden, möchten Sie vielleicht einen Blick auf „SparkPost unterstützt das Senden von E-Mails auf der Apple Watch“ werfen oder sich die Ersetzungssyntax ansehen, um zu sehen, wie sie mit „if then else“, „Ausdrücken in Bedingungen“ oder „Array-Iteration“ direkt in Ihrer Vorlage oder Ihrem Übertragungs-Content verwendet werden kann.

Andere Neuigkeiten

Mehr lesen aus dieser Kategorie

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

Die vollständige AI-native Plattform, die mit Ihrem Business skaliert.

Kontaktieren Sie den Vertrieb

Kostenlos starten

© 2025 Bird

Support kontaktieren

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

Die vollständige AI-native Plattform, die mit Ihrem Business skaliert.

Kontaktieren Sie den Vertrieb

Kostenlos starten

© 2025 Bird

Support kontaktieren

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

Die vollständige AI-native Plattform, die mit Ihrem Business skaliert.

Kontaktieren Sie den Vertrieb

Kostenlos starten

© 2025 Bird

Support kontaktieren