Mailgun API (v3)

v3.0 Base URL: https://mg-api.omnivery.net/v3

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 Mailgun v3 compatible API of Omnivery.

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

Differences from Mailgun

Endpoints

Only the endpoints described in this reference are available. Besides v3, these are the v4 domain endpoints (/v4/domains: list, create, get and verify, identical to their v3 counterparts) and GET /v5/accounts/http_signing_key. Mailgun's other v1, v4 and v5 endpoints (for example /v4/address/validate or PUT /v4/domains/{domain}) are not available.
Not available: events and logs, analytics/metrics, tags, templates, routes, mailing lists, IPs and IP pools, sub-accounts, stored messages, suppression CSV import, and clearing all allowlist entries at once (clearing all bounces, complaints or unsubscribes is available).
Email validation is available as GET /address/private/validate only, with a sending API key of a domain that has validation enabled.
Omnivery-only endpoints: PATCH /domains/{domain}/disable and GET /domains/{domain}/webhooks/{webhookname}/sample.

API keys

Sending (domain) API keys can send messages, validate and parse addresses, and read their own domain (GET /domains, GET /domains/{domain}, GET /domains/{domain}/connection and the same on /v4). Every other endpoint requires the primary (account) API key.
X-Mailgun-On-Behalf-Of is not supported. To act on a sub-account, use that sub-account's own API key.

Sending

subject is always required, also with template: an Omnivery template has no subject of its own, so the request must supply it (Mailgun can take the subject from the template).
template refers to a template stored in Omnivery. t:variables is supported; t:version and t:text are not.
These options are not supported and are ignored: o:sending-ip, o:sending-ip-pool, o:deliverytime-optimize-period, o:time-zone-localize, o:deliver-within, o:archive-to, o:secondary-dkim, o:suppress-headers, and the htmlonly value of o:tracking / o:tracking-clicks.
o:deliverytime must be less than 72 hours in the future.
DELETE /{domain}/envelopes is asynchronous: it answers 200 {"message": "done"} once the deletion is queued, and answers 503 if it cannot be queued. Each deleted message produces a soft-bounce event (554 5.7.1 [internal] Campaign cancelled) and a bounce notification to the sender, and the recipient is not added to a suppression list (Mailgun documents neither). Mailgun's storage host requirement does not apply. The optional tag parameter is an Omnivery extension (Mailgun deletes all scheduled mail of the domain); characters other than letters, digits, - and _ are ignored in it, and o:tag on send follows the same rule (a tag with none left, or over 128 characters, is refused with 400).
Reserved headers such as From, Sender, To, Bcc and DKIM-Signature cannot be set with h: parameters; the request is refused with HTTP status code 400. See h:X-My-Header under Send message for the full list.
messages.mime takes the o:, h: and v: parameters of /messages, template with t:variables, and recipient-variables; t:version and t:text are not supported on it, and the cc, bcc, reply_to and subject parameters do not apply (they come from the MIME message itself).
The id in the send response lists one message ID per recipient, separated by commas.
The maximum message size, including attachments, is 10 MB unless a different limit is set for your domain.
A message that is refused for its content (a missing or duplicated from, to or subject, a disallowed attachment, or a rejection by the mail server such as an unaligned Reply-To) returns HTTP status code 400 with {"message": "..."}. A message over the size limit returns 413.

Domains, credentials and webhooks

Domain objects contain Omnivery's domain fields. Mailgun-only fields such as spam_action, web_prefix or smtp_login are not returned.
GET /domains/{domain}/connection returns fixed settings (require_tls and skip_verification are always false) and the settings cannot be changed: Omnivery has no per-domain TLS policy.
GET /v5/accounts/http_signing_key returns the account's webhook signing key (primary API key only); regenerating it through the API is not available.
Supported webhook names: clicked, complained, delivered, opened, permanent_fail, temporary_fail and unsubscribed. accepted is not supported.
An SMTP credential login must be a full email address, and a password is required: at least 8 characters, using at least 3 character types.

This REST API requires all requests to be authenticated using Basic authenticaiton with username api and your access token as a password. 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 form-data format.

Available endpoints

Global (automatic geo-selection): https://mg-api.omnivery.net/v3
Europe: https://eu.mg-api.omnivery.net/v3
US: https://us.mg-api.omnivery.net/v3

