There are two routes for email verification.

the POST /verification/email with can be used to send a verification code by email, and the POST /verification/email/code which can be used to retrieve the verification code for automated testing purposes.

Request an email to be sent

Request format

The https://api.tanker.io/verification/email route handles POST requests with an application/json content type.

The body should be in this form:

{
    "app_id": <app_id>,
    "auth_token": <auth_token>,
    "email_data": {
        "subject": <subject>,
        "html": <html body>,
        "text": <text body>,
        "from_name": <from name>,
        "to_email": <recipient email address>,
        "to_name": <recipient name>
    }
}

Fields description

Field Required Description Value
app_id Required The app ID for which the email verification is sent The app ID string found in your dashboard
auth_token Required The authorization token corresponding to the app The API credentials found in your dashboard
email_data Required Sub-structure containing email configuration
email_data.subject Required Email subject String
email_data.to_email Required Recipient email Valid email address string
email_data.html Optional HTML body for the email Valid HTML string. Must contain the TANKER_VERIFICATION_CODE placeholder
email_data.text Optional Text body for the email String. Must contain the TANKER_VERIFICATION_CODE placeholder
email_data.from_name Optional Display name for email sender String. Defaults to verification@tanker.io
email_data.to_name Optional Display name for email receiver String

Note

At least one of email_data.html and email_data.text must be set.

Response from the HTTP API

The response will contain:

  • A Content-Type of application/json
  • An appropriate 2xx, 4xx, or 5xx HTTP status code
  • A JSON body

If everything went well, the status is 200 and the response is an empty JSON object.

If not, the returned JSON object is in the form:

{
  "error":
  {
    "status": 404,
    "code": "app_not_found",
    "message": "This app does not exist",
  }
}

status is a copy of the HTTP status code, and message usually contains more info about the error.

Here we detail what each code means:

Error code HTTP Status Code Explanation
invalid_body 400 Bad Request The JSON body is incorrect (for instance, both html and text are missing)
invalid_auth_token 401 Unauthorized Wrong authentication token
no_unlock_key 403 Forbidden Email verification is not set up for this user
no_unlock_email 403 Forbidden Email verification is not set up for this user
app_not_found 404 Not Found No app found matching the given ID
max_attempts_reached 429 Too Many Requests Too many recent failed attempts, retry later (15 minutes should suffice)
send_email_error 500 Internal Server Error Something went wrong when trying to send the email
internal_error 500 Internal Server Error Something went wrong on our end, retrying may help

Limits on Tanker verification code queries

A Tanker verification code is valid for 30 minutes. Server-side throttling protects it from brute force attacks.

Retrieve the code for email verification

This API only works if the matching application was created in "test mode" in the Tanker dashboard. Its purpose is to facilitate functional testing of your apps.

Request format

The https://api.tanker.io/verification/email/code route handles POST requests with an application/json content type.

The body should be in this form:

{
  "app_id": <app_id>,
  "auth_token": <auth_token>,
  "email": <email>,
}

Fields description

Field Required Description Value
app_id Required The ID of the test application The app ID string found in your dashboard
auth_token Required The authorization token corresponding to the app The API credentials found in your dashboard
email Required The email of the user Must match the value used to register or verify the user identity

Response from the HTTP API

The response will contain:

  • A Content-Type of application/json
  • An appropriate 2xx, 4xx, or 5xx HTTP status code
  • A JSON body

If everything went well, the status is 200 and the response is a JSON object containing the verification code:

{
  "verification_code": "12345678"
}

If not, the returned JSON object is in the form:

{
  "error":
  {
    "status": 404,
    "code": "app_not_found",
    "message": "This app does not exist",
  }
}

status is a copy of the HTTP status code, and message usually contains more info about the error.

Here we detail what each code means:

Error code HTTP Status Code Explanation
invalid_body 400 Bad Request The JSON body is incorrect (for instance, emailis missing)
invalid_email 400 Bad Request The given email address is invalid
invalid_auth_token 401 Unauthorized Wrong authentication token
app_not_found 404 Not Found No app found matching the given ID
app_is_not_test 403 Forbidden The app was not created in test mode
internal_error 500 Internal Server Error Something went wrong on our end, retrying may help