Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • A Verisoul API key (available from the Dashboard)

​
Step 1: Configure Your Webhook Endpoint (Optional)

Webhook configuration is optional. All email intelligence results are available in the Dashboard regardless of whether a webhook is configured. Set up a webhook only if you need results delivered to your own endpoint in real time.
To configure a webhook, go to Settings > Webhooks in the Dashboard and add a new endpoint. Select the Email Intel Completed event type, enter your target URL, and click Create. Your webhook endpoint must:
  • Accept POST requests with JSON payloads
  • Respond with a 2xx HTTP status code on success
  • Be idempotent (Verisoul may retry delivery)
  • Verify webhook signatures for security (see Step 3)
Once configured, Verisoul will automatically deliver results to this endpoint when email analysis completes.

​
Step 2: Submit Emails

Submit emails to the POST /email endpoint. You can submit a single email or a batch of emails.

Submit Email

Submit a single email with optional identity claims. Returns a request_id for webhook correlation.

Submit Email Batch

Submit up to 1,000 emails with per-email claims. Returns a batch_id for grouping webhook results.
The API responds immediately with a request_id (single) or batch_id (batch), plus a webhook_configured boolean indicating whether a webhook subscription is active for your project. This confirms the email has been accepted for processing — it does not contain the analysis results.

​
Step 3: Receive and Verify Webhook Results

Once analysis completes, Verisoul delivers a webhook to your configured endpoint with the event type email.intelligence.completed.

​
Webhook Signature Verification

All webhook requests include an x-signature header containing an HMAC-SHA256 signature over the timestamp, selected headers, and the raw request body. See the Webhook Signature Verification guide for the full algorithm, code examples in Node.js, Python, Go, and C#, and troubleshooting tips.
Always verify the signature before processing the payload. Use the raw request body (not a parsed/re-serialized version) and enforce a timestamp tolerance of ±5 minutes.

​
Processing the Payload

  1. Verify the webhook signature
  2. Check the status field — either success or error
  3. On success, use data.result.decision and data.result.risk_score for your business logic
  4. On error, inspect the error object for details
See the Webhook Payload Reference for the full payload structure and field definitions.

​
Latency and Delivery Guarantees

The time between submitting an email and receiving the webhook depends on whether Verisoul has previously analyzed the email or its domain. Single email requests:
ScenarioTypical latency
Invalid or previously analyzed emailUnder 1 second
New email on a known domainApproximately 5 seconds
New domain never seen before30–60 seconds (one-time domain analysis)
Verisoul guarantees that the webhook for a single email request will be delivered within 60 seconds of submission. If analysis has not completed by then, a webhook is sent with status: "error" and error.code: "timed_out" so your system is never left waiting. Batch requests: For batch submissions (up to 1,000 emails), Verisoul guarantees that all webhooks in the batch will be delivered within 5 minutes of submission. Each email in the batch triggers its own webhook as soon as its analysis completes — you do not need to wait for the entire batch to finish before receiving results. Batch emails are processed at a lower priority than single email requests, so real-time single-email submissions are never delayed by batch processing.

​
FAQ

If your endpoint does not return a 2xx response, Verisoul retries delivery:
  • Up to 5 fast retries with increasing delays
  • Up to 5 slow retries approximately once per hour
Total retry window is approximately 5 hours. Webhooks may be delivered more than once, so your endpoint should be idempotent.
Calls to /email count toward your API key’s rate limit. If you need a higher limit, contact Verisoul.
All Verisoul webhooks are sent from:
34.71.198.163
You can allowlist this IP if your endpoint is behind a firewall. You should still verify webhook signatures regardless.