Introduction

The main goal of this project is to ensure accurate and authentic email addresses for your app, preventing user errors such as typos or the use of fake email addresses (e.g., temporary or disposable emails during the registration process). Having accurate email addresses is crucial for maintaining effective communication with your users.

Our service checks:

• Whether we can receive the user's email (and that they can send).
• Whether the user's email is sent from authorized servers (SPF check) and is correctly digitally signed (DKIM check).

If all checks pass, we will instantly notify your application by sending a `verified-email` parameter. You can then use this to retrieve the actual email address via our Get verification details method.

Frontend integration

To display instructions to users on how to verify their email address, we provide a JavaScript library for easy frontend integration. This allows you to start our verification flow UI directly from your web app, but you also have the option to fully implement your own UI.

Integration options

You can integrate with our service by including a small (~14 KB) JavaScript file in your web application. We currently offer two types of frontend integration:

• Postback flow with our UI: Initiate the flow with a single JavaScript method. Upon successful verification, the page will reload with the `verified-email` parameter, which you can process on your backend.
• JavaScript flow with our UI: Offers a more seamless integration, giving you greater control. In this case, you implement a custom JavaScript method called `verifyAutoInboxHandler`, which is triggered by our flow UI to provide you with the verification details.
• JavaScript flow with your own UI: This option offers the most flexibility by allowing you to use your own user interface. We provide JavaScript callbacks to notify you about the current email verification progress. You will also need to implement a custom JavaScript method called `verifyAutoInboxHandler`.

We do not use an IFrame for the verification flow with our UI. Instead, the integration flow UI is dynamically injected directly into your webpage, providing a seamless user experience. However, IFrame support can be considered for future versions upon request.

Postback flow

<script src="https://autoinbox.dev/libs/sdk-0.9.0.min.js"></script>
<script>
    AutoInbox.verify({ 
        verificationId: "1f6g952jxacve9r8sb5gb14ker"
    });
</script>

curl -H "X-Account-ID: YOUR_ACCOUNT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://api.autoinbox.dev/v1/verifications/1f6g952jxacve9r8sb5gb14ker

{
  "isOk": true,
  "result": {
    "id": "1f6g952jxacve9r8sb5gb14ker",
    "status": "confirmed",
    "emailFrom": "your.verified.email@example.com",
    "security": {
      "spfVerificationStatus": "PASS",
      "spfMatchingDomain": "_netblocks.google.com",
      "dkimVerificationStatus": "PASS",
      "dkimSelector": "20230601",
      "mailServerAddress": "209.85.222.44"
    }
  }
}

JavaScript flow

Flow demonstration with our UI

For now, please check the HTML source code in `Flow demonstration`.

JavaScript flow with your own UI

When you want to start receiving live verification notifications in your app, simply call the following function:

AutoInbox.verify({
    //NOTE: you get verificationId from your backend
    //(you receive it in response when calling our API)
	verificationId: "3bc4crxrtzzb5z87nyvwb0snhy",
	jsMode: true,
	jsModeOptions: {
		noUI: true,
		accountId: "your-acc-id" //required for this mode
    }
});

Callback stub structure for your `verifyAutoInboxHandler` implementation:

function verifyAutoInboxHandler(args) {
	if (args.action === 'success') {
		// We are done, email has been verified !
		// You can now call your backend with
		// verificationId to get unmasked email,
		// you can update your UI, etc.
		return true;
	}

	if (args.action === 'pending') {
		// Still waiting for email.
		// You can update your UI from here.
		return true;
	}

	if (args.action === 'timeout') {
		// We didn't receive email for too long.
		// You can update your UI from here.
		// You can also wait for more time by
		// calling AutoInbox.verify(...) again.
		return true;
	}

	if (args.action === 'issue') {
		// There was some issue during verification.
		// You can show args.issue message to the user.
		return true;
	}

	if (args.action === 'error') {
		// Something went wrong, you can
		// show args.issue message to the user.
		return true;
	}

	return false;
}

Example of JSON object received as argument in `verifyAutoInboxHandler` during email verification:

Flow demonstration with your UI

Please also check the HTML source code in the `Flow demonstration`.