Erreichen

Grow

Manage

Automate

Erreichen

Grow

Manage

Automate

Erweiterte E-Mail-Vorlagen

Vogel

25.03.2016

E-Mail

1 min read

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.

Business in a box.

Entdecken Sie unsere Lösungen.

Dieser Beitrag richtet sich an den Entwickler, der das Beste aus SparkPosts E-Mail-Vorlagenfähigkeiten herausholen möchte. Es wird davon ausgegangen, dass Sie mit dem Lesen von JSON-Inhalten und dem Verfolgen einfacher Programmierabläufe vertraut sind. Wenn Ihnen neue Begriffe wie RFC 5322 vorgestellt werden, ist der Text mit seiner Quellenreferenz verlinkt. Nun, da das aus dem Weg geräumt ist, lassen Sie uns direkt eintauchen.

SparkPosts Vorlagen und Übertragungsfähigkeiten machen das Versenden von E-Mails einfach. Diese Fähigkeiten bieten eine Abstraktion für Text und HTML-Inhalte, was bedeutet, dass es meistens nicht notwendig ist, das rohe E-Mail-Format direkt zu kodieren, das in RFC 5322 vormals als (RFC 822) definiert ist. Aber manchmal möchten Sie vielleicht komplexere Nachrichten erstellen, die andere Mehrzweck-Internet-Mail-Erweiterungen (MIME) Teile enthalten, die nicht direkt über die SparkPost-REST-Schnittstelle zugänglich sind.

Vereinfachte E-Mail-Zusammensetzung

Zuallererst, lassen Sie uns ein ideales Szenario für das Senden einer E-Mail betrachten. Verwenden Sie den Übertragungs-Endpunkt, um den Text und HTML Inhalt bereitzustellen. Im Hintergrund sorgt SparkPost dafür, dass eine gültige RFC 5322 E-Mail zusammengesetzt wird. SparkPost wird Ersatzvariablen aus substitution_data in den Text- und HTML-Inhalt einfügen. Dies ist eine leistungsstarke Methode, um für jeden Empfänger Inhalte in einer gemeinsamen Vorlage zu erzeugen.

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

Datenarrays ersetzen

Viele Leute erkennen, dass SparkPosts Übertragungs- und Vorlagenendpunkte einfache Inhalts Ersatz in E-Mail-Kopfdaten und E-Mail-Körpern durchführen können. Aber viele übersehen die Möglichkeit, bedingte Inhalte oder Datenarrays bereitzustellen, die ebenfalls ersetzt werden können. Sie können auch einzigartige Inhalte pro Empfänger bereitstellen. In diesem Beispiel senden wir jedem Empfänger ein Array einzigartiger Links.

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

In diesem Beispiel sucht SparkPost nach Ersetzungsdaten namens „files_html“ und führt eine „for each“-Schleife für jedes Element im Array durch. Es wird eine Zeile mit dem Wert „file“ im „files_html“-Element erstellt. Beachten Sie die dreifachen geschweiften Klammern 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 escapen. Der Textteil ist ein einfaches Textlabel und die URL zur Datei.

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

Hier ist das fertiggestellte Arbeitsbeispiel:

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

Profi-Tipp: In Ihrem Code ist es ratsam, das Ansichtsmarkup von den Daten getrennt zu halten, aber das Ziel war hier, das Beispiel so einfach und nachvollziehbar wie möglich zu halten. Deshalb haben wir zwei Arrays erstellt. Ein Array ist für den HTML-Teil und das andere für den Textteil. Im Produktionsbetrieb wäre es üblich, einen Datensatz zu haben und die Logik im Vorlagencode zu schreiben.

Anhänge in Übertragungsfähigkeiten

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 Anhangselement beschreibt. Wie zuvor kümmert sich SparkPost um die Kodierung von Text, HTML, Ersetzungen und das Durchlaufen des Anhangs-Arrays, um eine korrekt formatierte E-Mail-Nachricht zu kodieren.

Best Practices besagen, dass das Senden von Anhängen am besten vermieden wird, es sei denn, es wird ausdrücklich als Teil Ihres Dienstes benötigt.

Unten sind die erforderlichen Felder für einen Anhang dargestellt:

  • typ: Der MIME-Typ des Anhangs

  • name: Der Dateiname des Anhangs

  • data: Base64-codierte Datei-Daten

So sieht ein Anhang in der Übertragungs-Inhaltsstrophe aus:

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

Sie können auch „Inline-Bilder“ in einer Übertragung senden. Diese sind den Anhängen sehr ähnlich und werden im content.inline_images-Array angegeben, wobei jedes der inline_image Objekte den oben gezeigten Anhangsobjekten ähnlich ist.

Anhänge in Vorlagen

