sendConfirmation

The sendConfirmation method of the emailConfirmationService performs the act of generating, storing and emailing a confirmation and its related data.

You call this method from services or controllers to start the process of performing a confirmation. You register listeners for the events that are fired using Platform Core Events API and the @Listener annotation (see example code below).

The user will receive an email containing the url to click to perform the confirmation, at which point an event will be received by your application indicating who confirmed and what the nature of that confirmation was.

Examples

// Send a simple confirmation
emailConfirmationService.sendConfirmation(
    to:params.email,
    subject:"Please confirm!")

// Send a confirmation with custom from: address
emailConfirmationService.sendConfirmation(
    from:'helpdesk@mycorp.com',
    to:params.email,
    subject:"Please confirm!")

// Send a confirmation with custom email template
emailConfirmationService.sendConfirmation(
    view:'/mailtemplates/confirm_signup',
    to:params.email,
    subject:"Please confirm!")

// Send a confirmation with custom email template and model
emailConfirmationService.sendConfirmation(
    model:[account:userAccount, promoCode:'NEWSIGNUP'],
    view:'/mailtemplates/confirm_signup', 
    to:params.email,
    subject:"Please confirm!")

// Send a confirmation with application id data
emailConfirmationService.sendConfirmation(
    to:params.email,
    subject:"Please confirm!",
    id:userAccount.ident())

// Send a confirmation with custom event namespace
emailConfirmationService.sendConfirmation(
    to:params.email,
    subject:"Please confirm!",
    eventNamespace:'plugin.myPlugin')

// Send a confirmation with custom event prefix and namespace
// The event topic would be 'signup.confirmed' in the specified namespace
emailConfirmationService.sendConfirmation(
    to:params.email,
    subject:"Please confirm!",
    event:'signup',
    eventNamespace:'plugin.myPlugin')

Once a confirmation has been sent like this, you use the Events to receive updates when people confirm or fail to confirm.

Events

Platform Core Events API events are generated when the user clicks through the link in the email successfully, or if they click on an invalid (already used or malformed) link or a link expires because it has not been used within the timeout period (default: 30 days).

The events that can occur are:

Here are some examples of listening for these events:

import grails.event.Listener

class MyService {

    // Standard confirmed event and namespace
    @Listener(topic:'confirmed', namespace:'plugin.emailConfirmation') 
    def userConfirmed(info) {
        log.info "User ${info.email} successfully confirmed with application id data ${info.id}"
        return [controller:'userProfile', action:'welcomeNewUser']
    }

    // Standard timeout event and namespace
    @Listener(topic:'timeout', namespace:'plugin.emailConfirmation') 
    def userConfirmationTimedOut(info) {
        log.info "A user failed to confirm, the token in their link was ${info.token}"
    }

    // Standard timeout event and namespace
    @Listener(topic:'invalid', namespace:'plugin.emailConfirmation') 
    def userConfirmationWasInvalid(info) {
        log.info "User ${info.email} failed to confirm for application id data ${info.id}"
        return [controller:'userProfile', action:'invalidConfirmationHelp']
    }

    // Custom confirmed event prefix and namespace set to 'app' when requesting confirmation
    @Listener(topic:'registration.confirmed') 
    def registrationConfirmed(info) {
        log.info "User ${info.email} successfully confirmed with application id data ${info.id}"
        return [controller:'userProfile', action:'welcomeNewUser']
    }

    // Custom confirmed event prefix and using a custom plugin namespace
    @Listener(topic:'changePassword.confirmed', namespace:'plugin.mySecurity') 
    def changePasswordConfirmed(info) {
        log.info "User ${info.email} successfully confirmed with application id data ${info.id}"
        return [controller:'security', action:'doChangePassword']
    }
}

Method Arguments

Supported Map arguments