Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core für Entwickler > agorum core JavaScript-API

JavaScript-Bibliothek common/mail

Diese Bibliothek enthält Funktionen zum Erstellen und Versenden von E-Mails.

send() mit Parametern

Erzeugt eine (ausgehende) E-Mail nach den Vorgaben.

Der Rückgabe-Parameter enthält das neu erstellte E-Mail-Objekt.

let objects = require('common/objects');

let mail = require('common/mail');

let data = {
  from: 'test@domain.de',
  to: [ 'receiver1@domain.de', 'receiver2@domain.de' ],
  cc: [ 'cc1@domain.de', 'cc2@domain.de' ],
  bcc: [ 'bcc1@domain.de', 'bcc2@domain.de' ],
  subject: 'Betreffzeile',
  body: 'Hier kommt der Inhalt der E-Mail, auch HTML ist möglich',
                                          
  // attachments: [ objects.find('ID-OF-Attachment') ],
  
  // html body (true), text body (false), default: false
  html: true,                                        
  
  user: objects.find('user:demo'),              
  replyTo: 'test@domain.de'
};

mail.send(data);

Beispiel für eine generierte E-Mail

Parameter

Die folgenden Parameter gelten, wenn Sie die E-Mail direkt über Parameter erzeugen und senden.

Parameter	Beschreibung
from	Definiert die Absenderadresse. Wenn Sie diesen Parameter nicht angegeben, verwendet das System die zugeordnete E-Mail-Adresse des Benutzers, der die E-Mail sendet.
to	Definiert ein Array von Empfängeradressen.
cc (optional)	Definiert ein Array von CC-Adressen.
bcc (optional)	Definiert ein Array von BCC-Adressen.
subject	Definiert den Betreff der E-Mail.
replyTo (optional)	Definiert eine alternative Adresse, an die das System die Antwort versendet (anstelle von from).
body (optional)	Definiert den Text oder den HTML-Body der E-Mail.
attachments (optional)	Definiert ein Array von agorum core-Objekten (in der Regel Dokumente oder E-Mails), die das System als Anhang zu der E-Mail versendet.
html	true Das System versendet die E-Mail als HTML-E-Mail. Hinweis: Der Body muss als HTML definiert sein. false (Standard) Das System versendet die E-Mail als Text-E-Mail.
user (optional)	Übergibt das Objekt des Benutzers, der die E-Mail versendet. Das System legt das Objekt in den Postausgang des Benutzers. Der Benutzer ist dann der Besitzer der E-Mail. Wenn Sie diesen Parameter nicht angeben, verwendet das System den aktuell angemeldeten Benutzer.
replyTo (optional)	Definiert eine E-Mail-Adresse, an die das System die Antwort versendet.
inReplyTo (optional)	Definiert eine RFC822MessageId der E-Mail, auf die geantwortet wurde.

send() mit draft

Das folgende Beispiel zeigt, wie Sie einen draft (E-Mail-Entwurf) versenden.

let mail = require('common/mail');
let objects = require('common/objects');

// create draft, with user demo
let draft = objects.find(mail.create({
  to: [ 'roi@agorumcore.com' ],
  subject: 'a mail subject',
  body: 'a body',
  user: objects.find('user:demo')
}));

// send the draft
mail.send(draft, {
  user: objects.find('user:demo'),
  keepDraft: false
});

Parameter

Parameter	Beschreibung
user (optional)	Definiert das Objekt des Benutzers, der die E-Mail versendet. Das System legt das Objekt in den Postausgang des Benutzers. Der Benutzer ist dann der Besitzer der E-Mail. Wenn Sie diesen Parameter nicht angeben, verwendet das System den aktuell angemeldeten Benutzer.
keepDraft (optional)	true Das System behält den Entwurf nach dem Versenden der E-Mail. false (Standard) Das System löscht den Entwurf nach dem Versenden der E-Mail.

sendEncryptedMail()

Versendet eine PGP-verschlüsselte E-Mail im PGP/MIME-Format gemäß RFC 3156. Die Verschlüsselung erfolgt mit öffentlichen PGP-Schlüsseln der Empfänger.

Syntax

let mail = require('common/mail');

mail.sendEncryptedMail(mailObject, data);

Diese Funktion akzeptiert als erstes Argument entweder:

agorum.Object – Ein bestehendes Mail-Entwurfsobjekt (Draft) aus agorum core
EncryptedMailData – Ein Datenobjekt mit allen E-Mail-Informationen

