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 per request with per-email claims. Returns a batch_id for grouping webhook results and for growing the batch across requests.
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.

​
Building a batch across requests

Each batch request carries at most 1,000 emails. To run a larger list as one batch, send the first request as usual, then pass the returned batch_id in each request that follows. Those emails join the same batch, and each response reports the cumulative total_count and the batch’s current status. A batch holds up to 100,000 emails.
A batch accepts new emails for 24 hours after its most recent request. After that window, a request carrying its batch_id returns a 400, as does a batch_id from another project or a request that would take the batch past 100,000 emails. batch_name comes from the first request and is ignored afterwards. Each email has 24 hours to complete from the request that submitted it; any still pending after that come back with error.code: "timed_out".

​
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: 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: Batch submissions are processed at a default throughput of approximately 250 emails per minute per project. A batch of 1,000 emails is fully processed and all of its webhooks delivered within about 4 minutes of submission, and a batch of 100,000 takes roughly 7 hours. 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, and you can submit additional batches without waiting for earlier ones to drain. If your use case requires higher throughput (for example, processing tens of thousands of emails in tight windows), contact us and we can raise your project’s batch processing rate. 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 3 times over approximately 3.5 minutes:
  • 1st retry: 3 seconds after the initial failure
  • 2nd retry: 10 seconds later
  • 3rd retry: 3 minutes later
After the retry window expires, the webhook is marked as failed and no further attempts are made. Webhooks may be delivered more than once, so your endpoint must 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:
You can allowlist this IP if your endpoint is behind a firewall. You should still verify webhook signatures regardless.