Documentation: Retrieving OTP Sent by Mail with HTTP API

This document provides guidance on retrieving a One-Time Password (OTP) sent by email using the OTP Device Sync HTTP API. This approach is especially suited for automated testing scenarios requiring email-based OTPs for 2FA (two-factor authentication) verification.

API Endpoint

Endpoint URL:

GET {API_BASE_URL}/retrieve/email

This endpoint retrieves the OTP sent via email for a specified user and service, authenticated with a registered API key.

Request Parameters

• user: string (required)
  The email address of the user receiving the OTP.
• service: string (required)
  The identifier for the service sending the OTP, typically the email domain or sender name.
• registeredKey: string (required)
  A unique key required to authenticate and authorize the API request.

Example Query:

GET {API_BASE_URL}/retrieve/email?user=user@example.com&service=ServiceName&registeredKey=YOUR_REGISTERED_KEY

Response

The API returns a JSON response containing the OTP and additional email message details.

Success Response:

{
  "code": "123456",  // The OTP code
  "text": "Your OTP code is 123456.",  // The plain text version of the email message
  "html": "<p>Your OTP code is <strong>123456</strong>.</p>"  // The HTML version of the email message
}

Error Response: In case of an error, the API will return a 4xx or 5xx status code along with an error message.

{
  "error": "Invalid registeredKey or missing parameters"
}

Example Usage

The following example demonstrates how to retrieve an email OTP using JavaScript (Node.js) and the Fetch API.

const fetch = require('node-fetch');

const getMailOTP = async (user, service, registeredKey) => {
  const url = new URL(`${process.env.API_BASE_URL}/retrieve/email`);
  url.searchParams.append('user', user);
  url.searchParams.append('service', service);
  url.searchParams.append('registeredKey', registeredKey);

  try {
    const response = await fetch(url);
    if (response.ok) {
      const data = await response.json();
      console.log(`Retrieved Email OTP: ${data.code}`);
      return data;
    } else {
      const errorText = await response.text();
      throw new Error(`Error retrieving Email OTP: ${errorText}`);
    }
  } catch (error) {
    console.error(`Failed to fetch Email OTP: ${error.message}`);
    throw error;
  }
};

// Usage example:
getMailOTP("user@example.com", "ServiceName", "YOUR_REGISTERED_KEY");

Key Points

• Time Sensitivity: Retrieve the OTP promptly, as it may have a limited validity period based on the service settings.
• Authentication: Store registeredKey securely to protect access.
• Error Handling: Ensure appropriate error handling to manage cases where the OTP request fails.

Summary

Using the HTTP API to retrieve email-based OTPs offers a straightforward solution for automating 2FA in testing workflows. The retrieve/email endpoint is designed for quick integration, making it easy to incorporate email-based OTP retrieval in automated end-to-end testing.