Email Validation - IBEx.Fi API Integration Guide

View Flow Diagram

Overview

The Email Validation API uses a generic proxy pattern to route requests to IBEX Safe. The IBEx.Fi API provides a transparent proxy endpoint that forwards requests to the IBEX Safe API, which handles the actual email validation and storage.

The proxy endpoints are:

For email validation, you call:

The Email Validation API allows you to securely validate and store user email addresses in IBEX Safe's GDPR-compliant storage. This process involves two steps:

  1. Request Email Validation : Send a verification code to the user's email address
  2. Confirm Email : Verify the code and optionally store the email in userData
💡 Proxy Pattern :
💡 GDPR Compliance :

1. Request Email Validation

To start the email validation process, send a verification code to the user's email address. This routes through the generic proxy to IBEX Safe's /validateEmail endpoint.

Endpoint : POST /v1.1/ibexsafe/validateEmail (via generic proxy POST /v1.1/ibexsafe/:verb)

Headers :

Request Body :

Request Example :

POST /v1.1/ibexsafe/validateEmail
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "email": "jane.doe@foo.domain",
  "externalUserId": "ext_user_123"
}

Response (200 OK) :

{
  "success": true,
  "message": "Verification code sent to email"
}
💡 Note : The verification code is sent to the provided email address. The code is typically valid for a limited time (e.g., 10-15 minutes). Make sure to prompt the user to check their email and enter the code within the validity period.

2. Confirm Email

After the user receives the verification code, confirm the email by submitting the code. You can optionally store the confirmed email in userData for future use. This routes through the generic proxy to IBEX Safe's /confirmEmail endpoint.

Endpoint : POST /v1.1/ibexsafe/confirmEmail (via generic proxy POST /v1.1/ibexsafe/:verb)

Headers :

Request Body :

Request Example :

POST /v1.1/ibexsafe/confirmEmail
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "email": "jane.doe@foo.domain",
  "code": "123456",
  "externalUserId": "ext_user_123",
  "userDataName": "marketing.email",
  "optinNews": true,
  "optinNotifications": false
}

Response (200 OK) :

{
  "success": true,
  "message": "Email confirmed and stored"
}
💡 Note : If userDataName is provided, the confirmed email is automatically stored in userData under that key. You can retrieve it later using GET /v1.1/ibexsafe/userdata/external/:externalUserId.

3. Retrieve Stored Email

After confirming the email, you can retrieve it from userData using the standard userData retrieval endpoint.

Endpoint : GET /v1.1/ibexsafe/userdata/external/:externalUserId

Request Example :

GET /v1.1/ibexsafe/userdata/external/ext_user_123
Authorization: Bearer <access_token>

Response (200 OK) :

{
  "data": {
    "marketing.email": "jane.doe@foo.domain",
    "optin.newsletter": true,
    "optin.walletAlerts": false
  }
}

Complete Flow Example

Here's a complete example of the email validation flow:

// Step 1: Request email validation
const validateResponse = await fetch('https://api.ibex.fi/v1.1/ibexsafe/validateEmail', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'jane.doe@foo.domain',
    externalUserId: 'ext_user_123'
  })
});

const validateResult = await validateResponse.json();
// { success: true, message: "Verification code sent to email" }

// Step 2: User enters code from email
const code = '123456'; // User input

// Step 3: Confirm email
const confirmResponse = await fetch('https://api.ibex.fi/v1.1/ibexsafe/confirmEmail', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'jane.doe@foo.domain',
    code: code,
    externalUserId: 'ext_user_123',
    userDataName: 'marketing.email',
    optinNews: true,
    optinNotifications: false
  })
});

const confirmResult = await confirmResponse.json();
// { success: true, message: "Email confirmed and stored" }

// Step 4: Retrieve stored email (optional)
const userDataResponse = await fetch('https://api.ibex.fi/v1.1/ibexsafe/userdata/external/ext_user_123', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const userData = await userDataResponse.json();
// { data: { "marketing.email": "jane.doe@foo.domain", "optin.newsletter": true } }

Error Handling

⚠️ Important Points :

Technical Deep Dive - For AI Integration

This section provides detailed technical information for AI systems integrating the IBEX email validation flow, including architecture patterns, data models, and implementation details.

Email Validation - Technical Details

Generic Proxy Pattern

POST /v1.1/ibexsafe/validateEmail

POST /v1.1/ibexsafe/confirmEmail

Data Model

Email Validation Request:

{
  "email": "string (valid email format)",
  "externalUserId": "string (your internal user ID)"
}

Email Confirmation Request:

{
  "email": "string (must match validateEmail email)",
  "code": "string (6-digit verification code)",
  "externalUserId": "string (must match validateEmail externalUserId)",
  "userDataName": "string (optional, default: 'marketing.email')",
  "optinNews": "boolean (optional)",
  "optinNotifications": "boolean (optional)"
}

UserData Storage (after confirmation):

{
  "data": {
    "marketing.email": "jane.doe@foo.domain",
    "optin.newsletter": true,
    "optin.walletAlerts": false
  }
}

Integration Points

UserData Integration:

GDPR Compliance:

Key Implementation Files

Complete Flow - Technical Sequence

  1. Request email validation : POST /v1.1/ibexsafe/validateEmail with email and externalUserId
  2. Authenticate : IBEx.Fi API validates JWT token
  3. Forward to IBEX Safe : IBEx.Fi API forwards request to IBEX Safe email validation service
  4. Validate email format : IBEX Safe validates email format and domain
  5. Generate verification code : IBEX Safe generates secure random code (typically 6 digits)
  6. Send email : IBEX Safe sends verification code to user's email address
  7. Store verification token : IBEX Safe stores verification token with expiration time
  8. Return confirmation : IBEx.Fi API returns success message to client
  9. User enters code : User receives email and enters code in your application
  10. Confirm email : POST /v1.1/ibexsafe/confirmEmail with email, code, and externalUserId
  11. Verify code : IBEX Safe verifies code against stored token and checks expiration
  12. Store email : If userDataName provided, IBEX Safe stores email in userData
  13. Store opt-ins : If opt-in flags provided, IBEX Safe stores preferences in userData
  14. Return confirmation : IBEx.Fi API returns success message to client
  15. Retrieve stored data : Client can retrieve stored email using GET /v1.1/ibexsafe/userdata/external/:externalUserId
← Back to Main Guide