Mehrsprachige E-Mails

Versenden Sie E-Mails in der bevorzugten Sprache der Empfänger — mithilfe von Template-Übersetzungen.

Reihenfolge der Sprachauflösung

Owlat ermittelt die Sprache für jede E-Mail in dieser Reihenfolge:

1. Expliziter Parameter language in der Sendeanfrage
2. Bevorzugte Sprache des Kontakts, gespeichert im Kontaktdatensatz
3. Standardsprache des Templates, gewählt beim Anlegen des Templates (und bei Marketing-Templates später in den Einstellungen änderbar)
4. Fallback-Standard (en)

Je nach Bedarf können Sie die Sprache auf unterschiedlichen Ebenen steuern.

Option 1: Explizite Sprache pro Anfrage

Übergeben Sie language direkt, wenn Sie das Gebietsschema des Benutzers kennen:

import { Owlat } from '@owlat/sdk-js'

const owlat = new Owlat('lm_live_...')

await owlat.transactional.send({
  slug: 'welcome',
  email: 'mira@acme.io',
  dataVariables: { firstName: 'Mira' },
  language: 'de',
})

curl -X POST https://your-deployment.convex.site/api/v1/transactional \
  -H "Authorization: Bearer lm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "welcome",
    "email": "mira@acme.io",
    "dataVariables": { "firstName": "Mira" },
    "language": "de"
  }'

Option 2: Gespeicherte Kontaktpräferenz

Jeder Kontakt kann eine gespeicherte Sprach-Präferenz besitzen. Wenn Sie ohne expliziten language-Parameter senden, greift die Auflösung auf diesen Wert zurück (siehe die Reihenfolge der Auflösung oben).

Die Sprache eines Kontakts ist nicht Teil der Create-API — owlat.contacts.create({ ... }) (und das zugrunde liegende POST /api/v1/contacts) akzeptieren nur email, firstName und lastName. Die gespeicherte Sprache setzen Sie auf eine von zwei Arten:

• Dashboard — den Kontakt bearbeiten und das Feld Sprache setzen.
• CSV-Import — beim Importieren von Kontakten eine Spalte language mitliefern.

Ein transaktionaler Versand speichert die language der Anfrage nicht am Kontakt — auch dann nicht, wenn der Versand einen brandneuen Kontakt anlegt. Die Sprache der Anfrage wird nur im Sendedatensatz festgehalten; ein neuer Kontakt wird ohne gespeicherte Sprachpräferenz angelegt.

Sobald ein Kontakt eine gespeicherte Sprache hat, können Sie language weglassen und die Auflösung darauf zurückgreifen lassen:

// No language param — the resolver uses the contact's stored preference,
// then the template default, then 'en'.
await owlat.transactional.send({
  slug: 'welcome',
  email: 'mira@acme.io',
  dataVariables: { firstName: 'Mira' },
})

Vollständiges Beispiel: Gebietsschema aus Ihrer Datenbank lesen

Ein vollständiger Handler, der die Gebietsschema-Präferenz des Benutzers liest und in der richtigen Sprache versendet:

import { Hono } from 'hono'
import { Owlat } from '@owlat/sdk-js'

const app = new Hono()
const owlat = new Owlat(process.env.OWLAT_API_KEY!)

app.post('/api/send-notification', async (c) => {
  const { userId, templateSlug, variables } = await c.req.json()

  // 1. Look up user locale from your database
  const user = await db.users.findUnique({
    where: { id: userId },
    select: { email: true, firstName: true, locale: true },
  })

  if (!user) return c.json({ error: 'User not found' }, 404)

  // 2. Send with the user's preferred language
  const result = await owlat.transactional.send({
    slug: templateSlug,
    email: user.email,
    dataVariables: {
      firstName: user.firstName,
      ...variables,
    },
    language: user.locale ?? undefined,
  })

  return c.json({ messageId: result.transactionalEmailId })
})

Nächste Schritte

• Leitfaden zu Übersetzungen — Übersetzungen zu Ihren Templates hinzufügen
• Referenz zur Transactional-API — Details zur Sprachauflösung
• Willkommens-E-Mail — grundlegendes Muster für transaktionalen Versand