Skip to content

Confirmation

You can optionally require a user to confirm their registration via email by using the email confirmation feature of the Users module.

When a confirmation email is sent, the user is put into a "pending" state. You can view Pending Users in the Users section of the Webmin.

Mailgun Account Required

A valid Mailgun account and the proper configuration must be set up to use the email confirmation feature. See the Mailgun Config section for more information.

Confirmation Table

When using the confirmation feature, the following parameters can be supplied in the confirmation table. Not all parameters are required.

Parameters

Name Description Type Required
from_email The senders email address. This is usually your address. String Y
subject The registration email subject line. String Y
email_tpl Identifier for a custom registration email template. String N
tpl_keys Additional template keys for the registration email template. Table N

Client-Side Example

You initialize the creation and confirmation using the client-side core.users.create method.

Default Confirmation

local function onUserCreate( evt )
  if evt.error then
    print(evt.error)
  else
    if evt.result.confirmation == 'pending' then
      --email was sent successfully
    end
    print(evt.result.user_id) -- new user id
  end
end

core.users.create({
  username = "SuperUser",
  password = "1234abcd",
  email = "newuser@somemail.com",
  confirmation = {
    from_email = "register@funrun.com",
    subject = "Please confirm your registration.",
  }
}, onUserCreate)

Important

Passwords are hashed before being sent to the server. Do not try to hash the passwords yourself.

Response Event

When creating a user with email confirmation, the response result will be a table containing the newly registered users user_id, and a confirmation key.

The confirmation key will contain the email sent state as a string with a value of 'pending' on success, or 'failed' otherwise.

Default Template

By default the following email template is sent to the users email. The only required template key is the {* confirm_link *} which is replaced automatically with the proper link to confirm the user.

Required Template Key

If you do not include the {* confirm_link *} template key in the email template, the user will have no way to confirm the registration.

You can edit the default template messaging if you wish, but to add additional template keys you must create a custom template, which is explained in the next section.

Template Location: /home/coronium/templates/registration/email.tpl

Hello,

You have requested to sign up for our app. 

Please confirm your registration by clicking the link below:

{* confirm_link *}

Thank you.

Custom Templates

To create a custom email template, you create, and place your custom template file in the /home/coronium/templates/registration/ directory, and pass a reference to the template file in the confirmation.email_tpl parameter.

At a minimum you must include the {* confirm_link *} template key in your custom template for the auto-generated confirmation link, but you can also supply other template keys by passing a table of key/value pairs to the confirmation.tpl_keys parameter.

You can create as many custom email templates as you wish.

Template Example

Template Location: /home/coronium/templates/registration/custom_email.tpl

Hello {{ username }},

Thank you for signing up to use the {{ app_name }} application.

Please click the following link to confirm your registration:

{* confirm_link *}

Have a nice day.

User Create Code

core.users.create({
  username = "SuperUser",
  password = "1234abcd",
  email = "newuser@somemail.com",
  confirmation = {
    from_email = "register@funrun.com",
    subject = "Please confirm your registration.",
    email_tpl = "custom_email.tpl",
    tpl_keys = {
      username = "Timmy",
      app_name = "FunRun"
    }
  }
}, onUserCreate)

Result

Hello Timmy,

Thank you for signing up to use the FunRun application.

Please click the following link to confirm your registration:

http://your.coronium.host/_confirmation?code=<generated-confirmation-code>

Have a nice day.

Important Notes

When using the email confirmation feature you must provide both the email key and the confirmation.from_email key or the confirmation will not be sent.

Do not add a confirm_link key to the confirmation.tpl_keys entry. Just be sure to include it in your custom template and it will be populated automatically with the correct confirmation link when the email is sent.

Confirmation Page

Once the user clicks the confirmation link in the registration email, they will be taken to the confirmation landing page.

When the user is confirmed they will be marked as active in the users database.

To customize the landing page, you can edit the following resources.

  • Template: /home/coronium/pages/_coronium/registration/confirmation.tpl
  • Lua Code: /home/coronium/pages/_coronium/registration/confirmation.lua

See the Pages usage guide for information about how to work with these files.

Resending Confirmation

To resend a users confirmation email, you must first login the user with their current username and password, and then call the resendConfirmation method with the users unique identifier.