Customer Emails

Configure the IMAP mailbox the platform polls for withdrawal PIN emails, then verify, enable, or disable that poller.

The platform reads withdrawal PINs straight from a customer's mailbox. Point it at an IMAP inbox here, verify the connection, and toggle polling on or off. Every response masks the IMAP password—you set it, but you never read it back.

Authentication: every endpoint on this page uses a Bearer token in the Authorization header.

Authorization: Bearer YOUR_SESSION_TOKEN

Each customer has exactly one poller. The IMAP email/user is derived server-side from the customer's owner credential—any email you send is ignored. Every poller path is singular /email/poller; enable and disable add the {{pollerID}} segment.

Create Email Poller

POSThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/email/poller

Configure the IMAP mailbox to poll for PIN emails. The poller is created enabled. The mailbox address isn't taken from the body—it's derived from the customer's owner credential—so you only supply connection details.

Request Body

Field	Type	Required	Description
imap	object	Yes	IMAP connection settings (see below).
description	string	No	Free-text label for the mailbox (max 255).

`imap` object

Field	Type	Required	Description
host	string	Yes	IMAP server host. Must be a valid hostname or IP.
port	number	Yes	IMAP server port (1-65535).
tls	boolean	No	Use TLS/SSL (default: true).
password	string	Yes	IMAP password (use an app-specific password for Gmail).

{
  "imap": {
    "host": "imap.gmail.com",
    "port": 993,
    "tls": true,
    "password": "your-app-password"
  },
  "description": "Main trading account"
}

Success Response (201 Created):

{
  "success": true,
  "data": {
    "customer_id": "sovbs-6f5d8756-e0ae-401f-9f3f-4d220a1dcbab",
    "email": "[email protected]",
    "imap": {
      "host": "imap.gmail.com",
      "port": 993,
      "tls": true,
      "user": "[email protected]",
      "password": "***masked***"
    },
    "description": "Main trading account",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
    "imap": {
      "host": "imap.gmail.com",
      "port": 993,
      "tls": true,
      "password": "your-app-password"
    },
    "description": "Main trading account"
  }'

Errors: 401 invalid token · 404 customer or owner email not found · 409 poller already exists for this customer · 422 validation failed · 500 server error.

Get Email Poller

GEThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/email/poller

Retrieve the customer's poller configuration and its poll statistics. The IMAP password is always masked.

GET https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller

Success Response (200 OK):

{
  "success": true,
  "data": {
    "customer_id": "sovbs-6f5d8756-e0ae-401f-9f3f-4d220a1dcbab",
    "email": "[email protected]",
    "imap": {
      "host": "imap.gmail.com",
      "port": 993,
      "tls": true,
      "user": "[email protected]",
      "password": "***masked***"
    },
    "description": "Main trading account",
    "last_polled_at": "2026-01-15T10:29:00.000Z",
    "last_successful_poll_at": "2026-01-15T10:29:00.000Z",
    "last_error_at": null,
    "last_error": null,
    "total_emails_processed": 42,
    "total_pins_extracted": 41,
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:29:00.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer or poller not found · 500 server error.

Update Email Poller

PUThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/email/poller

Update the poller. Send only the fields you want to change. Returns the full updated configuration with the password masked.

Request Body

All fields are optional. Include only the fields you want to change.

Field	Type	Required	Description
imap	object	No	IMAP connection settings. Same shape as Create.
enabled	boolean	No	Enable or disable polling.
description	string	No	Free-text label for the mailbox (max 255).

{
  "description": "Updated trading mailbox",
  "imap": {
    "host": "imap.gmail.com",
    "port": 993,
    "tls": true,
    "password": "new-app-password"
  }
}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "customer_id": "sovbs-6f5d8756-e0ae-401f-9f3f-4d220a1dcbab",
    "email": "[email protected]",
    "imap": {
      "host": "imap.gmail.com",
      "port": 993,
      "tls": true,
      "user": "[email protected]",
      "password": "***masked***"
    },
    "description": "Updated trading mailbox",
    "last_polled_at": "2026-01-15T10:29:00.000Z",
    "last_successful_poll_at": "2026-01-15T10:29:00.000Z",
    "last_error_at": null,
    "last_error": null,
    "total_emails_processed": 42,
    "total_pins_extracted": 41,
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T12:00:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X PUT "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
    "description": "Updated trading mailbox",
    "imap": {
      "host": "imap.gmail.com",
      "port": 993,
      "tls": true,
      "password": "new-app-password"
    }
  }'

Errors: 401 invalid token · 404 customer or poller not found · 422 validation failed · 500 server error.

Delete Email Poller

DELETEhttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/email/poller

Remove the customer's poller. Polling stops and the configuration is erased.

DELETE https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller

Success Response (204 No Content) — empty body, no JSON.

curl -X DELETE "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer or poller not found · 500 server error.

Verify Email Connection

POSThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/email/poller/verify

Test the stored IMAP credentials by opening a live connection to the mailbox. A successful login returns 200; a failed or timed-out connection returns 401 with the failure reason.

POST https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller/verify

No request body.

Success Response (200 OK):

{
  "success": true,
  "data": {
    "success": true,
    "message": "Connection successful"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller/verify" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token, or IMAP connection failed (bad credentials, timeout) · 404 customer or poller not found · 500 server error.

Enable Email Poller

POSThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/email/poller/:poller_id/enable

Turn polling on for a specific poller and start the background worker.

POST https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller/{{pollerID}}/enable

No request body.

Success Response (200 OK):

{
  "success": true,
  "data": {
    "message": "Email poller enabled"
  },
  "meta": {
    "timestamp": "2026-01-15T12:00:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller/{{pollerID}}/enable" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer or poller not found · 500 server error.

Disable Email Poller

POSThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/email/poller/:poller_id/disable

Turn polling off for a specific poller and stop the background worker. The configuration is kept—re-enable it any time.

POST https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller/{{pollerID}}/disable

No request body.

Success Response (200 OK):

{
  "success": true,
  "data": {
    "message": "Email poller disabled"
  },
  "meta": {
    "timestamp": "2026-01-15T12:05:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/email/poller/{{pollerID}}/disable" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer or poller not found · 500 server error.

Customer Emails

On this page