Da wir nun den notwendigen Hintergrund für das Senden von Anhängen mit dem Übertragungsendpunkt haben, werfen wir einen Blick darauf, wie man dies mit Vorlagen macht. Zum Zeitpunkt des Schreibens gibt es keine Anhangs-Abstraktion wie bei Inline-Übertragungen. Man könnte schlussfolgern, dass Vorlagen nicht mit Anhängen erstellt werden können. Sie hätten teilweise recht, aber es gibt eine Lösung, obwohl Sie nicht mehr vom RFC 5322-Format isoliert sind.

Sie können Anhänge in Vorlagen erreichen, indem Sie RFC 5322 Inhalte selbst kodieren, die die Anhänge beinhalten. Die gute Nachricht ist, dass Sie die Möglichkeit nicht verlieren, weiterhin Ersatzdaten in Ihren E-Mail-Kopfzeilen, HTML und Text-Teilen zu verwenden. Beachten Sie, dass diese Art von Vorlage die Ersetzungen auf die Kopfzeilen 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 E-Mail-Client erstellt und sie mir selbst gesendet. Nachdem ich sie erhalten hatte, habe ich die Quelle kopiert und die Felder ersetzt, 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 dieser Nachricht enthält „Content-Disposition: attachment; filename=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 der email_rfc822-Form des Vorlage-Endpunkts anstatt Text und HTML-Felder zu verwenden. Hier ist ein Beispiel dafür, wie der Inhalt 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 Anforderung abgeschlossen ist, antwortet SparkPost mit einem eindeutigen Identifikator für Ihre neue Vorlage. Zum Beispiel xxxxxxx.

Senden der Vorlage

Die gute Nachricht ist, dass das Erstellen der RFC 5322-Inhalte der schwierige Teil war. Ab dieser Stelle ist das Senden dieser Vorlage mit SparkPost genau dasselbe wie das Senden jeder anderen Vorlage.

So senden wir diese Vorlage und füllen die Ersetzungsdaten aus:

{
  "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 Mail-Client-API

Wenn Sie eine Programmiersprache verwenden, die eine Bibliothek zum Erstellen von E-Mails hat, können Sie diese verwenden, um die Vorlage programmatisch zu erstellen oder die Nachricht sogar inline zu senden. Hier ist ein Beispiel für die Verwendung von JavaMail, um genau dies durch den SparkPost-Übertragungsendpunkt zu tun. Diese Methode sollte sich leicht auf PHP oder Ihre bevorzugte Sprache übertragen 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();
            }
        }
    }
}

Fazit

Da Sie nun sehen, wie mit SparkPost E-Mails nahezu jeder Komplexität gesendet werden können, möchten Sie vielleicht einen Blick auf „SparkPost unterstützt das Senden von E-Mails auf der Apple Watch“ werfen oder einen Blick auf die Ersatzsyntax werfen, um zu sehen, wie sie mit „if then else“, „Ausdrücken in Bedingungen“ oder „Array-Iteration“ direkt in Ihrer Vorlage oder Inhalt verwendet werden kann.

Lassen Sie uns Sie mit einem Bird-Experten verbinden.
Erleben Sie die volle Macht des Bird in 30 Minuten.

Durch die Übermittlung stimmen Sie zu, dass Bird Sie bezüglich unserer Produkte und Dienstleistungen kontaktieren darf.

Sie können sich jederzeit abmelden. Weitere Informationen zur Datenverarbeitung finden Sie in Birds Datenschutzerklärung.

Unternehmen

Newsletter

Bleiben Sie mit Bird auf dem Laufenden durch wöchentliche Updates in Ihrem Posteingang.

Lassen Sie uns Sie mit einem Bird-Experten verbinden.
Erleben Sie die volle Macht des Bird in 30 Minuten.

Durch die Übermittlung stimmen Sie zu, dass Bird Sie bezüglich unserer Produkte und Dienstleistungen kontaktieren darf.

Sie können sich jederzeit abmelden. Weitere Informationen zur Datenverarbeitung finden Sie in Birds Datenschutzerklärung.

Unternehmen

Newsletter

Bleiben Sie mit Bird auf dem Laufenden durch wöchentliche Updates in Ihrem Posteingang.

Lassen Sie uns Sie mit einem Bird-Experten verbinden.
Erleben Sie die volle Macht des Bird in 30 Minuten.

Durch die Übermittlung stimmen Sie zu, dass Bird Sie bezüglich unserer Produkte und Dienstleistungen kontaktieren darf.

Sie können sich jederzeit abmelden. Weitere Informationen zur Datenverarbeitung finden Sie in Birds Datenschutzerklärung.

R

Erreichen

G

Grow

M

Manage

A

Automate

Unternehmen

Newsletter

Bleiben Sie mit Bird auf dem Laufenden durch wöchentliche Updates in Ihrem Posteingang.