The v4 domain endpoints and the v5 signing key are served by the same hosts, with /v4 or /v5 in place of /v3 (for example https://mg-api.omnivery.net/v4/domains).

Unlike Mailgun, Omnivery doesn't require you to have different credentials for different geographic zones. The endpoint is only used for selecting the server closest to you or to minimize transfers between zones. The actual data will be always stored in location according to the zone set for each respective domain used. You can use the same credentials for all the zones.

Authentication

basic: HTTP basic

Enter your credentials below to use the Try it feature:

API Key (HTTP Basic password)

Messages

DELETE /{domain}/envelopes Delete scheduled and undelivered mail ▼

Deletes all scheduled and undelivered mail of the domain (mail scheduled with o:deliverytime that has not been delivered yet).

The deletion is queued and carried out in the background: a request answered with 200 has queued the removal. Mail that is already being delivered cannot be recalled.

Omnivery extension: the optional tag parameter limits the deletion to scheduled mail that was sent with that o:tag. Without it, all scheduled and undelivered mail of the domain is deleted, as on Mailgun.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name
`tag`	query	string	No	Only delete scheduled mail sent with this `o:tag` (Omnivery extension). Characters other than letters, digits, `-` and `_` are ignored, as in the tag stamped on the message, and what is left must be 1 to 128 characters, otherwise `400`. Every tag `o:tag` accepts can be cancelled by the same value.

Responses

200

{
  "message": "done"
}

400

Invalid tag

{
  "message": "tag must be a single value of 1 to 128 letters, digits, - or _ (other characters are ignored)"
}

401

Unauthorized

{
  "message": "Unauthorized"
}

404

Domain not found, or not in your account

{
  "message": "Domain not found"
}

503

The deletion could not be queued, try again

{
  "message": "Unable to queue the deletion, please try again"
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/{domain}/envelopes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/{domain}/envelopes", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/envelopes', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/envelopes');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/{domain}/envelopes',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

POST /{domain}/messages Send message ▼

Sends a message from a domain specified in the URL by assembling it from the components. Note that you can specify most parameters multiple times, HTTP supports this out of the box. This makes sense for parameters like cc, to or attachment.

Parameter	Description
from	Email address for `From` header. Example: `"Sender Name" johndoe@sender.com`
to	Email address of the recipient(s). Example: `"John Doe" johndoe@example.com`. You can use commas to separate multiple recipients.
reply_to	Email addres for `Reply-To` header. Example: `"John Doe" johndoe@example.com`. You can use commas to separate multiple recipients.
cc	Same as `To` but for `Cc`
bcc	Same as `To` but for `Bcc`
subject	Message subject. Required, also when `template` is used (see Differences from Mailgun).
text	Body of the message. (text version)
html	Body of the message. (HTML version)
attachment	File attachment. You can post multiple `attachment` values. Important: You must use `multipart/form-data` encoding when sending attachments.
inline	Attachment with `inline` disposition. Can be used to send inline images (see example). You can post multiple `inline` values.
o:tag	Tag string.
o:testmode	Enables sending in test mode. Pass `yes` if needed.
o:tracking	Toggles tracking on a per-message basis. Pass `yes` or `no`.
o:tracking-opens	Toggles open tracking on a per-message basis. Pass `yes` or `no`.
o:tracking-clicks	Toggles click tracking on a per-message basis. Pass `yes` or `no`.
o:deliverytime	Schedule the message for later delivery. RFC 2822 date, e.g. `Fri, 14 Oct 2011 23:10:10 -0000`. Must be less than 72 hours in the future. See Scheduled delivery below.
h:X-My-Header	`h:` prefix followed by an arbitrary value allows to append a custom MIME header to the message (`X-My-Header` in this case). For example, `h:Reply-To` to specify Reply-To address. These headers are reserved and refused with HTTP status code 400: `From`, `Sender`, `Return-Path`, `To`, `Bcc`, `DKIM-Signature`, `DomainKey-Signature`, `ARC-*`, `Authentication-Results`, `Received`, `Content-Type`, `Content-Transfer-Encoding`, `MIME-Version`, `X-OV-Ident`, `X-OV-Submission` and `X-OV-APIFormat`. Use the `from`, `to` and `bcc` parameters instead.
v:my-var	`v:` prefix followed by an arbitrary name allows to attach a custom JSON data to the message.
template	Filename of the template to use
t:variables	Template variables as a JSON string. These variables will be passed to the template for processing.
substitutions	JSON string with substitions. The JSON key will be replaced with the matching value.
callback_url	Webhook URL to post delivery/bounce/etc information to

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to be used for sending the message. Domain must be verified and active.

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`amp-html`	string	No	AMP part of the message
`callback_url`	string	No	Webhook URL to post delivery/bounce/etc information to
`from`	string	Yes	Email address for `From` header
`h:X-testid`	integer	No	h: prefix followed by an arbitrary value allows to append a custom MIME header to the message (X-My-testid in this case). For example, h:Reply-To to specify Reply-To address. These headers are reserved and refused with HTTP status code 400: From, Sender, Return-Path, To, Bcc, DKIM-Signature, DomainKey-Signature, ARC-*, Authentication-Results, Received, Content-Type, Content-Transfer-Encoding, MIME-Version, X-OV-Ident, X-OV-Submission and X-OV-APIFormat.
`html`	string	No	Body of the message. (html version)
`o:deliverytime`	string	No	Desired delivery time as an RFC 2822 date. Must be less than 72 hours in the future; a time that is now or already past sends the message immediately.
`o:tag`	string	No	Tag string for message tagging. Repeat the parameter multiple times to add multiple tags. On Omnivery, characters other than letters, digits, `-` and `_` are ignored, and what is left must be 1 to 128 characters, otherwise `400` (such a message could not be cancelled by its tag).
`reply_to`	string	No	Email addres for `Reply-To` header
`subject`	string	Yes	Message subject
`substitutions`	string	No	JSON string with substitions. The JSON key will be replaced with the matching value.
`t:variables`	string	No	Template variables as a JSON string. These variables will be passed to the template for processing.
`template`	string	No	Filename of the template to use
`text`	string	No	Body of the message. (text version)
`to`	string	Yes	Email address of the recipient(s). Example: `"Bob bob@host.com"`. You can use commas to separate multiple recipients or repeat the to parameter multiple times.

Responses

200

{
  "id": "\u003cd5b0c0d0-7d27-11ec-8cdc-d7e317832025@test.omnivery.net\u003e",
  "message": "Queued. Thank you."
}

400

Bad Request

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/{domain}/messages' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"amp-html": "string", "callback_url": "string", "from": "string", "h:X-testid": 0, "html": "string", "o:deliverytime": "string", "o:tag": "string", "reply_to": "string", "subject": "string", "substitutions": "string", "t:variables": "string", "template": "string", "text": "string", "to": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/{domain}/messages", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/messages', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"amp-html": "string", "callback_url": "string", "from": "string", "h:X-testid": 0, "html": "string", "o:deliverytime": "string", "o:tag": "string", "reply_to": "string", "subject": "string", "substitutions": "string", "t:variables": "string", "template": "string", "text": "string", "to": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/messages');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"amp-html": "string", "callback_url": "string", "from": "string", "h:X-testid": 0, "html": "string", "o:deliverytime": "string", "o:tag": "string", "reply_to": "string", "subject": "string", "substitutions": "string", "t:variables": "string", "template": "string", "text": "string", "to": "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://mg-api.omnivery.net/v3/{domain}/messages',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"amp-html": "string", "callback_url": "string", "from": "string", "h:X-testid": 0, "html": "string", "o:deliverytime": "string", "o:tag": "string", "reply_to": "string", "subject": "string", "substitutions": "string", "t:variables": "string", "template": "string", "text": "string", "to": "string"}
)
print(response.json())

POST /{domain}/messages.mime Send message with MIME ▼

Send a message supplied in MIME format. You will need to build the MIME string yourself. As MIME is not a simple encoding, you should use a MIME library for your programming language.

