Quickstart

Log in to your new account (your did sign up, didn't you? The basic tier is free forever, so you have nothing to lose.) and find your public API key. It's right at the top of your Account page.

Next, include our small (~1800 bytes) javascript library in your signup page

<script type="text/javascript" src="https://cdn.clicktoverify.net/ctv.js"></script>

In the onsubmit handler for your signup form, or another appropriate place, reate a new verifier object:

verifier = new CTV();

Leave the rest to us. One call to the .verify method with the email you're trying to verify, your public_api_key (which you got from the account resource above), and a success callback, which will be called once the user as clicked on the link in the verification email and verified their email address. If you're less of an optimist, you can also include an error callback. Both of these functions receive an ordinary, plain XMLHttpRequest object that comes back from our servers. xhr.response.detail will usually have a human-readable description of the error.

verifier.verify({
     email: "user@example.com",
     public_api_key: "71917c69-b8e8-4bbf-adf5-c2de3b89c17e",
     success: function(xhr) {
          $("#results-area").text("You're verified!");
     },
     error: function(xhr) {
          $("#results-area").text("Something went wrong!");
          console.log(xhr.response.detail);
     }
});

Additional Integration Help

I know you don't have time to fiddle endlessly with your email verification code. In fact, that's the whole reason I built this service. If you're having any trouble at all setting any of this up, I want to help. My personal email address (also in your welcome email, if you're already signed up) is ctindall@gmail.com. For urgent issues (e.g. "My clients can't sign up and I'm losing business!"), please use ctindall+ctv-urgen@gmail.com instead.


Advanced Topics

ClickToVerify is easy to integrate with your signup process, but we also provide room to grow, with some additional advanced features

Custom Post-Verify Page

By default, after clicking on the verification email in their inbox, they will be taken to a generic "thank you" page that looks like this:




If you would prefer to send them to a page that is specific to your application (for example, the login page), you can set the post_verify_url option when making your initial verifier.verify() call in your signup form:

verifier.verify({
     ...
     post_verify_url: "https://example.com/login?msg=welcome", //new customers will be redirected here after verifying in their email		  
     ...
});

Now, in addition to the success callback activating on your signup page, the browser tab where the user clicked the verify link will be redirected to your login page. If you want both tabs to redirect to the same URL, simply do the same in the success callback as well:

verifier.verify({
     ...
     success: function(xhr) { window.location = xhr.response.post_verify_url; }
     ...
});

Account-wide Default

You can also change this setting on an account-wide basis on your Account page.

Using Tokens

The example shown above uses your public_api_key, which you will need to make available to your client-side Javascript, either by embedding it in the Javascript, or by otherwise storing it in the HTML DOM, or fetching it from your server or other storage mechanism. In any of these cases, there exists a potential for abuse, since anyone with this token can send verification emails to unsolicited email addresses (bad for our email reputation, and thus deliverability) using your account (bad because it costs you money). We use several fraud-mitigating mechanisms to prevent this as much as possible, and will refund credits where warranted, but if you want to have more control over when and who is creating verification emails under your account, you can do so by using verification tokens.T

First, create set our account to require tokens when creating new verifications. This can be done for your Account.

Minting Tokens

Creating tokens requires processing on the server-side of your application. It's not suitable for applications that are purely static. The upside is this puts you in control, and lets you get ahead of abuse trends that affect your particular business.

Generating a verification token is as easy as a POST to https://api.clicktoverify.net/tokens/ using your private API key.

[cam@laptop ~]$ curl -X POST \
-H "Authorization: Token $api_key" \
https://api.clicktoverify.net/tokens/

{"token":"2e6ba3f9-9b90-4cd8-acb4-7a0521639950"}

...or a simple example in PHP:

$API_KEY = "b2a5a776efeb19beca05ca9cde6c08181c61628d";

function get_token() {
    global $API_KEY;
    $ch = curl_init();
    
    curl_setopt($ch, CURLOPT_URL, "https://api.clicktoverify.net/tokens/");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_POST, 1);
    
    $headers = array();
    $headers[] = "Authorization: Token $API_KEY";
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    $result = json_decode(curl_exec($ch));
    if (curl_errno($ch)) {
        echo 'Error:' . curl_error($ch);
    }
    curl_close ($ch);

    return $result->token;
}

echo get_token();

From there, you can either fetch the token in your own code, and use it in in your call to the .verify method, in lieu of your public_api_key...

verifier.verify({
    email: "user@example.com",
    token: "2e6ba3f9-9b90-4cd8-acb4-7a0521639950",
    success: function(xhr) {
        $("#results-area").text("You're verified!");
    },
    error: function(xhr) {
        $("#results-area").text("Something went wrong!");
        console.log(xhr.response.detail);
    }
});

...or so long as your server-side URL returns a new, unique token on every POST request, in a JSON request under the key token like this:

{"token": "2e6ba3f9-9b90-4cd8-acb4-7a0521639950"}

...then the ctv.js library will allow you to take a little shortcut by simply specifying this URL in place of the token:

verifier.verify({
    ...
    token: "https://example.com/ctv-verification-token.php",
    ...
});

Webhooks

Verifications can optionally be POSTed to a URL of your choosing. This endpoint can be set in your Account page.

The URL should be able to handle form-encoded POST requests of the following form:

POST http://yourdomain.example.com/your_webhook_url
event_type:   verification_clicked_link
email: user@example.com 
token: 2e6ba3f9-9b90-4cd8-acb4-7a0521639950
created_from_public_key: false

Your webhook URL will receive such an event whenever one of your clients clicks the verification button in an email, and thus verifies their ownership of this email address.

The token field will only appear if the verification was created from a token.

The created_from_public_key field will always appear, and container true if the verification was created from a public, or false otherwise.

Note that, for security purposes, this URL should include a long, randomly-generated string, so that other actors are not able to report events to it, but we hope to roll out better authentication and secutity options for our webhook feature soon.