Introduction

This REST allows you to generate unique verification email addresses for your application.

You can retrieve confirmed email addresses after we send a webpage postback or call your `verifyAutoInboxHandler` JavaScript callback method.

Authentication

All API calls must be authenticated by including both the `X-Account-ID` and `Authorization` headers in the request.

The `X-Account-ID` is the unique identifier assigned to your account when you sign up.

The `Authorization` header must contain the Bearer authentication scheme, where you provide the access token (secret) issued to you upon signing up.

Your access token is randomly generated and displayed to you only once. You should not share it with anyone. We store a strongly hashed version of the token, meaning that if you lose it, we cannot retrieve the original token. In such cases, the only option is to reset the token to a new one (note: this feature is currently not supported for free accounts).

POST/v1/verifications

Generate new email verification

This endpoint allows you to generate a unique verification ID that is used on your frontend to initiate the verification flow UI.

We will store the verification ID and associated details on our server for up to 24 hours. After that, it will be automatically deleted.

If you have retrieved the result using the `Get verification details` endpoint, you can optionally delete this resource before the 24-hour period by calling the `Delete verification` endpoint.

To prevent overusing your daily or monthly quota of generated verification IDs, we recommend caching the generated verification ID on your side for a few hours.

For example, you can use the following caching strategies:

  • For unauthenticated users: Cache the generated verification ID using the hashed user's IP, such as SHA-256 with a salt, or better yet, HMAC SHA-256.
  • For authenticated users: Cache the verification ID using the username, session ID, or a similar identifier.

Optional payload parameters

  • Name
    domain
    Type
    string
    Description

    Which domain should we use for generated mailbox? If not provided, the default value of `confirm.withyour.email` will be used. There is an option to use your own domain. Please contact us for more information.

  • Name
    securityLevel
    Type
    string
    Description

    How strict should we be when verifying the authenticity of incoming email?

    One of the following values: `spfAndDkimMustPass`, `spfOrDkimMustPass`, `spfMustPass`, `dkimMustPass` or `none`.

    If not provided, we will use default value of `spfAndDkimMustPass`.

  • Name
    maxValidityInMinutes
    Type
    number
    Description

    The number of minutes the user has to verify their email address. Value can be from 1 minute to 1440 minutes. If not provided, we will use default value of 1440 minutes (24 hours).

  • Name
    debug
    Type
    boolean
    Description

    If you're testing the integration and have registered our script with the debug option `AutoInbox.verify({ ..., debug: true })`, and you want to simulate a processed email without sending a real one, you must set this parameter to `true`. Default value is `false`.

Request example: use all defaults

cURL
curl -H "X-Account-ID: YOUR_ACCOUNT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ }' \
     -X POST https://api.autoinbox.dev/v1/verifications

Request example: override the default `maxValidityInMinutes`

cURL
curl -H "X-Account-ID: YOUR_ACCOUNT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "maxValidityInMinutes": 60 }' \
     -X POST https://api.autoinbox.dev/v1/verifications

Example of a successful response: returns HTTP status 201 (Created)

{
  "isOk": true,
  "result": {
    "verificationId": "1f6g952jxacve9r8sb5gb14ker"
  }
}

You will use the generated verification ID on your webpage to initiate the verification flow with the following JavaScript snippet: 

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

Get verification details

This endpoint allows you to retrieve verification details. Typically, you will call this method only for confirmed verifications after receiving a notification from the frontend flow UI.

Please note that all verifications are automatically deleted after 24 hours.

Required URL parameters

Request example

cURL
curl -H "X-Account-ID: YOUR_ACCOUNT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -X GET https://api.autoinbox.dev/v1/verifications/{id}

Example of a successful response for confirmed verification: returns HTTP status 200 (OK)

{
  "isOk": true,
  "result": {
    "verificationId": "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"
    }
  }
}
DELETE/v1/verifications/{id}

Delete verification

This endpoint allows you to delete generated verifications. Typically, you will call this method after using the `Get verification details` method and receiving the confirmed email.

Since all verifications are automatically deleted after 24 hours, this call is optional.

Required URL parameters

Request example

cURL
curl -H "X-Account-ID: YOUR_ACCOUNT_ID" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -X DELETE https://api.autoinbox.dev/v1/verifications/{id}

Example of a successful response: returns HTTP status 200 (OK)

{
  "isOk": true,
  "result": {}
}