Mail hook, membership'te belirli bir olay gerçekleştiğinde şablonlu bir e-posta gönderir: UserCreated'da bir hoş geldin maili, UserPasswordChanged'da bir güvenlik bildirimi, RoleUpdated'da yöneticilere bir uyarı.

Ayrılmış adlara sahip iki mail hook, aktivasyon ve parola sıfırlama akışlarını da çalıştırır.

Başlamadan önce#

Mail'ler, membership'in mail_providers alanında tanımlı mail sağlayıcılarından biri (SMTP, SendGrid ya da Mailchimp Transactional) üzerinden gönderilir. Bkz. Membership'ler.

Mail hook nesnesi#

json

{
	"_id": "66f1c0d2a4b5c6d7e8f901b0",
	"name": "Welcome",
	"slug": "welcome",
	"description": "Sent to every new user",
	"event": "UserCreated",
	"status": "active",
	"mailProvider": "company-smtp",
	"fromName": "My Company",
	"fromAddress": "no-reply@example.com",
	"sendToUtilizer": false,
	"recipients": [
		{ "displayName": "{{document.firstname}} {{document.lastname}}", "emailAddress": "{{document.email_address}}" }
	],
	"mailSubject": "Welcome to My Company, {{document.firstname}}!",
	"mailTemplate": "<h1>Welcome, {{document.firstname}}!</h1><p>Your username is <b>{{document.username}}</b>.</p>",
	"membership_id": "66f1c0d2a4b5c6d7e8f90123"
}

Alan	Zorunlu	Açıklama
`name`	evet	Görünen ad. `User Activation` ve `Reset Password` özeldir.
`slug`	hayır	Verilmezse addan türetilir.
`description`	hayır
`event`	evet	Mail'i tetikleyen olay tipi.
`status`	evet	`active` ya da `passive`.
`mailProvider`	evet	Membership'in mail sağlayıcılarından birinin `slug`'ı.
`fromName`, `fromAddress`		Gönderen. Mail sağlayıcınızın gönderim yapmasına izin verilen bir adres kullanın.
`sendToUtilizer`		`true`, mail'i olaya yol açan kullanıcıya da gönderir (örneğin parolasını değiştiren kullanıcıya).
`recipients`		Sabit ya da şablonlu alıcılar; her biri `{ "displayName", "emailAddress" }`.
`mailSubject`		Konu. Placeholder içerebilir.
`mailTemplate`		Placeholder'lı HTML gövde ya da Mailchimp şablon adı (bkz. aşağısı).
`variables`		Mailchimp merge değişkenleri, bkz. aşağısı.

Alıcılar e-posta adresine göre tekilleştirilir.

Şablonlar#

Konular, gövdeler ve alıcılar, olaydan doldurulan çift süslü parantezli placeholder'lar kullanır:

Placeholder	Değer
`{{event_type}}`, `{{utilizer_id}}`, `{{event_time}}`, `{{membership_id}}`	Olayın alanları
`{{document.<field>}}`	Kaynağın değişiklikten sonraki halinin bir alanı
`{{prior.<field>}}`	Kaynağın değişiklikten önceki halinin bir alanı

Örneğin UserPasswordChanged'da kullanıcıya gönderilen bir bildirim:

json

{
	"name": "Password Changed Notice",
	"event": "UserPasswordChanged",
	"status": "active",
	"mailProvider": "company-smtp",
	"fromName": "My Company Security",
	"fromAddress": "security@example.com",
	"recipients": [ { "displayName": "{{document.firstname}}", "emailAddress": "{{document.email_address}}" } ],
	"mailSubject": "Your password was changed",
	"mailTemplate": "<p>Hi {{document.firstname}},</p><p>The password of your account was changed on {{event_time}}. If this wasn't you, contact us immediately.</p>"
}

Değerler güvenli şekilde yerleştirilir:

HTML gövdede her değer HTML-encode edilir; böylece adına işaretleme koyan bir kullanıcı bunu mail'lerinize enjekte edemez; şablonunuzun kendi işaretlemesi korunur;
konuda, değerlerdeki satır sonları boşlukla değiştirilir;
çözülemeyen placeholder'lar olduğu gibi bırakılır.

Mailchimp şablonları#

MailChimp sağlayıcısıyla ErtisAuth gövdeyi kendisi oluşturmaz: Mailchimp Transactional'dan, saklanan şablonlarınızdan birini göndermesini ister.

mailTemplate, Mailchimp'teki şablonun adıdır.
variables, şablona aktarılan merge değişkenleridir; değerleri placeholder içerebilir:

json

"variables": [
	{ "key": "FIRST_NAME", "value": "{{document.firstname}}" },
	{ "key": "USERNAME", "value": "{{document.username}}" }
]

Aktivasyon ve parola sıfırlama mail'leri#

İki mail hook adlarıyla bulunur ve hesap akışları tarafından, kendi verileriyle kullanılır:

Ad	Olay	Kullanan	Placeholder'lar
`User Activation`	`UserCreated`	Hesap aktivasyonu	`{{user.<field>}}`, `{{activationLink}}`
`Reset Password`	`UserPasswordReset`	Parola sıfırlama	`{{user.<field>}}`, `{{resetPasswordLink}}`

Tam olarak bu ada, yukarıdaki olaya ve active durumuna sahip olmalıdırlar. Olaylarının sıradan mail hook'ları olarak değil, yalnızca kendi akışları tarafından gönderilirler.

Gönderim#

Mail'ler bir arka plan kuyruğundan asenkron olarak gönderilir; olaya yol açan istek onları beklemez.
Her mail, alıcılarıyla (ve hatayla) bir MailhookMailSent ya da MailhookMailFailed olayı kaydeder; bir mail ulaşmadığında bakılacak yer burasıdır.
Mail'ler yeniden denenmez.

Endpoint'ler#

Tüm route'lar /memberships/{membershipId} altındadır.

Metot	Route	Açıklama	Yetki
`GET`	`/mailhooks/{id}`	Mail hook getirme	`mailhooks.read.{id}`
`GET`	`/mailhooks`	Mail hook'ları listeleme	`mailhooks.read`
`POST`	`/mailhooks/_query`	Mail hook'ları sorgulama	`mailhooks.read`
`POST`	`/mailhooks`	Mail hook oluşturma	`mailhooks.create`
`PUT`	`/mailhooks/{id}`	Mail hook güncelleme	`mailhooks.update.{id}`
`DELETE`	`/mailhooks/{id}`	Mail hook silme	`mailhooks.delete.{id}`
`DELETE`	`/mailhooks`	Birden fazla mail hook silme	`mailhooks.delete`

Oluşturma 201 Created döner; ad, mail sağlayıcısı, durum (active / passive) ya da olay tipi eksik veya geçersizse 400 ModelValidationError, slug kullanımdaysa 409 MailHookAlreadyExists. Güncelleme mail hook'u tamamen değiştirir; hiçbir değişiklik içermeyen bir güncelleme 409 IdenticalDocumentError döner. Silme 204 No Content döner.

Olaylar#

MailhookCreated, MailhookUpdated, MailhookDeleted ve gönderim olayları MailhookMailSent ile MailhookMailFailed. Bkz. Olaylar.