SparkPost API (v1)

v1.0 Base URL: https://sp-api.omnivery.net/api/v1

Omnivery API allows you to send messages, retrieve delivery stats, check and configure your sending domains and more in multiple formats. This documentation covers the SparkPost compatible API of Omnivery.

This API follows the SparkPost (v1) API as closely as possible, so existing software or libraries supporting SparkPost (v1) can be used by changing the endpoint and API token, keeping in mind the differences below.

Differences from SparkPost

Make sure your API library reflects these differences.

Endpoints

Domain in the URL. The suppression list, webhook and API key endpoints are scoped to a sending domain, which is passed in the URL: /{domain}/suppression-list, /{domain}/webhooks and /{domain}/api-keys instead of /suppression-list, /webhooks and /api-keys.
Only the endpoints described in this reference are available. Not available: message events, metrics, templates, recipient lists, retrieving transmissions or cancelling a single transmission by id, sub-accounts, and SparkPost-only products (for example IP pools, tracking domains, inbound domains, A/B tests, snippets and Signals).
Recipient validation (GET /recipient-validation/single/{address}) is available with a sending API key only. Its response is the validation result itself, not wrapped in results.
The X-MSYS-SUBACCOUNT header is not supported. To act on a sub-account, use that sub-account's own API key.
A valid API key without the role an endpoint needs (for example a sending key on /account) gets 403 with "message": "Forbidden". An invalid or missing key gets 401.
A few errors from the web framework itself (an unknown URL, a request body that is not valid JSON) are not in the errors format: they return {"message", "title", "status"}.

Transmissions

Primary API keys must set return_path. It selects the sending domain. With a sending API key the key's domain is used.
Tracking options. options.open_tracking and options.click_tracking work as in SparkPost. The top-level open_tracking and click_tracking attributes are also accepted; when both are sent, options wins. If the domain forces its tracking settings, both are ignored.
Response. A successful transmission returns the number of accepted and rejected recipients only. There is no transmission id in results.
These are not supported and are ignored: options.transactional, options.inline_css, options.ip_pool, options.perform_substitutions, options.skip_suppression, content.use_draft_template, recipients[].tags, recipients[].address.header_to and the num_rcpt_errors query parameter.
content.subject is always required, also with content.template_id: an Omnivery template has no subject of its own (SparkPost can take it from the template). The one exception is content.email_rfc822, which carries its own.
Stored recipient lists (recipients.list_id) are not supported; list the recipients in the request.
options.start_time must be less than 72 hours in the future.
Cancelling a scheduled campaign (DELETE /transmissions?campaign_id=) is asynchronous: like SparkPost it answers 204 with an empty body as soon as the request is accepted and does the deletion in the background, whether or not anything was scheduled. A primary API key must also pass domain, and a sending key can only cancel on its own domain. Not supported: the X-MSYS-SUBACCOUNT header, and SparkPost's 429 rate limit (this call is not rate limited). As in SparkPost, each deleted message produces a soft-bounce event (554 5.7.1 [internal] Campaign cancelled), and the sender receives a bounce notification; the recipient is not added to a suppression list.
A rejected recipient (a missing from, an invalid address, a rejection of the content by the mail server) returns HTTP status code 400 with {"errors": [{"message", "code", "description"}]}. A transmission over the size limit returns 413.
options.sandbox: true does not require a sandbox sending domain. The transmission is sent from your own domain in test mode, and our MTA accepts and discards it, so nothing is delivered.
Reserved headers such as From, Sender, To, Bcc and DKIM-Signature cannot be set in content.headers; the transmission is refused with HTTP status code 400. See content.headers for the full list.

Webhooks

Supported events: injection, delivery, bounce, policy_rejection, open, click, spam_complaint, list_unsubscribe and link_unsubscribe. Other SparkPost events (for example delay, out_of_band, initial_open and AMP events) are not available.
Creating a webhook for several events creates one webhook per event, all with the same target.
Basic authentication credentials (auth_credentials) can be set by updating a webhook, not when creating it. OAuth 2.0 is not supported.

This REST API requires all requests to be authenticated using Authentication header with your access token as a value. API tokens can be found in the UI under Credentials menu in API Keys tab (for domain specific/sending tokens) or under API keys menu. For security reasons we strongly suggest using domain specific API keys rather than account API keys whenever possible.

All data to the API endpoint must be posted in JSON format.

Authentication

API Key: API Key in header as Authorization

Enter your credentials below to use the Try it feature:

Authorization API Key

Account Info

GET /account Retrieve Account information ▼

This endpoint is only accessible using a primary API key.

Returns complete information about your account, it's settings and current plan and its usage.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	Authorization header must contain your account's primary API token

Responses

200

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/account' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/account", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/account', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/account');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/account',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

Sending Domains

GET /sending-domains List all Sending Domains ▼

This endpoint is only accessible using a primary API key.

Returns a list of domains under your account in JSON. See examples.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	Authorization header must contain your account's primary API token

Responses

200

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/sending-domains' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/sending-domains", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/sending-domains', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/sending-domains');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/sending-domains',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

POST /sending-domains Create a Sending Domain (auto gen DKIM) ▼

This endpoint is only accessible using a primary API key.

Create a sending domain by providing a sending domain object as the POST request body.

For compatibility reasons the API call will ignore parameters specific to Sparkpost's environment like tracking_domain, dkim, generate_dkim or shared_with_subaccounts.

NOTE: Omnivery takes care of automatic DKIM key rotation using CNAMEs. To facilitate a proper domain setup the response contains an object with all DNS records that need to be set instead of the DKIM object with the selector and public key.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	Authorization header must contain your account's primary API token
`Content-Type`	header	string	Yes	application/json

Request Body application/json

Field	Type	Required	Description
`domain`	string	Yes	The domain or subdomain to create

Responses

200

402

Payment Required

Code Samples

curl -X POST 'https://sp-api.omnivery.net/api/v1/sending-domains' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{"domain": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://sp-api.omnivery.net/api/v1/sending-domains", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/sending-domains', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
  body: JSON.stringify({"domain": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/sending-domains');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"domain": "string"}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.post(
    'https://sp-api.omnivery.net/api/v1/sending-domains',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
    json={"domain": "string"}
)
print(response.json())

GET /sending-domains/{domain} Retrieve a Sending Domain ▼

This endpoint is only accessible using a primary API key.

Retrieve a sending domain by specifying its domain name in the URI path. The response includes details about its DKIM key configuration.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	Authorization header must contain your account's primary API token

Responses

200

Sending domain detail object

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/sending-domains/{domain}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/sending-domains/{domain}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/sending-domains/{domain}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/sending-domains/{domain}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/sending-domains/{domain}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

DELETE /sending-domains/{domain} Delete a Sending Domain ▼

This endpoint is only accessible using a primary API key.

Delete an existing sending domain.

Warning: Before deleting a sending domain please ensure you are no longer using it. After deleting a sending domain, any new transmissions that use it will result in a rejection. This includes any transmissions that are in progress, scheduled for the future, or use a stored template referencing the sending domain.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	Authorization header must contain your account's primary API token
`domain`	path	string	Yes	The domain to be deleted

Responses

204

No Content

404

Not Found

Code Samples

curl -X DELETE 'https://sp-api.omnivery.net/api/v1/sending-domains/{domain}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://sp-api.omnivery.net/api/v1/sending-domains/{domain}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/sending-domains/{domain}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/sending-domains/{domain}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://sp-api.omnivery.net/api/v1/sending-domains/{domain}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

POST /sending-domains/{domain}/verify Verify a Sending Domain ▼

This endpoint is only accessible using a primary API key.

Verifies all the domain settings required for use of the domain for sending and receiving messages.

Request will perform a complete validation check of all required DNS records. All options available in the original Sparkpost API are ignored, eg. (dkim_verify, cname_verify, spf_verify, etc.)

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	Authorization header must contain your account's primary API token
`domain`	path	string	Yes	Domain name to verify

Responses

200

Code Samples

curl -X POST 'https://sp-api.omnivery.net/api/v1/sending-domains/{domain}/verify' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://sp-api.omnivery.net/api/v1/sending-domains/{domain}/verify", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/sending-domains/{domain}/verify', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/sending-domains/{domain}/verify');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.post(
    'https://sp-api.omnivery.net/api/v1/sending-domains/{domain}/verify',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

Transmissions

POST /transmissions Create a Transmission (inline text/html and recipients) ▼

This endpoint is only accessible using both sending and primary API keys. If primary API key is used the return_path attribute is required to identify the domain to be used.

You can create a transmission using SparkPost API in a number of ways.

Using Inline Email Part Content

Create a transmission using inline email part content.

Using Inline RFC822 Content (MIME)

Create a transmission using inline RFC822 content. Content headers are not generated for transmissions providing RFC822 content. They are expected to be provided as headers contained in the RFC822 content.

Using a Stored Template

Create a transmission using a stored template by specifying the template_id in the content attribute.

Tracking

Set options.open_tracking and options.click_tracking (true or false) to override the domain's tracking settings for this transmission. The top-level open_tracking and click_tracking attributes are also accepted; options wins when both are sent. If the domain forces its tracking settings, both are ignored.

Response

A successful transmission returns results with total_accepted_recipients and total_rejected_recipients. Unlike SparkPost, results does not contain a transmission id. If some recipients were rejected, the reasons are listed in errors.

Scheduled delivery

Set options.start_time to hold the transmission and deliver it at that time. The format is YYYY-MM-DDTHH:MM:SS+-HH:MM (or Z for UTC), e.g. 2018-09-11T08:00:00-04:00. The value now sends immediately.

The time must be less than 72 hours in the future. A later time is rejected with HTTP status code 422 (error code 1300) and nothing is sent.

A time that is now or already past sends the transmission immediately.

A value in any other format is rejected with HTTP status code 422 (error code 1300).

options.start_time takes precedence over an X-OV-Deliver-By header in content.headers. The header is how delivery is scheduled over SMTP.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	Authorization header must contain your domain's sending API token or your account's primary API token
`Content-Type`	header	string	Yes	application/json

Request Body application/json

Field Type Required Description

campaign_id

string

Campaign ID of your choice to help you identify campaigns. This could be helpful in the future when identifying messages of a larger send.

click_tracking

boolean

Enable or disable click tracking for this transmission, overriding the domain setting. Omnivery extension: the same as options.click_tracking, which wins when both are sent.

content

object

Yes

Content object carries the information about the sender (from), message subject as well as message body. The message body can be supplied in multiple formats or retrieved from a template.

metadata

object

Metadata are global metadata applied to all recipients of this transmission. Metadata supplied in the recipient's object will override the transmission metadata

open_tracking

boolean

Enable or disable open tracking for this transmission, overriding the domain setting. Omnivery extension: the same as options.open_tracking, which wins when both are sent.

options

object

Message level settings to override the domain level settings

recipients

array

Yes

Recipients object contains not only recipient's address but can also include variables to be passed to template.

Field	Type	Required	Description
`address`	object	Yes	Address information for a recipient
`callback_url`	string	No	Custom webhook endpoint URL - overrides webhooks set at the domain level.
`metadata`	object	No	Key/value pairs associated with a recipient. Metadata is available during events through the Webhooks and is provided to the template engine. A maximum of 1000 bytes of merged metadata (transmission level + recipient level) is available with recipient metadata taking precedence over transmission metadata when there are conflicts.
`substitution_data`	object	No	Key/value pairs associated with a recipient that are provided to the template engine. Recipient substitution data takes precedence over transmission substitution data. Unlike metadata, substitution data is not included in Webhook events. The maximum length is 100KB per recipient.
`tags`	array	No	Array of text labels associated with a recipient. Tags are available in Webhook events. Maximum number of tags - 10 per recipient, 100 system wide. Any tags over the limits are ignored.

return_path

string

Return path allows you to select your sending domain in case you are using a primary API token and in that case it is a required parameter. When using sending API token the return_path attribute has no use

substitution_data

object

Substitution data are global data substituted for all recipients of this transmission. Substitution data supplied in the recipient's object will override the transmission substitution data

Responses

200

Transmission accepted. results holds the recipient counts only; there is no transmission id. errors is present only when some recipients were rejected.

422

Unprocessable Entity

Code Samples

curl -X POST 'https://sp-api.omnivery.net/api/v1/transmissions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{"campaign_id": "string", "click_tracking": false, "content": {}, "metadata": {}, "open_tracking": false, "options": {}, "recipients": [], "return_path": "string", "substitution_data": {}}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://sp-api.omnivery.net/api/v1/transmissions", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/transmissions', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
  body: JSON.stringify({"campaign_id": "string", "click_tracking": false, "content": {}, "metadata": {}, "open_tracking": false, "options": {}, "recipients": [], "return_path": "string", "substitution_data": {}})
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/transmissions');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"campaign_id": "string", "click_tracking": false, "content": {}, "metadata": {}, "open_tracking": false, "options": {}, "recipients": [], "return_path": "string", "substitution_data": {}}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.post(
    'https://sp-api.omnivery.net/api/v1/transmissions',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
    json={"campaign_id": "string", "click_tracking": false, "content": {}, "metadata": {}, "open_tracking": false, "options": {}, "recipients": [], "return_path": "string", "substitution_data": {}}
)
print(response.json())

DELETE /transmissions Delete a Scheduled Campaign ▼

This endpoint is accessible using both sending and primary API keys. A primary API key must pass domain to identify the sending domain; a sending key always acts on its own domain.

Cancel the scheduled transmissions of a campaign: the transmissions sent with options.start_time in the future and this campaign_id.

As in SparkPost, the cancellation is asynchronous: the call returns 204 immediately and the deletion happens in the background. A 204 means the request was accepted and queued, not that any transmission was found. Transmissions whose delivery has already started are not affected. Only transmissions sent from the domain, by your account, with exactly this campaign_id are removed.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	Authorization header must contain your domain's sending API token or your account's primary API token
`campaign_id`	query	string	Yes	The `campaign_id` the transmissions were sent with. At most 64 characters, no control characters.
`domain`	query	string	No	Sending domain. Required with a primary API key.

Responses

204

The cancellation was accepted and queued. Empty body, as in SparkPost.

401

Invalid or missing API key, or a sending key used with another domain

404

The domain is not one of your sending domains

422

campaign_id is missing, longer than 64 characters or contains control characters, or a primary key did not pass domain

503

The cancellation could not be queued; nothing was cancelled and the request can be retried

Code Samples

curl -X DELETE 'https://sp-api.omnivery.net/api/v1/transmissions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://sp-api.omnivery.net/api/v1/transmissions", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/transmissions', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/transmissions');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://sp-api.omnivery.net/api/v1/transmissions',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

Webhooks

GET /{domain}/webhooks List Webhooks ▼

This endpoint is only accessible using a primary API key.

List the webhooks configured for the given sending domain.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes
`Accept`	header	string	Yes
`domain`	path	string	Yes	The sending domain the webhooks belong to.

Responses

200

404

Not Found

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/{domain}/webhooks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/{domain}/webhooks", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/webhooks', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/webhooks');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/{domain}/webhooks',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

POST /{domain}/webhooks Create Webhooks ▼

This endpoint is only accessible using a primary API key.

Create one or more webhooks for the given sending domain. A separate webhook is created for each event supplied in events, all pointing at the same target URL.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Content-Type`	header	string	No
`Accept`	header	string	Yes
`Authorization`	header	string	Yes
`domain`	path	string	Yes	The sending domain the webhooks will be created for.

Request Body application/json

Field	Type	Required	Description
`events`	array	Yes	Sparkpost event names to subscribe to. A separate webhook is created per event.
`target`	string	Yes	The endpoint URL events will be delivered to.

Responses

200

400

Bad Request

Code Samples

curl -X POST 'https://sp-api.omnivery.net/api/v1/{domain}/webhooks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{"events": [], "target": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://sp-api.omnivery.net/api/v1/{domain}/webhooks", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/webhooks', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
  body: JSON.stringify({"events": [], "target": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/webhooks');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"events": [], "target": "string"}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.post(
    'https://sp-api.omnivery.net/api/v1/{domain}/webhooks',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
    json={"events": [], "target": "string"}
)
print(response.json())

domain path *

Content-Type header

Accept header *

Authorization header *

Request Body application/json

Response

GET /{domain}/webhooks/{id} Retrieve a Webhook ▼

This endpoint is only accessible using a primary API key.

Retrieve a single webhook belonging to the given sending domain.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes
`Accept`	header	string	Yes
`domain`	path	string	Yes	The sending domain the webhook belongs to.
`id`	path	integer	Yes	The webhook identifier.

Responses

200

404

Not Found

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

PUT /{domain}/webhooks/{id} Update a Webhook ▼

This endpoint is only accessible using a primary API key.

Update a webhook belonging to the given sending domain. Changing which events a webhook fires on is not supported in place - delete and recreate the webhook instead.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Content-Type`	header	string	No
`Accept`	header	string	Yes
`Authorization`	header	string	Yes
`domain`	path	string	Yes	The sending domain the webhook belongs to.
`id`	path	integer	Yes	The webhook identifier.

Request Body application/json

Field Type Required Description

active

boolean

Enable or disable the webhook.

auth_credentials

object

Basic-auth credentials to call the target with.

Field	Type	Required	Description
`password`	string	No
`username`	string	No

events

array

Must match the webhook's existing event; changing events in place is not supported.

name

string

New human-readable name.

target

string

New endpoint URL.

Responses

200

400

Bad Request

404

Not Found

Code Samples

curl -X PUT 'https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{"active": false, "auth_credentials": {"password": "string", "username": "string"}, "events": [], "name": "string", "target": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("PUT", "https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}', {
  method: 'PUT',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
  body: JSON.stringify({"active": false, "auth_credentials": {"password": "string", "username": "string"}, "events": [], "name": "string", "target": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"active": false, "auth_credentials": {"password": "string", "username": "string"}, "events": [], "name": "string", "target": "string"}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.put(
    'https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
    json={"active": false, "auth_credentials": {"password": "string", "username": "string"}, "events": [], "name": "string", "target": "string"}
)
print(response.json())

domain path *

id path *

Content-Type header

Accept header *

Authorization header *

Request Body application/json

Response

DELETE /{domain}/webhooks/{id} Delete a Webhook ▼

This endpoint is only accessible using a primary API key.

Delete a webhook belonging to the given sending domain. Returns 204 No Content on success.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes
`domain`	path	string	Yes	The sending domain the webhook belongs to.
`id`	path	integer	Yes	The webhook identifier.

Responses

204

No Content

404

Not Found

Code Samples

curl -X DELETE 'https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

POST /{domain}/webhooks/{id}/validate Validate a Webhook ▼

This endpoint is only accessible using a primary API key.

Validate a webhook by sending a test message to its target URL. An optional message payload may be supplied; otherwise a sample event is generated.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Content-Type`	header	string	No
`Accept`	header	string	Yes
`Authorization`	header	string	Yes
`domain`	path	string	Yes	The sending domain the webhook belongs to.
`id`	path	integer	Yes	The webhook identifier.

Request Body application/json

Field	Type	Required	Description
`message`	object	No	Optional payload to send. If omitted, a sample event is generated.

Responses

200

404

Not Found

Code Samples

curl -X POST 'https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}/validate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{"message": {}}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}/validate", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}/validate', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
  body: JSON.stringify({"message": {}})
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}/validate');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"message": {}}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.post(
    'https://sp-api.omnivery.net/api/v1/{domain}/webhooks/{id}/validate',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
    json={"message": {}}
)
print(response.json())

domain path *

id path *

Content-Type header

Accept header *

Authorization header *

Request Body application/json

Response

API Keys

GET /{domain}/api-keys List API Keys ▼

This endpoint is only accessible using a primary API key.

List the API keys (credentials) belonging to the given sending domain. The full key secret is never returned by this endpoint - it is only shown once, at creation time.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes
`Accept`	header	string	Yes
`domain`	path	string	Yes	The sending domain the API keys belong to.

Responses

200

403

Forbidden - the API key does not have the role this endpoint requires

404

Not Found

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/{domain}/api-keys' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/{domain}/api-keys", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/api-keys', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/api-keys');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/{domain}/api-keys',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

POST /{domain}/api-keys Create an API Key ▼

This endpoint is only accessible using a primary API key.

Create a new API key (credential) scoped to the given sending domain. The response returns the full api_key secret once - store it securely, it cannot be retrieved again.

The grants and valid_ips fields are accepted for wire compatibility with Sparkpost but are not enforced; keys created here are always domain-scoped sending keys.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Content-Type`	header	string	No
`Accept`	header	string	Yes
`Authorization`	header	string	Yes
`domain`	path	string	Yes	The sending domain the new API key will be scoped to.

Request Body application/json

Field	Type	Required	Description
`grants`	array	No	Requested grants. Accepted for Sparkpost compatibility but not enforced.
`label`	string	No	Human-readable label for the key (stored as the credential note).
`valid_ips`	array	No	Requested IP allow-list. Accepted for Sparkpost compatibility but not enforced.

Responses

200

403

Forbidden - the API key does not have the role this endpoint requires

404

Not Found

Code Samples

curl -X POST 'https://sp-api.omnivery.net/api/v1/{domain}/api-keys' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{"grants": [], "label": "string", "valid_ips": []}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://sp-api.omnivery.net/api/v1/{domain}/api-keys", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/api-keys', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
  body: JSON.stringify({"grants": [], "label": "string", "valid_ips": []})
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/api-keys');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"grants": [], "label": "string", "valid_ips": []}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.post(
    'https://sp-api.omnivery.net/api/v1/{domain}/api-keys',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
    json={"grants": [], "label": "string", "valid_ips": []}
)
print(response.json())

domain path *

Content-Type header

Accept header *

Authorization header *

Request Body application/json

Response

GET /{domain}/api-keys/{id} Retrieve an API Key ▼

This endpoint is only accessible using a primary API key.

Retrieve a single API key (credential) belonging to the given sending domain. The key secret is not returned.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes
`Accept`	header	string	Yes
`domain`	path	string	Yes	The sending domain the API key belongs to.
`id`	path	integer	Yes	The API key identifier.

Responses

200

404

Not Found

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

DELETE /{domain}/api-keys/{id} Delete an API Key ▼

This endpoint is only accessible using a primary API key.

Delete an API key (credential) belonging to the given sending domain. Returns 204 No Content on success.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as a result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes
`domain`	path	string	Yes	The sending domain the API key belongs to.
`id`	path	integer	Yes	The API key identifier.

Responses

204

No Content

404

Not Found

Code Samples

curl -X DELETE 'https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://sp-api.omnivery.net/api/v1/{domain}/api-keys/{id}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

Recipient Validation

GET /recipient-validation/single/{address} Email Address Validation ▼

Runs a given address through a series of checks that catch many common problems, including syntax issues and non-existent mailboxes.

To perform email validation your sending domain must have email validation enabled and you must use your sending domain's API credentials not the account level credentials.

The request is a GET, as in SparkPost. Differences: the result is returned directly and not wrapped in results, and an account (primary) API key gets 403.

Responses

200

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/recipient-validation/single/{address}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/recipient-validation/single/{address}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/recipient-validation/single/{address}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/recipient-validation/single/{address}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/recipient-validation/single/{address}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

Suppression List

GET /{domain}/suppression-list Search for List Entries ▼

This endpoint is only accessible using a primary API key.

Perform a filtered search for entries in your domain-specific exclusion list.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes
`Accept`	header	string	Yes
`domain`	path	string	Yes
`from`	query	string	No	Filter results by date starting from
`to`	query	string	No	Filter results by date ending at
`per_page`	query	number	No	Output record limit
`page`	query	number	No	Result page
`sources`	query	string	No	Sources (one of `Spam Complaint`, `List Unsubscribe`, `Bounce Rule`, `Unsubscribe Link`, `Manually Added`, `Compliance`)

Responses

200

400

Bad Request

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/{domain}/suppression-list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/{domain}/suppression-list", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/suppression-list', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/suppression-list');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/{domain}/suppression-list',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

domain path *

from query

to query

per_page query

page query

sources query

Authorization header *

Accept header *

Response

PUT /{domain}/suppression-list Insert or Update List Entries ▼

This endpoint is only accessible using a primary API key.

Bulk insert entries to the domain-specific exclusion list by providing a JSON object, with a "recipients" key containing an array of recipients to insert or update, as the PUT request body. Maximum size of the JSON object is 10mb. At a minimum, each recipient must have a valid "email" address in recipient field. The optional "description" key can be used to include an explanation of what type of message should be suppressed.

If the type field is used with value transactional the record will be added to the "block" suppressions, otherwise the "unsubscribe" suppression will be used.

If an email address is duplicated in a single request, only the first instance will be processed.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required
`Content-Type`	header	string	No
`Accept`	header	string	Yes
`Authorization`	header	string	Yes
`domain`	path	string	Yes

Request Body application/json

Field Type Required Description

recipients array Yes

Field	Type	Required
`description`	string	Yes
`recipient`	string	Yes
`type`	string	No

Responses

200

Code Samples

curl -X PUT 'https://sp-api.omnivery.net/api/v1/{domain}/suppression-list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{"recipients": []}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("PUT", "https://sp-api.omnivery.net/api/v1/{domain}/suppression-list", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/suppression-list', {
  method: 'PUT',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
  body: JSON.stringify({"recipients": []})
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/suppression-list');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"recipients": []}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.put(
    'https://sp-api.omnivery.net/api/v1/{domain}/suppression-list',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
    json={"recipients": []}
)
print(response.json())

domain path *

Content-Type header

Accept header *

Authorization header *

Request Body application/json

Response

GET /{domain}/suppression-list/{recipient} Retrieve a Recipient Suppression Status ▼

This endpoint is only accessible using a primary API key.

Retrieve the suppression status for a specific recipient by specifying the recipient’s email address in the URI path.

If the recipient is not in the domain-specific exclusion list, an HTTP status of 404 is returned. If the recipient is in the list, an HTTP status of 200 is returned with the full suppression status in the response body.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required
`Authorization`	header	string	Yes
`Accept`	header	string	Yes
`domain`	path	string	Yes
`recipient`	path	string	Yes

Responses

200

Code Samples

curl -X GET 'https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

DELETE /{domain}/suppression-list/{recipient} Delete a List Entry ▼

This endpoint is only accessible using a primary API key.

Delete a recipient from the list by specifying the recipient's email address in the URI path.

If the recipient is not in the domain-specific exclusion list, an HTTP status of 404 is returned. If the recipient is in the list, an HTTP status of 204 is returned indicating a successful deletion.

Due to differences in architecture this endpoint requires the domain to be passed in the URL and as result its URL is not identical to that used by Sparkpost. Make sure your API library reflects this change.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes
`Accept`	header	string	Yes
`domain`	path	string	Yes
`recipient`	path	string	Yes
`recipient`	query	string	No	Recipient email address

Request Body application/json

Responses

204

No Content

404

Not Found

Code Samples

curl -X DELETE 'https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}", nil)
    req.Header.Set("Authorization", "YOUR_API_KEY")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
});
const data = await response.json();

<?php
$ch = curl_init('https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: YOUR_API_KEY']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://sp-api.omnivery.net/api/v1/{domain}/suppression-list/{recipient}',
    headers={'Content-Type': 'application/json', 'Authorization': 'YOUR_API_KEY'},
)
print(response.json())

domain path *

recipient path *

recipient query

Authorization header *

Accept header *

Request Body application/json