Parameter	Description
domain	Domain to be used for sending the message. Domain must be verified and active. This parameter is part of the URL
to	Email address of the recipient(s). Example: `"Bob "`. You can use commas to separate multiple recipients.
message	MIME string of the message. Send it as a file part (`multipart/form-data`) or as a plain form field.
o:tag	Tag string. Repeat the parameter to add several tags.
o:testmode	Enables sending in test mode. Pass `yes` if needed.
o:tracking	Toggles tracking on a per-message basis. Pass `yes` or `no`.
o:tracking-opens	Toggles open tracking on a per-message basis. Pass `yes` or `no`.
o:tracking-clicks	Toggles click tracking on a per-message basis. Pass `yes` or `no`.
o:deliverytime	Schedule the message for later delivery. RFC 2822 date, e.g. `Fri, 14 Oct 2011 23:10:10 -0000`. Must be less than 72 hours in the future. See Scheduled delivery below.
h:X-My-Header	`h:` prefix followed by an arbitrary value adds a custom MIME header to the message (`X-My-Header` in this case); a header of the same name in the MIME message is replaced. The reserved headers listed under Send message are refused with HTTP status code 400.
v:my-var	`v:` prefix followed by an arbitrary name allows to attach a custom JSON data to the message.
template	Filename of the template to use. The template is applied by the mail server and replaces the body of the MIME message.
t:variables	Template variables as a JSON string. These variables will be passed to the template for processing.
recipient-variables	A JSON object keyed by recipient address, e.g. `{"bob@example.com": {"id": 1}}`. The message is sent once per address in `to`, each with only its own entry, which is passed to the mail server as the recipient's variables. An address without an entry is sent without variables. The `To` header of the MIME message is kept as written.
callback_url	Webhook URL to post delivery/bounce/etc information to

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to be used for sending the message. Domain must be verified and active.

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`callback_url`	string	No	Webhook URL to post delivery/bounce/etc information to
`h:X-testid`	integer	No	h: prefix followed by an arbitrary value adds a custom MIME header to the message (X-testid in this case); a header of the same name in the MIME message is replaced. Reserved headers are refused with HTTP status code 400.
`message`	string	Yes	MIME encoded message content. This must be a valid MIME encoded message including headers and all body parts.
`o:deliverytime`	string	No	Desired delivery time as an RFC 2822 date. Must be less than 72 hours in the future; a time that is now or already past sends the message immediately.
`o:tag`	string	No	Tag string for message tagging. Repeat the parameter multiple times to add multiple tags. On Omnivery, characters other than letters, digits, `-` and `_` are ignored, and what is left must be 1 to 128 characters, otherwise `400` (such a message could not be cancelled by its tag).
`recipient-variables`	string	No	A JSON object keyed by recipient address. The message is sent once per address in `to`, each with only its own entry as the recipient's variables; an address without an entry gets none.
`t:variables`	string	No	Template variables as a JSON string. These variables will be passed to the template for processing.
`template`	string	No	Filename of the template to use. The mail server applies it and replaces the body of the MIME message.
`to`	string	Yes	List of recipients separated by comma. Don't forget to list all of your To, Cc and Bcc addresses here.

Responses

200

{
  "id": "\u003cd5b0c0d0-7d27-11ec-8cdc-d7e317832025@test.omnivery.net\u003e",
  "message": "Queued. Thank you."
}

400

Bad Request

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/{domain}/messages.mime' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"callback_url": "string", "h:X-testid": 0, "message": "string", "o:deliverytime": "string", "o:tag": "string", "recipient-variables": "string", "t:variables": "string", "template": "string", "to": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/{domain}/messages.mime", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/messages.mime', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"callback_url": "string", "h:X-testid": 0, "message": "string", "o:deliverytime": "string", "o:tag": "string", "recipient-variables": "string", "t:variables": "string", "template": "string", "to": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/messages.mime');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"callback_url": "string", "h:X-testid": 0, "message": "string", "o:deliverytime": "string", "o:tag": "string", "recipient-variables": "string", "t:variables": "string", "template": "string", "to": "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://mg-api.omnivery.net/v3/{domain}/messages.mime',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"callback_url": "string", "h:X-testid": 0, "message": "string", "o:deliverytime": "string", "o:tag": "string", "recipient-variables": "string", "t:variables": "string", "template": "string", "to": "string"}
)
print(response.json())

Domains

GET /domains Get domains ▼

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

Parameter	Description
limit	Maximum number of records to return. (100 by default)
skip	Number of records to skip. (0 by default)
state	Filter domains by state: `pending`, `unverified`, `active`, `rejected` or `disabled` optional. Any other value returns 400.

The list contains information about each domain available using your current credentials. If you are using account level API key the list will contain all domains in the account. For domain level API key only the domain the key is associated with will be returned. Only domains with active state can be used for sending and receiving.

Parameters

Name	In	Type	Required	Description
`limit`	query	string	No	Maximum number of records to return. (100 by default)
`skip`	query	string	No	Number of records to skip. (0 by default)
`state`	query	string	No	Filter domains by state

Responses

200

{
  "items": [
    {
      "created_at": "Mon, 05 Apr 2021 14:40:50 GMT",
      "force_dkim_authority": false,
      "name": "example.com",
      "state": "rejected",
      "wildcard": true
    },
    {
      "created_at": "Mon, 05 Apr 2021 14:40:50 GMT",
      "force_dkim_authority": false,
      "name": "samplemail.info",
      "state": "active",
      "wildcard": false
    },
    {
      "created_at": "Mon, 05 Apr 2021 14:40:51 GMT",
      "force_dkim_authority": false,
      "name": "simplesender.org",
      "state": "unverified",
      "wildcard": false
    },
    {
      "created_at": "Mon, 05 Apr 2021 14:40:51 GMT",
      "force_dkim_authority": false,
      "name": "waittosend.com",
      "state": "pending",
      "wildcard": false
    }
  ],
  "total_count": 4
}

400

Bad Request

{
  "message": "Invalid domain state \"bogus\" requested"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/domains' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/domains", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/domains',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

POST /domains Create new domain ▼

Add new domain to send and receive messages.

Parameter	Description
name	Name of the domain (ex. domain.com)
smtp_password	Password for SMTP authentication
wildcard	true or false Determines whether the domain will accept email for sub-domains. The default is false.

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`name`	string	Yes	Name of the domain (ex. domain.com)
`smtp_password`	string	No
`wildcard`	boolean	No

Responses

200

{
  "domain": {
    "created_at": "Mon, 24 Jan 2022 15:29:04 GMT",
    "force_dkim_authority": false,
    "name": "lori.net",
    "state": "pending",
    "updated_at": "Mon, 24 Jan 2022 15:29:04 GMT",
    "wildcard": false
  },
  "receiving_dns_records": [
    {
      "name": "lori.net",
      "priority": 10,
      "record_type": "MX",
      "valid": false,
      "value": "mx.omnivery.net"
    }
  ],
  "sending_dns_records": [
    {
      "name": "lori.net",
      "record_type": "TXT",
      "valid": false,
      "value": "v=spf1 include:omnivery.net ~all"
    },
    {
      "name": "k1-10533._domainkey.lori.net",
      "record_type": "CNAME",
      "state": "unverified",
      "valid": false,
      "value": "k1-10533.dkim.omnivery.net"
    },
    {
      "name": "k2-10533._domainkey.lori.net",
      "record_type": "CNAME",
      "state": "unverified",
      "valid": false,
      "value": "k2-10533.dkim.omnivery.net"
    }
  ]
}

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/domains' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"name": "string", "smtp_password": "string", "wildcard": false}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/domains", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"name": "string", "smtp_password": "string", "wildcard": false})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name": "string", "smtp_password": "string", "wildcard": false}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.post(
    'https://mg-api.omnivery.net/v3/domains',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"name": "string", "smtp_password": "string", "wildcard": false}
)
print(response.json())

