Email address verification and mailing-list cleaning to identify invalid, disposable or high-risk contacts before a send.
openapi: 3.1.2
info:
title: SendPulse Verifier API
version: 1.0.0
description: API for email address verification and mailing list cleaning.
x-ai-description: >
The Verifier API is a critical tool for maintaining high deliverability and
protecting sender reputation. It performs deep validation of email
addresses to identify invalid, disposable, or high-risk contacts before they
are used in campaigns.
license:
name: Apache 2.0
identifier: Apache-2.0
servers:
- url: https://api.sendpulse.com
description: Production server
security:
- apiKey: []
- oauth2: []
tags:
- name: Mailing List Verification
description: Endpoints related to Mailing List Verification.
- name: Single Email Verification
description: Endpoints related to Single Email Verification.
- name: Reports
description: Endpoints related to Reports.
paths:
/verifier-service/send-list-to-verify:
post:
tags:
- Mailing List Verification
summary: Verify mailing list
operationId: verifyMailingList
description: Send a mailing list for verification.
x-ai-role: email_deliverability_expert
x-ai-description: >
Initiates a comprehensive audit of an entire address book. This is a
strategic step taken before launching a campaign to a new or stale list
to prevent hard bounces and protect the sender's domain reputation.
x-ai-reasoning-instructions:
- >-
Ensure that the mailing list has not been used in a campaign yet, as
the system restricts verification of active lists.
- >-
Check if there are any ongoing verifications for the same list ID;
concurrent verifications are prohibited.
- >-
Verify that the account has sufficient verification credits and that
the current plan is active.
- >-
Advise the user that new addresses must be added to the list if they
are re-verifying a previously checked book.
x-ai-responding-instructions:
- Confirm that the verification process has started successfully.
- >-
Instruct the user to use the `getVerificationProgress` method to
monitor the status.
- >-
Remind the user that the list cannot be used for sending until the
verification is complete.
x-ai-suggestions:
- Check progress in 5 minutes.
x-ai-capabilities:
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: integer
description: Mailing list ID to be verified
example: 89165888
responses:
'200':
description: Verification started
content:
application/json:
schema:
$ref: '#/components/schemas/ResultTrue'
'401':
description: Unauthorized
'403':
description: Forbidden
/verifier-service/get-progress:
get:
tags:
- Mailing List Verification
summary: Get mailing list verification progress
operationId: getVerificationProgress
description: Check the progress of an ongoing mailing list verification.
x-ai-role: email_deliverability_expert
x-ai-description: Provides real-time visibility into the batch validation process.
x-ai-reasoning-instructions:
- >-
Use this method to poll for status before attempting to fetch final
results.
- >-
Calculate the percentage of completion from 'total' and 'processed'
fields.
- >-
If 'processed' equals 'total', inform the user that results are now
available.
x-ai-responding-instructions:
- State the current progress (e.g., '80% complete').
- >-
Predict an estimated time remaining if the processing rate is
consistent.
x-ai-suggestions:
- 'id: 89165888'
x-ai-capabilities:
security_info:
data_handling:
- InformationRetrieval
parameters:
- name: id
in: query
required: true
schema:
type: integer
description: Mailing list ID that is being verified
responses:
'200':
description: Verification progress
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
data:
type: object
properties:
total:
type: integer
processed:
type: integer
'401':
description: Unauthorized
'403':
description: Forbidden
/verifier-service/check:
get:
tags:
- Mailing List Verification
summary: Get mailing list verification results
operationId: getVerificationResults
description: Retrieve a list of email addresses with their verification statuses.
x-ai-role: data_analyst
x-ai-description: >
Exports the detailed findings of a list audit. This data allows for
granular segmentation based on address health (Valid, Unconfirmed,
Invalid).
x-ai-reasoning-instructions:
- Must be called after `verifyMailingList` has finished.
- Apply pagination using 'start' and 'count' for large lists.
- >-
Analyze the 'status_text' and 'status' codes to advise on list
hygiene.
x-ai-responding-instructions:
- >-
Summarize the overall health of the list (e.g., 'Green', 'Yellow',
'Red').
- Highlight the number of valid addresses ready for campaigns.
- Advise removing 'Invalid' (status 3) addresses immediately.
x-ai-suggestions:
- 'start: 0'
- 'count: 100'
x-ai-capabilities:
security_info:
data_handling:
- InformationRetrieval
- PIIDisplay
parameters:
- name: id
in: query
required: true
schema:
type: integer
- name: start
in: query
schema:
type: integer
default: 0
- name: count
in: query
schema:
type: integer
default: 10
responses:
'200':
description: Verification results
content:
application/json:
schema:
$ref: '#/components/schemas/MailingListVerificationResult'
'401':
description: Unauthorized
'403':
description: Forbidden
/verifier-service/check-list:
get:
tags:
- Mailing List Verification
summary: Get a list of verified mailing lists
operationId: getVerifiedLists
description: Retrieve a summary of all mailing lists that have been verified.
x-ai-role: data_analyst
x-ai-description: Provides an audit log of all historical list verification activities.
x-ai-reasoning-instructions:
- >-
Use this to identify which lists have been cleaned and which are
pending.
- >-
Monitor 'is_updated' to find lists where new, unverified addresses
were added post-check.
- >-
Check 'is_garbage_in_book' to identify lists with previously known bad
data.
x-ai-responding-instructions:
- >-
Present a table of verified lists with their last check date and
status.
- Flag lists that need re-verification due to new updates.
x-ai-suggestions:
- 'limit: 10'
x-ai-capabilities:
security_info:
data_handling:
- InformationRetrieval
parameters:
- name: start
in: query
schema:
type: integer
default: 0
- name: count
in: query
schema:
type: integer
default: 10
responses:
'200':
description: List of verified mailing lists
content:
application/json:
schema:
type: object
properties:
total:
type: integer
list:
type: array
items:
$ref: '#/components/schemas/VerifiedListSummary'
'401':
description: Unauthorized
'403':
description: Forbidden
/verifier-service/send-single-to-verify:
post:
tags:
- Single Email Verification
summary: Verify a single email address
operationId: verifySingleEmail
description: Send one email address for real-time verification.
x-ai-role: email_deliverability_expert
x-ai-description: >
Enables on-the-fly validation for individual contacts. Ideal for
real-time signup forms or manual entry to ensure only valid data enters
the system.
x-ai-reasoning-instructions:
- Verify email syntax before sending.
- >-
Advise the user that this only initiates the check; results must be
fetched separately.
x-ai-responding-instructions:
- Confirm the verification task is created.
- Suggest fetching the result via `getSingleVerificationResult` next.
x-ai-suggestions:
- 'email: ''test@example.com'''
x-ai-capabilities:
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: Verification started
content:
application/json:
schema:
$ref: '#/components/schemas/ResultTrue'
'401':
description: Unauthorized
'403':
description: Forbidden
/verifier-service/get-single-result:
get:
tags:
- Single Email Verification
summary: Get email address verification results
operationId: getSingleVerificationResult
description: Retrieve the verification result for a single email address.
x-ai-role: email_deliverability_expert
x-ai-description: >-
Provides a detailed breakdown of an individual email's health and
technical validity.
x-ai-reasoning-instructions:
- >-
Check 'disposable' and 'gibberish' flags to detect bot or temporary
accounts.
- >-
Analyze 'webmail' flag to distinguish personal from corporate
addresses.
- >-
If status is not 1 (Valid), advise the user not to send to this
address.
x-ai-responding-instructions:
- Clearly state if the email is 'Valid' or 'Invalid'.
- >-
Highlight specific risks like 'Disposable service detected' if
applicable.
x-ai-suggestions:
- 'email: ''test@example.com'''
x-ai-capabilities:
security_info:
data_handling:
- InformationRetrieval
parameters:
- name: email
in: query
required: true
schema:
type: string
format: email
responses:
'200':
description: Verification results
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
data:
$ref: '#/components/schemas/SingleEmailResult'
'401':
description: Unauthorized
'403':
description: Forbidden
/verifier-service/make-report:
post:
tags:
- Reports
summary: Create a mailing list verification report
operationId: createVerificationReport
description: Generate a downloadable file with verification results.
x-ai-role: data_analyst
x-ai-description: >-
Exports the audit results into a structured file format for offline
analysis or external reporting.
x-ai-reasoning-instructions:
- >-
Select an appropriate format (CSV, XLS, XLSX) based on the user's data
processing needs.
- >-
Filter the statuses (e.g., only 'Invalid') if the user wants to focus
on cleanup.
- Specify the language for headers if necessary.
x-ai-responding-instructions:
- Confirm the report generation has started.
- Instruct the user to use `viewVerificationReport` once ready.
x-ai-suggestions:
- 'format: 4 (XLSX)'
- 'status: [1,2,3]'
x-ai-capabilities:
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: integer
format:
type: integer
description: 2 — csv, 3 — xls, 4 — xlsx; default is 2
enum:
- 2
- 3
- 4
default: 2
status:
type: array
items:
type: integer
description: >-
Statuses to include: 0 — unverified, 1 — valid, 2 —
unconfirmed, 3 — invalid
example:
- 1
- 2
- 3
lang:
type: string
example: en
responses:
'200':
description: Report creation started
content:
application/json:
schema:
$ref: '#/components/schemas/ResultTrue'
'401':
description: Unauthorized
'403':
description: Forbidden
/verifier-service/check-report:
get:
tags:
- Reports
summary: View a mailing list verification report
operationId: viewVerificationReport
description: Get metadata and a sample of the generated report.
x-ai-role: data_analyst
x-ai-description: >-
Provides a preview and verification of the report content before
download.
x-ai-reasoning-instructions:
- Ensure `make-report` was called previously.
- >-
Check the 'status' of the mailing list in the report
(Red/Yellow/Green).
x-ai-responding-instructions:
- Show a summary of the report contents (counts of each status).
- 'Provide the next step: `downloadVerificationReport`.'
x-ai-suggestions:
- 'id: 89165888'
x-ai-capabilities:
security_info:
data_handling:
- InformationRetrieval
parameters:
- name: id
in: query
required: true
schema:
type: integer
- name: format
in: query
schema:
type: integer
default: 2
responses:
'200':
description: Report details
content:
application/json:
schema:
$ref: '#/components/schemas/MailingListVerificationResult'
'401':
description: Unauthorized
'403':
description: Forbidden
/verifier-service/get-report:
get:
tags:
- Reports
summary: Download mailing list verification report
operationId: downloadVerificationReport
description: >-
Download the full report file. Note that the report is deleted from the
server after download.
x-ai-role: data_analyst
x-ai-description: >-
The final retrieval of the cleaning results. This is a one-time download
for security and storage efficiency.
x-ai-reasoning-instructions:
- >-
Warn the user that this is a single-use link; they must save the file
locally.
- Verify the format matches the one used during creation.
x-ai-responding-instructions:
- Provide the binary stream or download link.
- Remind the user that the report is now removed from SendPulse servers.
x-ai-suggestions:
- 'id: 89165888'
x-ai-capabilities:
security_info:
data_handling:
- InformationRetrieval
- DataDestruction
parameters:
- name: id
in: query
required: true
schema:
type: integer
- name: format
in: query
schema:
type: integer
default: 2
responses:
'200':
description: Report file download
content:
application/octet-stream:
schema:
type: string
format: binary
'401':
description: Unauthorized
'403':
description: Forbidden
components:
schemas:
ResultTrue:
type: object
properties:
result:
type: boolean
example: true
MailingListVerificationResult:
type: object
x-ai-description: Detailed breakdown of mailing list health.
properties:
id:
type: integer
address_book_name:
type: string
all_emails_quantity:
type: integer
status:
type: integer
description: 1 - Green, 2 - Yellow, 3 - Red
check_date:
type: string
data:
type: object
properties:
'0':
type: integer
description: Unverified
'1':
type: integer
description: Valid
'2':
type: integer
description: Unconfirmed
'3':
type: integer
description: Invalid
is_updated:
type: integer
status_text:
type: string
email_addresses:
type: array
items:
$ref: '#/components/schemas/EmailAddressVerification'
email_addresses_total:
type: integer
EmailAddressVerification:
type: object
properties:
id:
type: integer
email_address:
type: string
check_date:
type: string
status:
type: integer
status_text:
type: string
VerifiedListSummary:
type: object
properties:
id:
type: integer
address_book_name:
type: string
all_emails_quantity:
type: integer
status:
type: integer
check_date:
type: string
data:
type: object
is_updated:
type: integer
status_text:
type: string
is_garbage_in_book:
type: boolean
SingleEmailResult:
type: object
properties:
email:
type: string
checks:
type: object
properties:
status:
type: integer
valid_format:
type: integer
disposable:
type: integer
webmail:
type: integer
gibberish:
type: integer
status_text:
type: string
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: API Key
description: >
Static API Key authentication. A long-lived token generated manually in
the SendPulse account settings.
x-ai-description: >
Permanent authentication token. Ideal for simple integrations without
token refresh logic.
oauth2:
type: oauth2
description: OAuth 2.0 Client Credentials flow for temporary access tokens.
flows:
clientCredentials:
tokenUrl: https://api.sendpulse.com/oauth/access_token
scopes: {}
x-ai-description: >
Standard OAuth 2.0 flow using Client ID and Client Secret. Provides
temporary tokens (valid for 1 hour) for enhanced security.