Confirmations
Require a user to confirm their email by using the users.sendConfirmationLink method of the Users module.
When a confirmation email is sent, the user is in 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 Options
The following keys are available to pass to the options parameter of the users.sendConfirmationLink method depending on whether you are using the default or a custom template.
Name | Description | Type | Required |
---|---|---|---|
from_email | The senders email address. This is usually your address. | String | Y |
subject | The confirmation email subject line. | String | Y |
email_tpl | Identifier for a custom confirmation email template. | String | N |
tpl_keys | Additional template keys for the custom confirmation email template. | Table | N |
Server-Side Example
You need a registered user to send a confirmation. Generally you create a user with the user.register method, making sure to supply an email address, and then follow up with the users.sendConfirmationLink method.
Default Confirmation
function api.createAndConfirm(input) -- Register a user local user_id, err, code = core.users.register("Wolly", nil, "Space Race", { email = "wolly@home.com" }) if not user_id then return core.error(err, code) end -- Send the confirmation local res, err, code = core.users.sendConfirmationLink(user_id, { from_email = "yourapp@domain.com", subject = "Please confirm your registration.", }) if not res then return core.error(err, code) end return res end
Response
On success, the sendConfirmationLink method will return a String indicating the sent state from Mailgun, which can be "OK" or "Failed". Otherwise a nil, error, and error code is returned.
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 email_tpl
parameter of the options
table.
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 tpl_keys
parameter of the options
table.
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.
Custom Confirmation
function api.createAndConfirm(input) -- Register a user local user_id, err, code = core.users.register("Wolly", nil, "Space Race", { email = "wolly@home.com" }) if not user_id then return core.error(err, code) end -- Send the confirmation local res, err, code = core.users.sendConfirmationLink(user_id, { from_email = "yourapp@domain.com", subject = "Please confirm your registration.", email_tpl = "custom_email.tpl", tpl_keys = { username = "Wolly", app_name = "Space Race" } }) if not res then return core.error(err, code) end return res end
Result
Hello Wolly, Thank you for signing up to use the Space Race 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
Do not add a confirm_link key to the tpl_keys
parameter. 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.