GET /domains/{domain} Get single domain ▼

Returns a single domain, including DNS records.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name to retrieve details for

Responses

200

{
  "domain": {
    "created_at": "Wed, 09 Jun 2021 14:09:07 GMT",
    "force_dkim_authority": false,
    "name": "sample.omnivery.net",
    "state": "active",
    "updated_at": "Fri, 21 Jan 2022 12:32:13 GMT",
    "wildcard": false
  },
  "receiving_dns_records": [
    {
      "name": "sample.omnivery.net",
      "priority": 10,
      "record_type": "MX",
      "valid": true,
      "value": "mx.omnivery.dev"
    }
  ],
  "sending_dns_records": [
    {
      "name": "sample.omnivery.net",
      "record_type": "TXT",
      "valid": true,
      "value": "v=spf1 include:omnivery.net ~all"
    },
    {
      "name": "k1-10502._domainkey.sample.omnivery.net",
      "record_type": "CNAME",
      "state": "active",
      "valid": true,
      "value": "k1-10502.dkim.omnivery.dev"
    },
    {
      "name": "k2-10502._domainkey.sample.omnivery.net",
      "record_type": "CNAME",
      "state": "inactive",
      "valid": true,
      "value": "k2-10502.dkim.omnivery.dev"
    }
  ]
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/domains/{domain}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/domains/{domain}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/domains/{domain}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

DELETE /domains/{domain} Delete domain ▼

Deletes a domain from your account

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name to delete

Responses

200

{
  "message": "Domain has been deleted"
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/domains/{domain}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/domains/{domain}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/domains/{domain}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /domains/{domain}/connection Get domain connection settings ▼

Returns the SMTP connection settings of a domain, as {"connection": {"require_tls": false, "skip_verification": false}}.

Differences from Mailgun: Omnivery has no per-domain TLS policy, so the answer is always false for both settings; they cannot be changed (PUT is not available). The endpoint exists so that libraries which read the settings (for example getConnection in mailgun.js) keep working. A sending API key can read its own domain only.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name

Responses

200

{
  "connection": {
    "require_tls": false,
    "skip_verification": false
  }
}

401

Unauthorized

{
  "message": "Unauthorized"
}

404

Domain not found, or not in your account

{
  "message": "Domain not found"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/domains/{domain}/connection' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/domains/{domain}/connection", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/connection', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/connection');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/domains/{domain}/connection',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /domains/{domain}/credentials Get SMTP credentials for a domain ▼

Returns a list of SMTP credentials for the defined domain.

Parameter	Description
limit	Maximum number of records to return. (100 by default)
skip	Number of records to skip. (0 by default)

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to list credentials for
`limit`	query	integer	No	Maximum number of records to return. (100 by default)
`skip`	query	integer	No	Number of records to skip; 0 by default.

Responses

200

{
  "items": [
    {
      "created_at": "Thu, 10 Jun 2021 12:54:42 GMT",
      "login": "karlee25@example.net",
      "mailbox": "karlee25@example.net",
      "note": "Distributed attitude-oriented frame"
    }
  ],
  "total_count": 1
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/domains/{domain}/credentials' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/domains/{domain}/credentials", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/credentials', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/credentials');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/domains/{domain}/credentials',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

POST /domains/{domain}/credentials Create new SMTP credentials ▼

Creates a new set of SMTP credentials for the defined domain.

Parameter	Description
login	The user name, for example `bob.bar`
password	A password for the SMTP credentials. (Length Min 5, Max 32)

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to add credentials to

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`login`	string	Yes	The user name, for example bob.bar
`password`	string	Yes	A password for the SMTP credentials. (Length Min 5, Max 32)

Responses

200

{
  "created_at": "2022-01-24 16:42:05",
  "message": "Created 1 credentials pair",
  "note": null,
  "updated_at": "2022-01-24 16:42:05",
  "username": "emilia_jacobi@hotmail.com"
}

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/domains/{domain}/credentials' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"login": "string", "password": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/domains/{domain}/credentials", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/credentials', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"login": "string", "password": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/credentials');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"login": "string", "password": "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://mg-api.omnivery.net/v3/domains/{domain}/credentials',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"login": "string", "password": "string"}
)
print(response.json())

PUT /domains/{domain}/credentials/{login} Update SMTP credentials ▼

Updates the specified SMTP credentials. Currently only the password can be changed.

Parameter	Description
password	A password for the SMTP credentials. (Length Min 5, Max 32)

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to update SMTP credentials
`login`	path	string	Yes	SMTP username to update

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`password`	string	Yes	A password for the SMTP credentials. (Length Min 5, Max 32)

Responses

200

{
  "message": "Credentials updated"
}

Code Samples

curl -X PUT 'https://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"password": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("PUT", "https://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}', {
  method: 'PUT',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"password": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"password": "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://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"password": "string"}
)
print(response.json())

DELETE /domains/{domain}/credentials/{login} Delete SMTP credentials ▼

Deletes the defined SMTP credentials.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to delete SMTP credentials from
`login`	path	string	Yes	SMTP username to delete

Responses

200

{
  "message": "Credentials (1) deleted"
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/domains/{domain}/credentials/{login}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

PATCH /domains/{domain}/disable Disable domain ▼

This endpoint serves as a domain kill-switch and is only available for use using primary API token.

Domains disabled using this endpoint can only be reactivated from the UI.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name

Responses

200

{
  "domain": {
    "created_at": "Wed, 09 Jun 2021 14:09:07 GMT",
    "force_dkim_authority": false,
    "name": "sample.omnivery.net",
    "state": "disabled",
    "updated_at": "Fri, 21 Jan 2022 12:32:13 GMT",
    "wildcard": false
  },
  "receiving_dns_records": [
    {
      "name": "sample.omnivery.net",
      "priority": 10,
      "record_type": "MX",
      "valid": true,
      "value": "mx.omnivery.dev"
    }
  ],
  "sending_dns_records": [
    {
      "name": "sample.omnivery.net",
      "record_type": "TXT",
      "valid": true,
      "value": "v=spf1 include:omnivery.net ~all"
    },
    {
      "name": "k1-10502._domainkey.sample.omnivery.net",
      "record_type": "CNAME",
      "state": "active",
      "valid": true,
      "value": "k1-10502.dkim.omnivery.dev"
    },
    {
      "name": "k2-10502._domainkey.sample.omnivery.net",
      "record_type": "CNAME",
      "state": "inactive",
      "valid": true,
      "value": "k2-10502.dkim.omnivery.dev"
    }
  ]
}

Code Samples

curl -X PATCH 'https://mg-api.omnivery.net/v3/domains/{domain}/disable' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("PATCH", "https://mg-api.omnivery.net/v3/domains/{domain}/disable", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/disable', {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/disable');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.patch(
    'https://mg-api.omnivery.net/v3/domains/{domain}/disable',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /domains/{domain}/tracking Get domain tracking settings ▼

Returns tracking settings for a domain.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to retrieve tracking settings for

Responses

200

{
  "tracking": {
    "click": {
      "active": false
    },
    "open": {
      "active": false
    },
    "unsubscribe": {
      "active": false
    }
  }
}

404

Not Found

{
  "message": "Domain not found"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/domains/{domain}/tracking' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/domains/{domain}/tracking", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/tracking', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/tracking');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/domains/{domain}/tracking',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

PUT /domains/{domain}/verify Verify domain ▼

Verifies and returns a single domain, including credentials and DNS records. If the domain is successfully verified you will be able to use the domain to send messages.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name to verify

Responses

200

{
  "domain": {
    "created_at": "Wed, 09 Jun 2021 14:09:07 GMT",
    "force_dkim_authority": false,
    "name": "sample.omnivery.net",
    "state": "active",
    "updated_at": "Fri, 21 Jan 2022 12:32:13 GMT",
    "wildcard": false
  },
  "receiving_dns_records": [
    {
      "name": "sample.omnivery.net",
      "priority": 10,
      "record_type": "MX",
      "valid": true,
      "value": "mx.omnivery.dev"
    }
  ],
  "sending_dns_records": [
    {
      "name": "sample.omnivery.net",
      "record_type": "TXT",
      "valid": true,
      "value": "v=spf1 include:omnivery.net ~all"
    },
    {
      "name": "k1-10502._domainkey.sample.omnivery.net",
      "record_type": "CNAME",
      "state": "active",
      "valid": true,
      "value": "k1-10502.dkim.omnivery.dev"
    },
    {
      "name": "k2-10502._domainkey.sample.omnivery.net",
      "record_type": "CNAME",
      "state": "inactive",
      "valid": true,
      "value": "k2-10502.dkim.omnivery.dev"
    }
  ]
}

Code Samples

curl -X PUT 'https://mg-api.omnivery.net/v3/domains/{domain}/verify' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("PUT", "https://mg-api.omnivery.net/v3/domains/{domain}/verify", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/verify', {
  method: 'PUT',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/verify');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.put(
    'https://mg-api.omnivery.net/v3/domains/{domain}/verify',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /v4/domains Get domains (v4) ▼

Mailgun's /v4 domain list. It is the same endpoint as GET /v3/domains, with the same parameters and the same response: the account (primary) API key lists the account's domains, a sending API key lists its own domain only. Base URL: https://mg-api.omnivery.net/v4.

Differences from Mailgun: the v4-only parameters authority, search, sort and include_subaccounts are ignored; a sub-account's domains are never listed (use the sub-account's own API key). The domain objects are the same as on v3 (see Differences from Mailgun).

Parameters

Name	In	Type	Required	Description
`limit`	query	string	No	Maximum number of records to return. (100 by default)
`skip`	query	string	No	Number of records to skip. (0 by default)
`state`	query	string	No	Filter domains by state: `pending`, `unverified`, `active`, `rejected` or `disabled`. Any other value returns 400.

Responses

200

{
  "items": [
    {
      "created_at": "Mon, 05 Apr 2021 14:40:50 GMT",
      "name": "samplemail.info",
      "state": "active",
      "wildcard": false
    }
  ],
  "total_count": 1
}

400

Bad Request

{
  "message": "Invalid domain state \"bogus\" requested"
}

401

Unauthorized

{
  "message": "Unauthorized"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/v4/domains' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/v4/domains", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/v4/domains', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/v4/domains');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/v4/domains',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

POST /v4/domains Create new domain (v4) ▼

Mailgun's /v4 domain creation. It is the same endpoint as POST /v3/domains: same parameters and response. Account (primary) API key only.

Differences from Mailgun: only name, smtp_password and wildcard are used; the v4-only parameters (web_scheme, web_prefix, dkim_key_size, ips, pool_id, force_dkim_authority, spam_action, ...) are ignored.

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`name`	string	Yes	Name of the domain (ex. domain.com)
`smtp_password`	string	No
`wildcard`	boolean	No

Responses

200

401

Unauthorized

{
  "message": "Unauthorized"
}

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/v4/domains' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"name": "string", "smtp_password": "string", "wildcard": false}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/v4/domains", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/v4/domains', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"name": "string", "smtp_password": "string", "wildcard": false})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/v4/domains');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"name": "string", "smtp_password": "string", "wildcard": false}');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.post(
    'https://mg-api.omnivery.net/v3/v4/domains',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"name": "string", "smtp_password": "string", "wildcard": false}
)
print(response.json())

GET /v4/domains/{domain} Get single domain (v4) ▼

Mailgun's /v4 single domain. It is the same endpoint as GET /v3/domains/{domain}: the domain with its sending and receiving DNS records. An account (primary) API key reads the domains of its own account, a sending API key its own domain only. A domain of another account (including a sub-account or a parent account) answers 404.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name

Responses

200

401

Unauthorized

{
  "message": "Unauthorized"
}

404

Domain not found, or not in your account

{
  "message": "Domain not found"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/v4/domains/{domain}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/v4/domains/{domain}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/v4/domains/{domain}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/v4/domains/{domain}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/v4/domains/{domain}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

PUT /v4/domains/{domain}/verify Verify domain (v4) ▼

Mailgun's /v4 domain verification. It is the same endpoint as PUT /v3/domains/{domain}/verify, with the same preconditions. Account (primary) API key only.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name

Responses

200

401

Unauthorized

{
  "message": "Unauthorized"
}

404

Domain not found, or not in your account

{
  "message": "Domain not found"
}

Code Samples

curl -X PUT 'https://mg-api.omnivery.net/v3/v4/domains/{domain}/verify' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("PUT", "https://mg-api.omnivery.net/v3/v4/domains/{domain}/verify", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/v4/domains/{domain}/verify', {
  method: 'PUT',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/v4/domains/{domain}/verify');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.put(
    'https://mg-api.omnivery.net/v3/v4/domains/{domain}/verify',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

Webhooks

GET /domains/{domain}/webhooks Get webhooks ▼

Returns a list of webhooks set for the specified domain. A domain without webhooks returns {"webhooks": {}}.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to list webhooks from

Responses

200

{
  "webhooks": {
    "clicked": {
      "urls": [
        "https://your_domain.com/v1/clicked"
      ]
    },
    "opened": {
      "urls": [
        "https://your_domain.com/v1/opened",
        "https://your_domain.com/v2/opened"
      ]
    }
  }
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/domains/{domain}/webhooks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/domains/{domain}/webhooks", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/domains/{domain}/webhooks',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

POST /domains/{domain}/webhooks Create webhook ▼

Creates a new webhook. Note When adding a Clicked or Opened webhook, ensure that you also have tracking enabled.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to add webhook to

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`id`	string	Yes	Name of the webhook
`url`	string	Yes	URL for the webhook event. May be repeated up to 3 times.

Responses

200

{
  "message": "Webhook has been created",
  "webhook": {
    "urls": [
      "https://your_domain.com/v1/clicked",
      "https://your_domain.com/v2/clicked",
      "https://your_partner_domain.com/v1/clicked"
    ]
  }
}

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/domains/{domain}/webhooks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"id": "string", "url": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/domains/{domain}/webhooks", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"id": "string", "url": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"id": "string", "url": "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://mg-api.omnivery.net/v3/domains/{domain}/webhooks',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"id": "string", "url": "string"}
)
print(response.json())

GET /domains/{domain}/webhooks/{webhookname} Get webhook details ▼

Returns details about a the webhook specified in the URL.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to retrieve webhook settings from
`webhookname`	path	string	Yes	Name of the webhook to retrieve data for (opened,clicked,delivered,softbounced,hardbounced,etc)

Responses

200

{
  "webhook": {
    "urls": [
      "https://your_domain.com/v1/clicked"
    ]
  }
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

PUT /domains/{domain}/webhooks/{webhookname} Update webhook ▼

Updates an existing webhook.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to update webhook settings for
`webhookname`	path	string	Yes	Name of the webhook to update

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`url`	string	Yes	URL for the webhook event. May be repeated up to 3 times.

Responses

200

{
  "message": "Webhook has been updated",
  "webhook": {
    "urls": [
      "https://your_domain.com/v1/clicked"
    ]
  }
}

Code Samples

curl -X PUT 'https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"url": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("PUT", "https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}', {
  method: 'PUT',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"url": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"url": "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://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"url": "string"}
)
print(response.json())

DELETE /domains/{domain}/webhooks/{webhookname} Delete webhook ▼

Deletes an existing webhook and URL endpoints assigned.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to delete webhook from
`webhookname`	path	string	Yes	Name of the webhook to delete

Responses

200

{
  "message": "Webhook has been deleted",
  "webhook": {
    "urls": [
      "https://your_domain.com/v1/clicked",
      "https://your_domain.com/v2/clicked",
      "https://your_partner_domain.com/v1/clicked"
    ]
  }
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/domains/{domain}/webhooks/{webhookname}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /v5/accounts/http_signing_key Get HTTP signing key ▼

Returns the key your account's webhook deliveries are signed with, so that a webhook receiver (or a migrated integration) can verify the signature of the events it gets. Base URL: https://mg-api.omnivery.net/v5.

It is the account's webhook signing key (the one shown in the UI), not the API key in use.

Differences from Mailgun: the key can only be read. Regenerating it (POST) is not available; rotate it in the UI.

Responses

200

{
  "http_signing_key": "3a9c1b2f5d7e4a8c9b0d1e2f3a4b5c6d"
}

401

Unauthorized

{
  "message": "Unauthorized"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/v5/accounts/http_signing_key' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/v5/accounts/http_signing_key", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/v5/accounts/http_signing_key', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/v5/accounts/http_signing_key');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/v5/accounts/http_signing_key',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

Bounces

GET /{domain}/bounces Get bounces ▼

Retrieve a list of bounce suppressions of a domain. Response may require pagination over multiple result sets.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to retrieve bounces for

Responses

200

"{\n  \"items\":\n    [\n      {\n        \"address\": \"alice@example.com\",\n        \"code\": \"550\",\n        \"error\": \"No such mailbox\",\n        \"created_at\": \"Fri, 21 Oct 2011 11:02:55 GMT\"\n      },\n      \n    ],\n  \"paging\":\n    {\n      \"first\": \u003cfirst page URL\u003e,\n      \"next\": \u003cnext page URL\u003e,\n      \"previous\": \u003cprevious page URL\u003e,\n      \"last\": \u003clast page URL\u003e\n    }\n}"

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/{domain}/bounces' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/{domain}/bounces", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/bounces', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/bounces');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/{domain}/bounces',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

POST /{domain}/bounces Add single bounce ▼

Add a bounce record to the bounce list.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to add bounce to

Request Body application/json

Field	Type	Required
`address`	string	Yes
`code`	string	No
`error`	string	No

Responses

200

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/{domain}/bounces' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"address": "string", "code": "string", "error": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/{domain}/bounces", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/bounces', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"address": "string", "code": "string", "error": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/bounces');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"address": "string", "code": "string", "error": "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://mg-api.omnivery.net/v3/{domain}/bounces',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"address": "string", "code": "string", "error": "string"}
)
print(response.json())

DELETE /{domain}/bounces Delete bounce list ▼

Delete all bounced addresses from a domain's bounce suppressions list.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name

Responses

200

{
  "message": "Bounced addresses for this domain have been removed"
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/{domain}/bounces' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/{domain}/bounces", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/bounces', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/bounces');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/{domain}/bounces',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /{domain}/bounces/{address} Get single bounce ▼

Fetch a single bounce event by a given email address. Useful to check if a given email address has bounced before.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to get bounce from
`address`	path	string	Yes	The address to lookup

Responses

200

{
  "address": "test@example.com",
  "code": "550",
  "created_at": "Fri, 21 Oct 2011 11:02:55 GMT",
  "error": "No such mailbox"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/{domain}/bounces/{address}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/{domain}/bounces/{address}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/bounces/{address}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/bounces/{address}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/{domain}/bounces/{address}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

DELETE /{domain}/bounces/{address} Delete bounce ▼

Delete single address from the bounce suppression list.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to delete bounce from
`address`	path	string	Yes	Address to remove from bounce suppression list

Responses

200

{
  "address": "test@example.com",
  "message": "Bounced address has been removed"
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/{domain}/bounces/{address}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/{domain}/bounces/{address}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/bounces/{address}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/bounces/{address}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/{domain}/bounces/{address}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

Complaints

GET /{domain}/complaints Get all complaints ▼

Retrieve a list of complaint suppressions of a domain. Response may require pagination over multiple result sets.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to retrieve complaint suppressions from

Responses

200

"{\n  \"items\":\n    [\n      {\n        \"address\": \"alice@example.com\",\n        \"error\": \"Recipient reported message as SPAM\",\n        \"created_at\": \"Fri, 21 Oct 2011 11:02:55 GMT\"\n      },\n      \n    ],\n  \"paging\":\n    {\n      \"first\": \u003cfirst page URL\u003e,\n      \"next\": \u003cnext page URL\u003e,\n      \"previous\": \u003cprevious page URL\u003e,\n      \"last\": \u003clast page URL\u003e\n    }\n}"

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/{domain}/complaints' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/{domain}/complaints", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/complaints', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/complaints');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/{domain}/complaints',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

POST /{domain}/complaints Add single complaint ▼

Add a complaint record to the complaint list.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to add complaint to

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`address`	string	Yes	Valid email address
`error`	string	Yes	Complaint description

Responses

200

{
  "address": "copmplained@example.com",
  "message": "Address has been added to the complaints table"
}

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/{domain}/complaints' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"address": "string", "error": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/{domain}/complaints", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/complaints', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"address": "string", "error": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/complaints');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"address": "string", "error": "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://mg-api.omnivery.net/v3/{domain}/complaints',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"address": "string", "error": "string"}
)
print(response.json())

DELETE /{domain}/complaints Delete complaint list ▼

Delete all complaint addresses from a domain's complaints suppression list.

The list is cleared in the background: a request answered with 200 has queued the removal.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name

Responses

200

{
  "message": "Complaint addresses for this domain have been removed"
}

401

Unauthorized

{
  "message": "Unauthorized"
}

404

Domain not found, or not in your account

{
  "message": "Domain not found"
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/{domain}/complaints' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/{domain}/complaints", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/complaints', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/complaints');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/{domain}/complaints',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /{domain}/complaints/{address} Get single complaint ▼

Fetch a single complaint event by a given email address. Useful to check if a given email address has complained before.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name to retrieve complaint from
`address`	path	string	Yes	Address to lookup in complaint list

Responses

200

{
  "address": "complained@example.com",
  "created_at": "Mon, 24 Jan 2022 16:51:06 GMT",
  "description": "Some complaint text"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/{domain}/complaints/{address}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/{domain}/complaints/{address}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/complaints/{address}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/complaints/{address}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/{domain}/complaints/{address}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

DELETE /{domain}/complaints/{address} Delete single complaint ▼

Delete single address from the complaint suppression list.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to remove complaint from
`address`	path	string	Yes	Address to remove

Responses

200

{
  "address": "complained@example.com",
  "message": "Spam complaint has been removed"
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/{domain}/complaints/{address}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/{domain}/complaints/{address}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/complaints/{address}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/complaints/{address}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/{domain}/complaints/{address}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

Unsubscribes

GET /{domain}/unsubscribes Get domain unsubscribes ▼

Retrieve a list of unsubscribe suppressions of a domain. Response may require pagination over multiple result sets.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to get unsubscribes from

Responses

200

{
  "items": [
    {
      "address": "test@example.com",
      "created_at": "Fri, 31 Dec 2021 14:30:25 GMT",
      "error": "Sample record"
    }
  ],
  "paging": {}
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/{domain}/unsubscribes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/{domain}/unsubscribes", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/unsubscribes', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/unsubscribes');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/{domain}/unsubscribes',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

POST /{domain}/unsubscribes Add single unsubscribe ▼

Add a unsubscribe record to the unsubscribe list.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to add unsubscribe to

Request Body application/x-www-form-urlencoded

Field	Type	Required	Description
`address`	string	Yes	Valid email address
`error`	string	Yes	Unsubscribe reason or description (optional)

Responses

200

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/{domain}/unsubscribes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"address": "string", "error": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/{domain}/unsubscribes", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/unsubscribes', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
  body: JSON.stringify({"address": "string", "error": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/unsubscribes');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"address": "string", "error": "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://mg-api.omnivery.net/v3/{domain}/unsubscribes',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"address": "string", "error": "string"}
)
print(response.json())

DELETE /{domain}/unsubscribes Delete unsubscribe list ▼

Delete all unsubscribed addresses from a domain's unsubscribes suppression list.

The list is cleared in the background: a request answered with 200 has queued the removal.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain name

Responses

200

{
  "message": "Unsubscribe addresses for this domain have been removed"
}

401

Unauthorized

{
  "message": "Unauthorized"
}

404

Domain not found, or not in your account

{
  "message": "Domain not found"
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/{domain}/unsubscribes' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/{domain}/unsubscribes", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/unsubscribes', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/unsubscribes');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/{domain}/unsubscribes',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /{domain}/unsubscribes/{address} Get single unsubscribe ▼

Get a single unsubscribe record in the selected domain. This might be useful to check if a specific recipient has unsubscribed before.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to get unsubscribe from
`address`	path	string	Yes	Address to lookup

Responses

200

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

DELETE /{domain}/unsubscribes/{address} Delete single unsubscribe ▼

Delete single address from the unsubscribe suppression list.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to delete unsubscribe from
`address`	path	string	Yes	Address to remove

Responses

200

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/{domain}/unsubscribes/{address}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

Whitelists

GET /{domain}/whitelists Get whitelist ▼

Retrieve a list of allowlisted addresses of a domain. Response may require pagination over multiple result sets.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to retrieve allowlist for

Responses

200

{
  "items": [
    {
      "created_at": "Mon, 24 Jan 2022 16:29:09 GMT",
      "type": "address",
      "value": "whitelisted@example.com"
    },
    {
      "created_at": "Mon, 24 Jan 2022 16:31:49 GMT",
      "type": "address",
      "value": "1whitelisted@example.com"
    },
    {
      "created_at": "Mon, 24 Jan 2022 16:31:51 GMT",
      "type": "address",
      "value": "2whitelisted@example.com"
    }
  ],
  "paging": {
    "first": "https://mg-api.omnivery.dev/v3/ov.omnivery.dev/whitelists?limit=3\u0026skip=0",
    "last": "https://mg-api.omnivery.dev/v3/ov.omnivery.dev/whitelists?limit=3\u0026skip=9",
    "next": "https://mg-api.omnivery.dev/v3/ov.omnivery.dev/whitelists?limit=3\u0026skip=3"
  }
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/{domain}/whitelists' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/{domain}/whitelists", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/whitelists', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/whitelists');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/{domain}/whitelists',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

POST /{domain}/whitelists Add record to whitelist ▼

Add an email address to the whitelist. Whitelisted addresses are exempt from suppressions. Whitelisting can be used to prevent test addresses (internal emails, seed-lists, etc) from being suppressed.

Parameters

Name	In	Type	Required	Description
`address`	query	string	Yes	Email address to add to whitelist
`domain`	path	string	Yes	Domain whitelist to use

Responses

200

{
  "message": "Address/Domain has been added to the whitelists table",
  "type": "address",
  "value": "whitelisted@example.com"
}

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/{domain}/whitelists' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://mg-api.omnivery.net/v3/{domain}/whitelists", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/whitelists', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/whitelists');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.post(
    'https://mg-api.omnivery.net/v3/{domain}/whitelists',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /{domain}/whitelists/{address} Get whitelist record ▼

Fetch a single allowlist record for a given email address. Useful to check if a given email address has been whitelisted before.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to query for allowlist
`address`	path	string	Yes	Address to lookup

Responses

200

{
  "created_at": "Mon, 24 Jan 2022 16:29:09 GMT",
  "type": "address",
  "value": "whitelisted@example.com"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

DELETE /{domain}/whitelists/{address} Delete record from whitelist ▼

Delete single address from the whitelist.

Parameters

Name	In	Type	Required	Description
`domain`	path	string	Yes	Domain to delete allowlist record from
`address`	path	string	Yes	Address to remove

Responses

200

{
  "message": "Whitelist address/domain has been removed",
  "value": "whitelisted@example.com1"
}

Code Samples

curl -X DELETE 'https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("DELETE", "https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}', {
  method: 'DELETE',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.delete(
    'https://mg-api.omnivery.net/v3/{domain}/whitelists/{address}',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

Email Validation

GET /address/private/parse Parse email address ▼

Parse email address strings and lists into objects with distinct address and name.

Parameters

Name	In	Type	Required	Description
`addresses`	query	string	Yes	Email address string

Responses

200

{
  "parsed": [
    {
      "domain": "example.com",
      "email": "alice@example.com",
      "localpart": "alice",
      "name": "Alice"
    },
    {
      "domain": "example.com",
      "email": "bob@example.com",
      "localpart": "bob"
    }
  ],
  "unparseable": []
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/address/private/parse' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/address/private/parse", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/address/private/parse', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/address/private/parse');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/address/private/parse',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

GET /address/private/validate Validate address ▼

Validate a single email address

The reason node contains detailed information about the result. Here's a list of all available reasons:

invalid_email - Specified email is not a valid email address syntax
invalid_domain - Domain for email does not exist
rejected_email - Email address was rejected by the SMTP server, email address does not exist
accepted_email - Email address was accepted by the SMTP server
low_quality - Email address has quality issues that may make it a risky or low-value address
low_deliverability - Email address appears to be deliverable, but deliverability cannot be guaranteed
no_connect - Could not connect to SMTP server
timeout - SMTP session timed out
invalid_smtp - SMTP server returned an unexpected/invalid response
unavailable_smtp - SMTP server was unavailable to process our request
unexpected_error - An unexpected error has occurred

Parameters

Name	In	Type	Required	Description
`address`	query	string	Yes	Email address to validate

Responses

200

{
  "address": "test@omnivery.com",
  "did_you_mean": null,
  "is_disposable_address": false,
  "is_role_address": false,
  "is_valid": true,
  "parts": {
    "domain": "omnivery.com",
    "local_part": "test"
  },
  "reason": "accepted_email"
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/address/private/validate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/address/private/validate", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/address/private/validate', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/address/private/validate');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/address/private/validate',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

Stats

GET /{domain}/stats/total Get domain stats ▼

Returns total stats for a given domain.

Parameter	Description
event	The type of the event. For a complete list of all events written to the log see the Event Types table below. (Required)
start	The starting time. Should be in RFC 2822#page-14 or unix epoch format. Default: 7 days from the current time.
end	The ending date. Should be in RFC 2822#page-14 or unix epoch format. Default: current time.
resolution	Can be either `hour`, `day` or `month`. Default: `day`

Parameters

Name	In	Type	Required	Description
`event`	query	string	Yes	The type of the event. For a complete list of all events written to the log see the Event Types table below. (Required)
`resolution`	query	string	No	Can be either hour, day or month. Default: day
`domain`	path	string	Yes	Domain name to query data for
`start`	query	string	No	The starting time. Should be in RFC 2822#page-14 or unix epoch format. Default: 7 days from the current time.
`end`	query	string	No	The ending date. Should be in RFC 2822#page-14 or unix epoch format. Default: current time.

Responses

200

{
  "end": "Fri, 01 Apr 2012 00:00:00 UTC",
  "resolution": "month",
  "start": "Tue, 14 Feb 2012 00:00:00 UTC",
  "stats": [
    {
      "accepted": {
        "incoming": 5,
        "outgoing": 10,
        "total": 15
      },
      "delivered": {
        "http": 5,
        "smtp": 15,
        "total": 20
      },
      "failed": {
        "permanent": {
          "bounce": 4,
          "delayed-bounce": 1,
          "suppress-bounce": 1,
          "suppress-complaint": 3,
          "suppress-unsubscribe": 2,
          "total": 10
        },
        "temporary": {
          "espblock": 1
        }
      },
      "time": "Tue, 14 Feb 2012 00:00:00 UTC"
    }
  ]
}

Code Samples

curl -X GET 'https://mg-api.omnivery.net/v3/{domain}/stats/total' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://mg-api.omnivery.net/v3/{domain}/stats/total", nil)
    req.SetBasicAuth("username", "password")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://mg-api.omnivery.net/v3/{domain}/stats/total', {
  method: 'GET',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
});
const data = await response.json();

<?php
$ch = curl_init('https://mg-api.omnivery.net/v3/{domain}/stats/total');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    'https://mg-api.omnivery.net/v3/{domain}/stats/total',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
print(response.json())

domain path *

event query *

resolution query

start query

end query