Introduction

emauth is a simple authentication tool for developers. It is the easiest way to answer the question: "Does X user control Y email address?"

You can use it by making an HTTP request to emauth.io, like this:


curl 'https://emauth.io/verify?email=alice@example.com'
      

That request waits while an email with a verification link is sent to alice@example.com. When Alice clicks on the link, the request returns a 200 HTTP status code. If something goes wrong, it returns a 4xx or 5xx code and a message. If this happens, it's usually an invalid email address or timeout (default 60 seconds).

Try it:

Enter an email address:

Submit from your browser:


fetch("https://emauth.io/verify?email=");
      

Status:

Or you can use curl:


curl 'https://emauth.io/verify?email='
      

Response format

Upon successful verification, emauth.io returns a signed JSON Web Token (JWT), which contains the email address verified, and the iat ("issued at") claim. It's not necessary to use this token. Some applications will want to ensure that the verification just happened, in which case the token can be ignored. But there are also cases where it may be useful to use the JWT approach, so they're provided.

The signature of the tokens can verified using the public key available at emauth.io/pubkey. Note that this key may change, so if you get a token that fails verification, we recommend checking if there's a new public key before failing the request.

Uses

emauth tells you that someone owns an email address, but what you do with that information is up to you. You could use this to add 2FA to an existing application. Or maybe you just want to implement really simple auth in front of a private website for sharing photos with your family, checking emails against a whitelist. Or maybe you're rolling your own newsletter and want to verify signups before sending emails. It's an elegant tool that can be combined easily with other services.

Go Pro

You're welcome to use emauth for free if it suits your needs. It should be useful for many simple applications with small numbers of users. However, there are some limitations. Any given email address can only be verified a certain number of times each month. Also, in order to protect the email sender reputation for emauth.io, we aggressively blacklist ip addresses that repeatedly make requests to invalid email addresses.

If you subscribe to emauth pro for $4/month, you can make 512 verifications per month, of any combination of email addresses.

If you need more verifications than this (for example if you want to use emauth for a public app with many users), please contact sales at sales@emauth.io.

Once you've subscribed to emauth pro, you can get an auth token like this:


curl 'https://emauth.io/token?email=subscriber@example.com'
      

Click the link in the email sent to you (yay dogfooding), and a token will be returned. You can then use it in verification requests like this:


curl 'https://emauth.io/verify?email=alice@example.com&token=TOKEN'
      

You can also pass the token in a cookie, or with the Authorization: Bearer TOKEN header.

If you run into any problems with emauth pro, please contact us at support@emauth.io.

API

There are a few helpful query parameters.

timeout

Timeout in seconds. Default is 60. Can be between 5 and 300 (5 minutes).

Example


curl 'https://emauth.io/verify?email=alice@example.com&timeout=15'
      

source

Source entity for the request. Let's you change the email message to say it's from your business/app istead of emauth.

Example


curl 'https://emauth.io/verify?email=alice@example.com&source=example.com'
      

from

Changes the email from name.

Example


curl 'https://emauth.io/verify?email=alice@example.com&from=Alice%20Doe'
      

Privacy

We do not save email addresses for any purpose other than internal analytics, ie to count how many times an email address has been verified for billing purposes. This data is not sold or passed on in any way, and we will never send emails to the addresses other than for authentication purposes.

Updates

If you'd like to stay up to date on future developments, consider subscribing to our newsletter: