README

MailOdds provides email validation services to help maintain clean email lists and improve deliverability. The API performs multiple validation checks including format verification, domain validation, MX record checking, and disposable email detection.

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys can be created in the MailOdds dashboard.

Rate Limits

Rate limits vary by plan:

Free: 10 requests/minute
Starter: 60 requests/minute
Pro: 300 requests/minute
Business: 1000 requests/minute
Enterprise: Custom limits

Response Format

All responses include:

schema_version: API schema version (currently "1.0")
request_id: Unique request identifier for debugging

Error responses include:

error: Machine-readable error code
message: Human-readable error description

Webhooks

MailOdds can send webhook notifications for job completion and email delivery events. Configure webhooks in the dashboard or per-job via the webhook_url field.

Event Types

Event	Description
`job.completed`	Validation job finished processing
`job.failed`	Validation job failed
`message.queued`	Email queued for delivery
`message.delivered`	Email delivered to recipient
`message.bounced`	Email bounced
`message.deferred`	Email delivery deferred
`message.failed`	Email delivery failed
`message.opened`	Recipient opened the email
`message.clicked`	Recipient clicked a link

Payload Format

{
  \"event\": \"job.completed\",
  \"job\": { ... },
  \"timestamp\": \"2026-01-15T10:30:00Z\"
}

Webhook Signing

If a webhook secret is configured, each request includes an X-MailOdds-Signature header containing an HMAC-SHA256 hex digest of the request body.

Verification pseudocode:

expected = HMAC-SHA256(webhook_secret, request_body)
valid = constant_time_compare(request.headers[\"X-MailOdds-Signature\"], hex(expected))

The payload is serialized with compact JSON (no extra whitespace, sorted keys) before signing.

Headers

All webhook requests include:

Content-Type: application/json
User-Agent: MailOdds-Webhook/1.0
X-MailOdds-Event: {event_type}
X-Request-Id: {uuid}
X-MailOdds-Signature: {hmac} (when secret is configured)

Retry Policy

Failed deliveries (non-2xx response or timeout) are retried up to 3 times with exponential backoff (10s, 60s, 300s).

For more information, please visit https://mailodds.com/contact.

Installation & Usage

Requirements

PHP 8.1 and later.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"
    }
  ],
  "require": {
    "GIT_USER_ID/GIT_REPO_ID": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure Bearer authorization: BearerAuth
$config = MailOdds\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new MailOdds\Api\BulkValidationApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$job_id = 'job_id_example'; // string

try {
    $result = $apiInstance->cancelJob($job_id);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling BulkValidationApi->cancelJob: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://api.mailodds.com/v1

Class	Method	HTTP request	Description
BulkValidationApi	cancelJob	POST /v1/jobs/{job_id}/cancel	Cancel a job
BulkValidationApi	createJob	POST /v1/jobs	Create bulk validation job (JSON)
BulkValidationApi	createJobFromS3	POST /v1/jobs/upload/s3	Create job from S3 upload
BulkValidationApi	createJobUpload	POST /v1/jobs/upload	Create bulk validation job (file upload)
BulkValidationApi	deleteJob	DELETE /v1/jobs/{job_id}	Delete a job
BulkValidationApi	getJob	GET /v1/jobs/{job_id}	Get job status
BulkValidationApi	getJobResults	GET /v1/jobs/{job_id}/results	Get job results
BulkValidationApi	getPresignedUpload	POST /v1/jobs/upload/presigned	Get S3 presigned upload URL
BulkValidationApi	listJobs	GET /v1/jobs	List validation jobs
EmailSendingApi	deliverBatch	POST /v1/deliver/batch	Send to multiple recipients (max 100)
EmailSendingApi	deliverEmail	POST /v1/deliver	Send a single email
EmailValidationApi	validateBatch	POST /v1/validate/batch	Validate multiple emails (sync)
EmailValidationApi	validateEmail	POST /v1/validate	Validate single email
SendingDomainsApi	createSendingDomain	POST /v1/sending-domains	Add a sending domain
SendingDomainsApi	deleteSendingDomain	DELETE /v1/sending-domains/{domain_id}	Delete a sending domain
SendingDomainsApi	getSendingDomain	GET /v1/sending-domains/{domain_id}	Get a sending domain
SendingDomainsApi	getSendingDomainIdentityScore	GET /v1/sending-domains/{domain_id}/identity-score	Get domain identity score
SendingDomainsApi	getSendingStats	GET /v1/sending-stats	Get sending statistics
SendingDomainsApi	listSendingDomains	GET /v1/sending-domains	List sending domains
SendingDomainsApi	verifySendingDomain	POST /v1/sending-domains/{domain_id}/verify	Verify domain DNS records
SubscriberListsApi	confirmSubscription	GET /v1/confirm/{token}	Confirm subscription
SubscriberListsApi	createList	POST /v1/lists	Create a subscriber list
SubscriberListsApi	deleteList	DELETE /v1/lists/{list_id}	Delete a subscriber list
SubscriberListsApi	getList	GET /v1/lists/{list_id}	Get a subscriber list
SubscriberListsApi	getLists	GET /v1/lists	List subscriber lists
SubscriberListsApi	getSubscribers	GET /v1/lists/{list_id}/subscribers	List subscribers
SubscriberListsApi	subscribe	POST /v1/subscribe/{list_id}	Subscribe to a list
SubscriberListsApi	unsubscribeSubscriber	DELETE /v1/lists/{list_id}/subscribers/{subscriber_id}	Unsubscribe a subscriber
SuppressionListsApi	addSuppression	POST /v1/suppression	Add suppression entries
SuppressionListsApi	checkSuppression	POST /v1/suppression/check	Check suppression status
SuppressionListsApi	getSuppressionAuditLog	GET /v1/suppression/audit	Get suppression audit log
SuppressionListsApi	getSuppressionStats	GET /v1/suppression/stats	Get suppression statistics
SuppressionListsApi	listSuppression	GET /v1/suppression	List suppression entries
SuppressionListsApi	removeSuppression	DELETE /v1/suppression	Remove suppression entries
SystemApi	getTelemetrySummary	GET /v1/telemetry/summary	Get validation telemetry
SystemApi	healthCheck	GET /health	Health check
ValidationPoliciesApi	addPolicyRule	POST /v1/policies/{policy_id}/rules	Add rule to policy
ValidationPoliciesApi	createPolicy	POST /v1/policies	Create policy
ValidationPoliciesApi	createPolicyFromPreset	POST /v1/policies/from-preset	Create policy from preset
ValidationPoliciesApi	deletePolicy	DELETE /v1/policies/{policy_id}	Delete policy
ValidationPoliciesApi	deletePolicyRule	DELETE /v1/policies/{policy_id}/rules/{rule_id}	Delete rule
ValidationPoliciesApi	getPolicy	GET /v1/policies/{policy_id}	Get policy
ValidationPoliciesApi	getPolicyPresets	GET /v1/policies/presets	Get policy presets
ValidationPoliciesApi	listPolicies	GET /v1/policies	List policies
ValidationPoliciesApi	testPolicy	POST /v1/policies/test	Test policy evaluation
ValidationPoliciesApi	updatePolicy	PUT /v1/policies/{policy_id}	Update policy

Models

Authorization

Authentication schemes defined for the API:

BearerAuth

Type: Bearer authentication

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

support@mailodds.com

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

API version: 1.0.0
- Generator version: 7.19.0
Build package: org.openapitools.codegen.languages.PhpClientCodegen

mailodds / mailodds-php

Maintainers

Package info

Statistics

Security