Einfache verschlüsselte E-Mail

let mail = require('common/mail');
let objects = require('common/objects');

// Öffentlichen Schlüssel laden
let publicKey = objects.find('/pfad/zum/public-key.asc');

// Verschlüsselte E-Mail versenden
mail.sendEncryptedMail({
  to: ['empfaenger@example.com'],
  subject: 'Vertrauliche Nachricht',
  body: 'Dies ist eine verschlüsselte Nachricht.',
  encryption: {
    publicKeys: [publicKey]
  }
});

Verschlüsselte E-Mail mit sichtbarem Betreff

Standardmäßig wird der Betreff durch "…" ersetzt, um keine Informationen preiszugeben. Mit keepSubject: true bleibt der Original-Betreff sichtbar:

let mail = require('common/mail');
let objects = require('common/objects');

let publicKey = objects.find('/pfad/zum/public-key.asc');

mail.sendEncryptedMail({
  to: ['empfaenger@example.com'],
  subject: 'Monatsbericht Januar 2025',
  body: 'Anbei der vertrauliche Monatsbericht.',
  encryption: {
    publicKeys: [publicKey],
    keepSubject: true
  }
});

Verschlüsselte E-Mail mit benutzerdefiniertem Betreff

Mit der subject-Option in encryption kann ein alternativer Betreff für die verschlüsselte E-Mail angegeben werden:

let mail = require('common/mail');
let objects = require('common/objects');

let publicKey = objects.find('/pfad/zum/public-key.asc');

mail.sendEncryptedMail({
  to: ['empfaenger@example.com'],
  subject: 'Geheimer Inhalt',
  body: 'Streng vertrauliche Informationen.',
  encryption: {
    publicKeys: [publicKey],
    subject: 'Verschlüsselte Nachricht'
  }
});

In diesem Fall sieht der Empfänger zunächst „Verschlüsselte Nachricht“ als Betreff. Nach der Entschlüsselung wird der eigentliche Betreff „Geheimer Inhalt“ sichtbar.

Verschlüsselte E-Mail mit Anhängen

let mail = require('common/mail');
let objects = require('common/objects');

let publicKey = objects.find('/pfad/zum/public-key.asc');
let attachment = objects.find('/pfad/zum/dokument.pdf');

mail.sendEncryptedMail({
  to: ['empfaenger@example.com'],
  subject: 'Dokumente zur Prüfung',
  body: 'Anbei die angeforderten Dokumente.',
  attachments: [attachment],
  encryption: {
    publicKeys: [publicKey]
  }
});

Unverschlüsselte Kopie behalten

Mit keepUnencrypted: true wird die unverschlüsselte E-Mail als Anhang im agorum core Mail-Objekt gespeichert. Dies ist nützlich für Archivierungszwecke:

let mail = require('common/mail');
let objects = require('common/objects');

let publicKey = objects.find('/pfad/zum/public-key.asc');

mail.sendEncryptedMail({
  to: ['empfaenger@example.com'],
  subject: 'Archivierte Nachricht',
  body: 'Diese Nachricht wird auch unverschlüsselt archiviert.',
  encryption: {
    publicKeys: [publicKey],
    keepUnencrypted: true
  }
});

HTML-E-Mail verschlüsselt versenden

let mail = require('common/mail');
let objects = require('common/objects');

let publicKey = objects.find('/pfad/zum/public-key.asc');

mail.sendEncryptedMail({
  to: ['empfaenger@example.com'],
  subject: 'Newsletter',
  html: true,
  body: '<h1>Willkommen</h1><p>Dies ist eine <strong>formatierte</strong> Nachricht.</p>',
  encryption: {
    publicKeys: [publicKey]
  }
});

Mehrere Empfänger mit verschiedenen Schlüsseln

Wenn mehrere Empfänger unterschiedliche PGP-Schlüssel haben, müssen alle öffentlichen Schlüssel angegeben werden:

let mail = require('common/mail');
let objects = require('common/objects');

let publicKey1 = objects.find('/pfad/zum/key1.asc');
let publicKey2 = objects.find('/pfad/zum/key2.asc');

mail.sendEncryptedMail({
  to: ['empfaenger1@example.com', 'empfaenger2@example.com'],
  subject: 'Gruppennachricht',
  body: 'Nachricht an mehrere Empfänger.',
  encryption: {
    publicKeys: [publicKey1, publicKey2]
  }
});

Beispiel mit Draft

let mail = require('common/mail');
let objects = require('common/objects');

// Entwurf erstellen
let draft = objects.find(mail.create({
  to: ['receiver@domain.de'],
  subject: 'Vertrauliche Nachricht',
  body: 'Vertraulicher Inhalt',
  user: objects.find('user:demo')
}));

// Entwurf verschlüsselt versenden
mail.sendEncryptedMail(draft, {
  user: objects.find('user:demo'),
  keepDraft: false,
  encryption: {
    publicKeys: [objects.find('/pfad/zum/public-key.asc')],
    keepSubject: true
  }
});

Parameter (EncryptedMailData)

Parameter	Erforderlich	Beschreibung
to	Ja	Liste der Empfänger-E-Mail-Adressen als Array.
from	Nein	Absender-E-Mail-Adressen.
cc	Nein	CC-Empfänger als Array.
bcc	Nein	BCC-Empfänger (Blindkopie) als Array.
replyTo	Nein	Antwort-Adresse.
inReplyTo	Nein	Message-ID der E-Mail, auf die geantwortet wird.
subject	Ja	Betreff der E-Mail.
html	Nein	`true` für HTML-Inhalt, `false` für Plaintext.
body	Nein	Inhalt der E-Mail.
attachments	Nein	Liste von agorum core-Objekten als Anhänge.
user	Nein	Benutzer, in dessen Kontext die Mail versendet wird.
encryption	Ja	Verschlüsselungsoptionen (siehe Tabelle unten).

Parameter (EncryptionData)

Parameter	Erforderlich	Beschreibung
publicKeys	Ja	Liste der öffentlichen PGP-Schlüssel für die Verschlüsselung. Kann als Pfad (String), agorum core-Objekt oder InputStream übergeben werden.
keepSubject	Nein	true Der Original-Betreff bleibt sichtbar. false (Standard) Der Betreff wird durch `"..."` ersetzt.
subject	Nein	Benutzerdefinierter Betreff für die verschlüsselte E-Mail (überschreibt `keepSubject`).
keepUnencrypted	Nein	true Die unverschlüsselte E-Mail wird als Anhang im agorum core Mail-Objekt gespeichert. false (Standard) Keine unverschlüsselte Kopie wird erstellt.

Parameter (Draft)

Wenn ein Draft-Objekt übergeben wird, werden folgende Parameter im zweiten Argument unterstützt:

Parameter	Beschreibung
user (optional)	Definiert das Objekt des Benutzers, der die E-Mail versendet.
keepDraft (optional)	true Das System behält den Entwurf nach dem Versenden. false (Standard) Das System löscht den Entwurf nach dem Versenden.
encryption	Objekt mit den Verschlüsselungseinstellungen (erforderlich). Siehe Tabelle oben.

Rückgabewert

Die Funktion gibt das erstellte Mail-Objekt zurück.

Hinweise

Die E-Mail wird im RFC 3156 PGP/MIME-Format verschlüsselt.
Alle Empfänger (to, cc, bcc) müssen über gültige öffentliche PGP-Schlüssel verfügen.
Der Betreff wird standardmäßig durch "…" ersetzt, um keine Metadaten preiszugeben.
Öffentliche Schlüssel können als Dateipfad (String), agorum.Object oder InputStream übergeben werden.

reply()

Erwartet eine (eingehende) E-Mail als Parameter und erzeugt eine dazu passende Antwort-E-Mail im Entwurfsmodus.

let mail = require('common/mail');
let objects = require('common/objects');

let inboxMail = objects.find('<e-mail-uuid>');

let draft = mail.reply(inboxMail, {
  from: 'test@domain.de',
  all: true,
  signature: 'Hier kommt meine Signatur',
  user: objects.find('user:demo'),
  body: 'Optionaler HTML-Body, der vorn an die E-Mail angefügt wird'
});

Parameter

Parameter	Beschreibung
from	Definiert die Absenderadresse. Wenn Sie diesen Parameter nicht angeben, verwendet das System die zugeordnete E-Mail-Adresse des Benutzers, der die E-Mail versendet.
all	true Alle Absender als auch alle Empfänger erhalten die Antwort (ausgenommen: der Absender der Antwort). false Ausschließlich der erste Absender erhält die Antwort.
signature	Definiert einen Signatur-String, den das System automatisch als Signatur in die erzeugte E-Mail einfügt.
user (optional)	Definiert einen Benutzer, in dessen Namen das System die E-Mail erstellt. Wenn Sie diesen Parameter nicht angeben, verwendet das System den aktuell angemeldeten Benutzer.
body (optional)	Definiert den Body, den das System beim Antworten vorn in den E-Mail-Text einfügt.

forward()

Erwartet eine (eingehende) E-Mail als Parameter und erzeugt eine dazu passende Weiterleitungs-E-Mail im Entwurfsmodus.

let mail = require('common/mail');

let inboxMail = objects.find('<e-mail-uuid>');

let draft = mail.forward(inboxMail, {
  from: 'test@domain.de'
  attach: true,
  signature: 'Hier kommt meine Signatur',
  user: objects.find('user:demo'),
  body: 'Optionaler HTML-Body, der vorn an die E-Mail angefügt wird'
});

Parameter

Parameter	Beschreibung
from	Definiert die Absenderadresse. Wenn Sie diesen Parameter nicht angeben, verwendet das System die zugeordnete E-Mail-Adresse des Benutzers, der die E-Mail versendet.
to	Definiert ein Array von Empfängeradressen.
cc (optional)	Definiert ein Array von CC-Adressen.
bcc (optional)	Definiert ein Array von BCC-Adressen.
attach	true Das System hängt die weitergeleitete E-Mail als Anhang an. false Das System hängt die weitergeleitete E-Mail als Zitat an.
signature	Definiert einen Signatur-String, den das System automatisch als Signatur in die erzeugte E-Mail einfügt.
user (optional)	Definiert einen Benutzer, in dessen Namen das System die E-Mail erstellt. Wenn Sie diesen Parameter nicht angeben, verwendet das System den aktuell angemeldeten Benutzer.
body (optional)	Definiert den Body, den das System beim Antworten vorn in den E-Mail-Text einfügt.

appendGlobalFooter()

Ergänzt den E-Mail-Body um den globalen E-Mail-Footer und liefert den E-Mail-Body.

let mail = require('common/mail');
let objects = require('common/objects');

let draft = mail.appendGlobalFooter({
  body: 'Hier kommt der Inhalt der E-Mail, auch HTML ist möglich',
  user: objects.find('user:demo'),
  mail: objects.find('<e-mail-uuid>'),
});

Parameter

Parameter	Beschreibung
body (optional)	Definiert den Text oder den HTML-Body der E-Mail.
user (optional)	Ergänzt die E-Mail um den E-Mail-Footer des angegebenen Benutzers. Wenn Sie diesen Parameter nicht angeben, verwendet das System den aktuell angemeldeten Benutzer.
mail	Definiert das E-Mail-Objekt.

create()

Erstellt ein E-Mail-Entwurf-Objekt und liefert die ID dieses Objekts.

let mail = require('common/mail');
let objects = require('common/objects');

let draft = mail.create({
  from: 'sender@domain.de',
  to: [ 'receiver1@domain.de', 'receiver2@domain.de' ],
  cc: [ 'cc1@domain.de', 'cc2@domain.de' ],
  bcc: [ 'bcc1@domain.de', 'bcc2@domain.de' ],
  subject: 'Betreffzeile',
  body: 'Hier kommt der Inhalt der E-Mail, auch HTML ist möglich',
  signature: 'Signatur',
  // attachments: [ objects.find(/* attachment ID */) ],
  user: objects.find('user:demo')
});

Parameter

Parameter	Beschreibung
from	Definiert die Absenderadresse. Wenn Sie diesen Parameter nicht angeben, verwendet das System die zugeordnete E-Mail-Adresse des Benutzers, der die E-Mail versendet.
to	Definiert ein Array von Empfängeradressen.
cc (optional)	Definiert ein Array von CC-Adressen.
bcc (optional)	Definiert ein Array von BCC-Adressen.
subject	Definiert den Betreff der E-Mail.
body (optional)	Definiert den Text oder den HTML-Body der E-Mail.
signature	Definiert einen Signatur-String, den das System automatisch als Signatur in die erzeugte E-Mail einfügt.
attachments (optional)	Definiert ein Array von agorum core-Objekten (in der Regel Dokumente oder E-Mails), die das System als Anhang zu der E-Mail versendet.
user (optional)	Definiert einen Benutzer, in dessen Namen das System die E-Mail erstellt. Wenn Sie diesen Parameter nicht angeben, verwendet das System den aktuell angemeldeten Benutzer.
inReplyTo (optional)	Definiert die RFC822MessageId einer anderen E-Mail. Das System verknüpft dann diese E-Mail mit der E-Mail.

