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:

{
    "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_email 400 Bad Request The given email address is invalid
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.