Mailgun plugin

Validate an email address by using Mailgun API

Usage

Mailgun is one of most popular email services. It also provides free API to validate an email address based on:

Mailbox detection
Syntax checks (RFC defined grammar)
DNS validation
Spell checks
Email Service Provider (ESP) specific local-part grammar (if available)

To use it, you need to sign up for a Mailgun account and get a free API key. The following piece of code is the starting point to use the Mailgun plugin:

<html>
    <head>
        <link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
    </head>
    <body>
        <form id="demoForm" method="POST">...</form>

        <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.3/es6-shim.min.js"></script>
        <script src="/vendors/@form-validation/umd/bundle/popular.min.js"></script>
        <script src="/vendors/@form-validation/umd/plugin-mailgun/index.min.js"></script>

        <script>
            document.addEventListener('DOMContentLoaded', function(e) {
                FormValidation.formValidation(
                    document.getElementById('demoForm'),
                    {
                        fields: {
                            ...
                        },
                        plugins: {
                            ...,
                            mailgun: new FormValidation.plugins.Mailgun({
                                apiKey: ...,
                                field: ...,
                                message: ...,
                                suggestion: ...,
                            }),
                        },
                    }
                );
            });
        </script>
    </body>
</html>

The sample code above assumes that the FormValidation files are placed inside the vendors directory. You might need to change the path depending on where you place them on the server.

Options

Option	Type	Description
`apiKey`*	`String`	The API key provided by Mailgun
`field`*	`String`	The field name that will be validated
`message`*	`String`	Error message indicates the input is not valid
`suggestion`	`Boolean`	Show suggestion if the email is not valid. By default, it is set to `false`

Using the npm packages

If you are using a bundler such as Webpack, Rollup, Parcel or Vite, etc., to bundle your application, then it's recommended to use the FormValidation NPM packages.

Install the packages:

$ npm install @form-validation/bundle
$ npm install @form-validation/plugin-mailgun

Import and use the Mailgun plugin:

import { formValidation } from '@form-validation/bundle/popular';
import { Mailgun } from '@form-validation/plugin-mailgun';

formValidation(
    document.getElementById('demoForm'),
    {
        fields: {
            ...
        },
        plugins: {
            mailgun: new Mailgun({
                ...
            }),
            ...
        },
    }
);

Basic example

You can use the following sample email addresses to test with your app.

Description	Sample
Does not meet Gmail minimum local-part length of 6 characters	`john@gmail.com`
Invalid, because gmaill.com does not have valid MX records	`john.smith@gmaill.com`
Invalid because while microsoft.io does not have any MX records, it does have fallback A records, but alas no Mail Exchanger responds	`john@microsoft.io`
Meets Gmail 6 character minimum and all other requirements	`john.smith@gmail.com`
Meets pure syntax checks	`"hello world"@domain.com`
Suggest new email address	`hello@gail.com`

The following sample code demonstrates how to use Mailgun plugin to validate email address which its form is made with Tachyons plugin:

<html>
    <head>
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" />
        <link rel="stylesheet" href="https://unpkg.com/tachyons@4.10.0/css/tachyons.min.css" />
        <link rel="stylesheet" href="/vendors/@form-validation/umd/styles/index.min.css" />
    </head>
    <body>
        <form id="demoForm" method="POST">
            <div class="cf mb2">
                <div class="fl w-100">
                    <div class="fl w-25 pa2">Email address</div>
                    <div class="fl w-40">
                        <input type="text" class="input-reset ba b--black-20 pa2 mb2 db w-100" name="email" />
                    </div>
                </div>
            </div>

            <div class="cf mb2">
                <div class="fl w-100">
                    <div class="fl w-25 pa2"></div>
                    <div class="fl w-50">
                        <button type="submit" class="ba b--black-20 bg-blue white ph3 pv2 br2">Submit</button>
                    </div>
                </div>
            </div>
        </form>

        <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.3/es6-shim.min.js"></script>
        <script src="/vendors/@form-validation/umd/bundle/popular.min.js"></script>
        <script src="/vendors/@form-validation/umd/plugin-tachyons/index.min.js"></script>
        <script src="/vendors/@form-validation/umd/plugin-mailgun/index.min.js"></script>

        <script>
            document.addEventListener('DOMContentLoaded', function (e) {
                FormValidation.formValidation(document.getElementById('demoForm'), {
                    fields: {
                        email: {
                            validators: {
                                notEmpty: {
                                    message: 'The email address is required',
                                },
                                emailAddress: {
                                    message: 'The input is not a valid email address',
                                },
                            },
                        },
                    },
                    plugins: {
                        trigger: new FormValidation.plugins.Trigger(),
                        tachyons: new FormValidation.plugins.Tachyons(),
                        submitButton: new FormValidation.plugins.SubmitButton(),
                        icon: new FormValidation.plugins.Icon({
                            valid: 'fa fa-check',
                            invalid: 'fa fa-times',
                            validating: 'fa fa-refresh',
                        }),
                        mailgun: new FormValidation.plugins.Mailgun({
                            // Put your Mailgun public API key here
                            apiKey: '...',
                            field: 'email',
                            message: 'The email address is not valid',
                            suggestion: true,
                        }),
                    },
                });
            });
        </script>
    </body>
</html>

Changelog

v2.4.0

The plugin can be enabled or disabled using the enablePlugin and disablePlugin methods

v2.0.0

Add the npm package

v1.0.0

First release

L10n plugin MandatoryIcon plugin