footer()

Liefert den individuellen E-Mail-Footer des Benutzers als HTML-String.

Wenn kein Footer beim Benutzer definiert ist, erhalten Sie ' '.
Wenn Sie den Parameter from nicht angeben, erhalten Sie den Footer des angemeldeten Benutzers.

let mail = require('common/mail');

// mail.footer([ from ], [ user ]);
let footer = mail.footer('test@domain.de');

Parameter	Beschreibung
from	Definiert die Absenderadresse. Wenn Sie diesen Parameter nicht angeben, verwendet das System die zugeordnete E-Mail-Adresse des Benutzers, der die E-Mail versendet.
user (optional)	Wenn Sie den Parameter from nicht angeben, jedoch den Parameter user, verwendet das System die Standard-E-Mail-Adresse des Benutzers als from-Adresse.

cleanContent()

Liefert einen bereinigten E-Mail-Body.

let mail = require('common/mail');

// mail.cleanContent(body);
let cleanContent = mail.cleanContent('Hier kommt der Inhalt der E-Mail, auch HTML ist möglich');

Parameter

Parameter	Beschreibung
body (optional)	Definiert den Text oder den HTML-Body der E-Mail.

prepareEmptyContent()

Liefert einen Standard-Body für leere E-Mails inklusive Platzhalter für den Footer.

let mail = require('common/mail');
let objects = require('common/objects');

// prepareEmptyContent(content, signature, user, from);
let emptyContent = mail.prepareEmptyContent(mail.prepareBody('Body-Text in HTML'), 'optionale Signatur', objects.find('user:demo'), 'demo@agorumcore.com');

Parameter

Parameter	Beschreibung
content (optional)	Definiert den Text, den das System in den Body einfügt.
signature (optional)	Definiert eine Signatur, die das System unten an den Body einfügt. Wenn Sie diesen Parameter nicht angeben, verwendet das System die Signatur des Benutzers (user), passend zu seiner Adresse (from).
user (optional)	Wenn Sie diesen Parameter nicht angeben, verwendet das System die Signatur des aktuell angemeldeten Benutzers. Wenn Sie den Parameter from nicht angeben, verwendet das System die Standard-Signatur des angegebenen Benutzers.
from (optional)	Wenn Sie diesen Parameter angeben, lädt das System von dieser E-Mail-Adresse passend zum Parameter user die Signatur. Wenn Sie diesen Parameter nicht angeben, verwendet das System die Signatur der Standard-E-Mail Adresse des Benutzers. Hinweis: user und from müssen zusammenpassen.

prepareBody()

Liefert einen korrekt formatierten Body und orientiert sich dabei an den Einstellungen zum Paragrafenformat unter MAIN_MODULE_MANAGEMENT/customers/agorum.mail/UseParagraphFormat.

Diese Funktion können Sie in Kombination mit der Funktion prepareEmptyContent verwenden.

let mail = require('common/mail');

// prepareBody(content);
let body = mail.prepareBody('Body-Text in HTML');

Parameter

Parameter	Beschreibung
content	Definiert den Text, den das System in den Body einfügt.

isValidMailAddress()

Prüft, ob die angegebene E-Mail-Adresse valide ist, und liefert je nach Ergebnis false oder true zurück.

let mail = require('common/mail');

// isValidMailAddress(mailAddress);
let valid = mail.isValidMailAddress('"Oliver Schulze" <oliver.schulze@agorum.com>');

Parameter

Parameter	Beschreibung
mailAddress	Definiert die zu prüfende E-Mail-Adresse als String.

rawAddress()

Liefert die reine E-Mail-Adresse.

let mail = require('common/mail');

// rawAddress(mailAddress);
let rawAddress = mail.rawAddress('"Oliver Schulze" <oliver.schulze@agorum.com>');
// Ergebnis: oliver.schulze@agorum.com

Parameter

Parameter	Beschreibung
mailAddress	Definiert die zu konvertierende E-Mail-Adresse als String.

defaultDomain()

Liefert die eingetragene Standard-E-Mail-Domäne des Systems zurück.

let mail = require('common/mail');

let DEFAULT_EMAIL_DOMAIN = mail.defaultDomain();
// Result: e.g. "agorumcore.com"

Rückgabewert

Typ	Beschreibung
String	Die Standard-E-Mail-Domäne, die im System im Support Tool konfiguriert ist.