# Welcome

OTP Email verification API provided by PayPI (out of the kindness of our little hearts)

![](https://4212371277-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQUKKzCvErZb7WSnlfXJk%2Fuploads%2FBoa41I0k5RWLlDYQGhhW%2FvBig.png?alt=media\&token=2b722714-2ea0-4244-93f8-30344f9b6aec)

The EmailVerify API ensures an email address exists and that the user you are interacting with is the owner of the email address.&#x20;

We do this by sending them a 6 digit code which they then give back to you to verify that they have access to the email account.

![Example verification email](https://4212371277-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQUKKzCvErZb7WSnlfXJk%2Fuploads%2FFi1ICtOorEXQczcnmNKL%2FScreenshot%202021-10-13%20at%2013.20.29.png?alt=media\&token=4e1b57cb-a838-48e1-991b-64abe5dedf4e)

### Uses

Email verification is an incredibly useful tool to help users avoid later frustration if they've incorrectly typed their email address and gives you peace of mind that the users signing up on your site are the owners of the addresses they're using.&#x20;

* Verifying a user has typed their email correctly.
* Be sure a user owns the email address they're creating an account for.
* Ensuring an email exists before submitting a form.
* Prevent abusive use of others email addresses.&#x20;
* As a 2FA challenge

### How does it work

#### 1. Send a verification code

Retrieve the email address from the user, then send them a verification email using the `/sendCode` endpoint:

## Send verification code

<mark style="color:green;">`POST`</mark> `https://ev.apis.paypi.dev/sendCode`

This request send's a code to the given email address, which should be returned to check it is correct.&#x20;

All emails are sent from `emailverify@paypi.dev`

#### Headers

| Name                                            | Type   | Description                                        |
| ----------------------------------------------- | ------ | -------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | PayPI subscriber secret in `Bearer <token>` format |

#### Request Body

| Name                                    | Type   | Description                                        |
| --------------------------------------- | ------ | -------------------------------------------------- |
| email<mark style="color:red;">\*</mark> | string | The email address to send the verification code to |

{% tabs %}
{% tab title="200: OK Success - Email sent" %}

```javascript
{
    success: true,
    message: "Verification email sent"
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid or incorrectly formatted email given" %}

```javascript
{
    success: false,
    message:
      "Unable to send email - please check the email address and try again"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid API Key" %}

```javascript
{
    success: false,
    message: "Authorization header value invalid"
}
```

{% endtab %}
{% endtabs %}

#### 2. Check the verification code

The user should receive an email immediately with a 6 digit code, they should then give this code to you, and your backend can check it via the `/checkCode` endpoint:

## Check verification code

<mark style="color:green;">`POST`</mark> `https://ev.apis.paypi.dev/checkCode`

Checks the user's emailed code is valid.&#x20;

If this returns `success=true`, you can safely assume the user you are interacting with is the owner of that email address.

#### Headers

| Name                                            | Type   | Description                                        |
| ----------------------------------------------- | ------ | -------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | PayPI subscriber secret in `Bearer <token>` format |

#### Request Body

| Name                                    | Type   | Description                                 |
| --------------------------------------- | ------ | ------------------------------------------- |
| email<mark style="color:red;">\*</mark> | string | The email address to check the code against |
| code<mark style="color:red;">\*</mark>  | string | The 6 digit code given by the user.         |

{% tabs %}
{% tab title="200: OK Success - Code Correct" %}

```javascript
{
      success: true,
      message: "email successfully verified"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid API Key" %}

```javascript
{
    success: false,
    message: "Authorization header value invalid",
}
```

{% endtab %}

{% tab title="200: OK Unable to verify email - Code incorrect" %}

```javascript
{
    success: false,
    message: "Given code is not valid"
}
```

{% endtab %}

{% tab title="403: Forbidden Tries Exceeded" %}
To prevent abuse and brute forcing, we limit the number of checkCode requests for each email address to 20.&#x20;

This means if more than 20 requests are made you will have to send another code to your user, this will reset the limit.

```javascript
{
    success: false,
    message: "Number of tries exceeded, please request a new code"
}
```

{% endtab %}
{% endtabs %}

### [Subscribe to the API](https://app.paypi.dev/subscribe/c2VydmljZTo1OGQxZDNmMy05OWQ5LTQ3ZjYtOWJkNi02OWNkMTY1OGFmOWU=)


# FAQ

### How do I get an API key?

You can get an API key from PayPI [here](https://app.paypi.dev/subscribe/c2VydmljZTo1OGQxZDNmMy05OWQ5LTQ3ZjYtOWJkNi02OWNkMTY1OGFmOWU=) .

### What is PayPI?

PayPI allows easy API payment handling, users just need one account and can subscribe to all PayPI APIs whether they were made by the PayPI team or not.&#x20;

If you're thinking about creating your own API, head here [https://paypi.dev ](https://paypi.dev)to check out what we do.

### How much is it?

View our pricing [here](https://app.paypi.dev/subscribe/c2VydmljZTo1OGQxZDNmMy05OWQ5LTQ3ZjYtOWJkNi02OWNkMTY1OGFmOWU=)

### I need some help, who do I call... ghostbusters? Nope you should contact PayPI because ghostbusters don't do APIs.

If you want to contact someone for assistance or you want to discuss our API some more, send a message to <hello@paypi.dev> and we'll see what we can do (we're no ghostbusters but we're pretty good with APIs).

### Is this API ready for production use?

Yes! We run on AWS lambda and thus can scale to almost any demand.&#x20;

Our codes are cryptographically secure and should you need longer, or alphanumeric codes please get in touch directly.

### Is there any rate limiting?

| Endpoint     | Limit                                                                                                                                                |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/sendCode`  | No limit                                                                                                                                             |
| `/checkCode` | We limit the number of requests for a specific email address to 20. After that you will have to send another code. This is to prevent code guessing. |

### Where should I be calling your API from?

You should call our API from your backend, if you were to do it from your frontend you would have to expose your API key to the public so we do not recommend this.&#x20;

### Do you have any client libraries?

We don't currently have any client libraries, but if there's demand we'll certainly make some. Let us know at <hello@paypi.dev> if that's something you're looking for and which languages you'd like to have a library for.&#x20;

### Can I get discounts for large numbers of requests?

We do offer very competitive pricing, although we're always open to new things ;) , so shoot us an email to <hello@paypi.dev> and we can probably help you out.&#x20;

### Do you sell my data?

No! We do not make any money (or other gains) from anything other than API requests, it's that simple.&#x20;


# API Reference

## Send verification code

<mark style="color:green;">`POST`</mark> `https://ev.apis.paypi.dev/sendCode`

This request send's a code to the given email address, which should be returned to check it is correct.&#x20;

All emails are sent from `emailverify@paypi.dev`

#### Headers

| Name                                            | Type   | Description                                        |
| ----------------------------------------------- | ------ | -------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | PayPI subscriber secret in `Bearer <token>` format |

#### Request Body

| Name                                    | Type   | Description                                        |
| --------------------------------------- | ------ | -------------------------------------------------- |
| email<mark style="color:red;">\*</mark> | string | The email address to send the verification code to |

{% tabs %}
{% tab title="200: OK Success - Email sent" %}

```javascript
{
    success: true,
    message: "Verification email sent"
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid or incorrectly formatted email given" %}

```javascript
{
    success: false,
    message:
      "Unable to send email - please check the email address and try again"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid API Key" %}

```javascript
{
    success: false,
    message: "Authorization header value invalid"
}
```

{% endtab %}
{% endtabs %}

## Check verification code

<mark style="color:green;">`POST`</mark> `https://ev.apis.paypi.dev/checkCode`

Checks the user's emailed code is valid.&#x20;

If this returns `success=true`, you can safely assume the user you are interacting with is the owner of that email address.

#### Headers

| Name                                            | Type   | Description                                        |
| ----------------------------------------------- | ------ | -------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | PayPI subscriber secret in `Bearer <token>` format |

#### Request Body

| Name                                    | Type   | Description                                 |
| --------------------------------------- | ------ | ------------------------------------------- |
| email<mark style="color:red;">\*</mark> | string | The email address to check the code against |
| code<mark style="color:red;">\*</mark>  | string | The 6 digit code given by the user.         |

{% tabs %}
{% tab title="200: OK Success - Code Correct" %}

```javascript
{
      success: true,
      message: "email successfully verified"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid API Key" %}

```javascript
{
    success: false,
    message: "Authorization header value invalid",
}
```

{% endtab %}

{% tab title="200: OK Unable to verify email - Code incorrect" %}

```javascript
{
    success: false,
    message: "Given code is not valid"
}
```

{% endtab %}

{% tab title="403: Forbidden Tries Exceeded" %}
To prevent abuse and brute forcing, we limit the number of checkCode requests for each email address to 20.&#x20;

This means if more than 20 requests are made you will have to send another code to your user, this will reset the limit.

```javascript
{
    success: false,
    message: "Number of tries exceeded, please request a new code"
}
```

{% endtab %}
{% endtabs %}

{% file src="/files/L2a3aSMAllpZY1WCLzlm" %}


