E-Mail senden

Diese Anleitung erklärt jeden Teil einer Anfrage an POST /emails und was Emailit damit macht, von der Absenderadresse bis zu den Fehlern, die Sie zurückbekommen können. Die vollständige Parameterreferenz finden Sie unter E-Mail senden in der API-Referenz.

Voraussetzungen

• Eine verifizierte Versanddomain in Ihrem Workspace. Siehe Versanddomain hinzufügen.
• Ein API-Schlüssel mit dem Scope Full Access oder Sending Only. Siehe API-Schlüssel.
• Produktionszugang, wenn Sie an andere Personen als die Mitglieder Ihres Workspace senden. Siehe Produktionszugang.
• Genug Credits für jeden Empfänger (je 1 Credit).

Einfache E-Mail senden

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready."
  }'

import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: ['ada@example.com', 'Grace Hopper <grace@example.com>'],
  cc: 'accounts@example.com',
  reply_to: 'support@acme.com',
  subject: 'Your invoice for October',
  html: '<p>Your invoice is ready.</p>',
  text: 'Your invoice is ready.',
});

import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
})

$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => ['ada@example.com', 'Grace Hopper <grace@example.com>'],
    'cc' => 'accounts@example.com',
    'reply_to' => 'support@acme.com',
    'subject' => 'Your invoice for October',
    'html' => '<p>Your invoice is ready.</p>',
    'text' => 'Your invoice is ready.',
]);

Absenderadresse festlegen

from ist erforderlich und nimmt eine Adresse in einer dieser Formen an:

• billing@acme.com
• Acme Billing <billing@acme.com> oder mit Anführungszeichen "Acme, Inc." <billing@acme.com>

Die Domain nach dem @ muss eine verifizierte Versanddomain im selben Workspace sein:

• Der Abgleich ist exakt. Domains werden ohne Beachtung der Groß-/Kleinschreibung verglichen, aber mail.acme.com und acme.com sind unterschiedliche Domains. Fügen Sie jede Subdomain hinzu, von der Sie senden, und verifizieren Sie sie.
• Jeder lokale Teil funktioniert. Sie brauchen kein Postfach für billing@ oder no-reply@.
• Domains in Prüfung können nicht senden. Eine Domain, die noch auf die Prüfung wartet (Pending verification), gilt als nicht verifiziert.
• Beschränkte Schlüssel bleiben bei ihrer Domain. Ein auf eine Domain beschränkter Schlüssel mit Sending Only kann nur von dieser Domain senden.
• Pausierte Domains sind blockiert. Hat die Versandgesundheit die Domain pausiert, werden Versände von ihr abgelehnt, bis die Pause aufgehoben ist.

Empfänger hinzufügen

to ist erforderlich. cc und bcc sind optional. Jedes Feld akzeptiert einen String oder ein Array von Strings, mit oder ohne Anzeigenamen, und fasst bis zu 50 Adressen. Ein String kann mehrere durch Kommas getrennte Adressen enthalten; verwenden Sie ein Array, wenn ein Anzeigename selbst ein Komma enthält.

Emailit entfernt Duplikate über to, cc und bcc hinweg (ohne Beachtung der Groß-/Kleinschreibung) und erstellt dann eine E-Mail pro eindeutigem Empfänger, jede mit eigener em_-ID. Jede Kopie trägt dieselben Header To und Cc, sodass Empfänger die Konversation wie gewohnt sehen, und Bcc-Empfänger erscheinen nie in den Headern einer Kopie.

Hat eine Anfrage mehr als einen Empfänger, enthält die Antwort eine Zuordnung ids von Empfänger zu E-Mail-ID. id ist die E-Mail des ersten Empfängers.

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "ids": {
    "ada@example.com": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
    "grace@example.com": "em_33VtK8nB5rTq0YxW3mJk9PdLsUe",
    "accounts@example.com": "em_33VtK8nQ2wErT6yU8iOp4AsDf7g"
  }
}

Jeder Empfänger kostet 1 Credit und zählt zu Ihren Rate Limits. Ein Empfänger mit einer Sperrung vom Typ recipient wird angenommen und dann als suppressed markiert, statt zugestellt zu werden.

Inhalt schreiben

Nennt reply_to dieselbe Adresse wie from, entfernt Emailit den Header Reply-To, weil er nichts beiträgt und manche Spamfilter ihn negativ bewerten.

Mit einer Vorlage senden

Setzen Sie template auf einen Alias einer Vorlage oder eine tem_-ID und übergeben Sie variables für die Temple-Platzhalter darin.

• Ein Alias sendet die Version, die für diesen Alias aktuell veröffentlicht ist. Ist keine Version veröffentlicht, schlägt die Anfrage mit 404 fehl.
• Eine tem_-ID sendet genau diese Version, ob veröffentlicht oder nicht. Damit testen Sie eine Entwurfsversion, bevor Sie sie veröffentlichen.

Felder in der Anfrage haben Vorrang vor der Vorlage: Ein subject, html oder text, das Sie senden, ersetzt den Wert der Vorlage. Senden Sie kein reply_to, wird die Reply-To-Adresse der Vorlage verwendet. from ist in der Anfrage immer erforderlich. Wie das Veröffentlichen funktioniert, erfahren Sie unter Vorlagenversionen.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
      "first_name": "Ada",
      "plan": "Pro",
      "activation_url": "https://acme.com/activate?token=8f3k2"
    }
  }'

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome-email',
  variables: {
    first_name: 'Ada',
    plan: 'Pro',
    activation_url: 'https://acme.com/activate?token=8f3k2',
  },
});

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
        "first_name": "Ada",
        "plan": "Pro",
        "activation_url": "https://acme.com/activate?token=8f3k2",
    },
})

$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'template' => 'welcome-email',
    'variables' => [
        'first_name' => 'Ada',
        'plan' => 'Pro',
        'activation_url' => 'https://acme.com/activate?token=8f3k2',
    ],
]);

variables funktioniert auch ohne Vorlage: Emailit rendert Temple-Platzhalter in subject, html und text, die Sie direkt mitsenden.

Tracking steuern

Standardmäßig folgt jede E-Mail den Einstellungen Track loads und Track clicks ihrer Versanddomain. Überschreiben Sie sie pro E-Mail mit tracking:

• "tracking": true oder false aktiviert oder deaktiviert sowohl das Tracking von Ladevorgängen (Öffnungen) als auch das Klick-Tracking.
• "tracking": { "loads": true, "clicks": false } legt beides getrennt fest.

Tracking funktioniert nur, wenn der Tracking-CNAME der Domain verifiziert ist. Ohne ihn wird die E-Mail ohne Tracking gesendet, und die Anfrage ist trotzdem erfolgreich. Das Objekt tracking in der Antwort zeigt die tatsächlich angewendeten Einstellungen. Siehe Öffnungs- und Klick-Tracking.

Header und Metadaten hinzufügen

Verwenden Sie headers für eigene E-Mail-Header wie List-Unsubscribe und meta für Ihre eigenen Schlüssel-Wert-Paare aus Strings. Emailit speichert meta mit der E-Mail und nimmt es in Webhook-Events auf. Siehe Header und Metadaten.

Wie Sie Dateien anhängen, den Versand planen oder Wiederholungen sicher machen, erfahren Sie unter Anhänge, Planung und Idempotenz.

Antwort lesen

Eine erfolgreiche Anfrage gibt 200 zurück:

Speichern Sie die id (oder die Zuordnung ids), damit Sie spätere Webhook-Events zuordnen und die E-Mail mit E-Mail abrufen nachschlagen können.

Events

Die E-Mail jedes Empfängers löst eigene Events aus:

1. email.accepted direkt nach der Anfrage oder email.scheduled, wenn sie einen zukünftigen Sendezeitpunkt hat.
2. Zustell-Events, während die E-Mail die Zustellung durchläuft: email.delivered, email.attempted (vorübergehender Fehler, wird erneut versucht), email.bounced, email.failed, email.rejected oder email.suppressed. Eine zur Prüfung zurückgehaltene E-Mail löst email.held aus.
3. Engagement-Events bei aktiviertem Tracking: email.loaded und email.clicked. Spam-Meldungen lösen email.complained aus.

Was die einzelnen Status bedeuten, erfahren Sie unter E-Mail-Status.

Fehler

Validierungsfehler geben eine Liste aller gefundenen Probleme zurück:

{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: grace@"
  ]
}

Ein gesperrter Workspace erhält bei jedem Versand 403 mit Workspace is suspended. Das allgemeine Fehlerformat finden Sie unter Fehler.

Siehe auch

• E-Mail senden in der API-Referenz
• Vorlagen
• E-Mail-Status
• Webhook-Event-Typen
• Warum ist meine E-Mail nicht angekommen?