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.

As this API is fully compatible with the Mailgun (v3) API any existing software or library supporting Mailgun (v3) API should work without any changes required. The only change that may be required would be the change of the endpoint and API token

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

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)

Webhooks

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 /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())

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

Returns a list of webhooks set for the specified domain.

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())

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/{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())

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())

Domains

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
    }
  }
}

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())

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} 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())

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
`password`	string	Yes	A password for the SMTP credentials. (Length Min 5, Max 32)
`login`	string	Yes	The user name, for example bob.bar

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 '{"password": "string", "login": "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({"password": "string", "login": "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, '{"password": "string", "login": "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={"password": "string", "login": "string"}
)
print(response.json())

PATCH /{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/{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/{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/{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/{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/{domain}/disable',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
)
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())

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 /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 optional

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
}

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())

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())

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())

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

Response

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())

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())

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())

Messages

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
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`.
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.
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
`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.
`from`	string	Yes	Email address for `From` header
`o:tag`	string	No	Tag string for message tagging. Repeat the parameter multiple times to add multiple tags.
`subject`	string	Yes	Message subject
`t:variables`	string	No	Template variables as a JSON string. These variables will be passed to the template for processing.
`text`	string	No	Body of the message. (text version)
`amp-html`	string	No	AMP part of the message
`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 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.
`html`	string	No	Body of the message. (html version)
`reply_to`	string	No	Email addres for `Reply-To` header
`substitutions`	string	No	JSON string with substitions. The JSON key will be replaced with the matching value.
`template`	string	No	Filename of the template to use

Responses

200

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

Code Samples

curl -X POST 'https://mg-api.omnivery.net/v3/{domain}/messages' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic BASE64_CREDENTIALS' \
  -d '{"to": "string", "from": "string", "o:tag": "string", "subject": "string", "t:variables": "string", "text": "string", "amp-html": "string", "callback_url": "string", "h:X-testid": 0, "html": "string", "reply_to": "string", "substitutions": "string", "template": "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({"to": "string", "from": "string", "o:tag": "string", "subject": "string", "t:variables": "string", "text": "string", "amp-html": "string", "callback_url": "string", "h:X-testid": 0, "html": "string", "reply_to": "string", "substitutions": "string", "template": "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, '{"to": "string", "from": "string", "o:tag": "string", "subject": "string", "t:variables": "string", "text": "string", "amp-html": "string", "callback_url": "string", "h:X-testid": 0, "html": "string", "reply_to": "string", "substitutions": "string", "template": "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={"to": "string", "from": "string", "o:tag": "string", "subject": "string", "t:variables": "string", "text": "string", "amp-html": "string", "callback_url": "string", "h:X-testid": 0, "html": "string", "reply_to": "string", "substitutions": "string", "template": "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.
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`.
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.
v:my-var	`v:` prefix followed by an arbitrary name allows to attach a custom data to the message.
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
`h:headername`	integer	No	h: prefix allows you to add custom headers to your message. Certain headers like list-unsubscribe, precedence, Feedback-ID, etc. are reserved and set by the system.
`message`	string	Yes	MIME encoded message content. This must be a valid MIME encoded message including headers and all body parts.
`o:tag`	string	No	Add custom tags to your message. Repeat multiple times for multiple tags
`to`	string	Yes	List of recipients separated by comma. Don't forget to list all of your To, Cc and Bcc addresses here.
`v:variablename`	string	No	v: prefix followed by an arbitrary name allows to attach a custom data to the message. These variables will be available to you later on for tracking messages and recipients via webhooks.
`callback_url`	string	No	Webhook URL to post delivery/bounce/etc information to

Responses

200

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

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 '{"h:headername": 0, "message": "string", "o:tag": "string", "to": "string", "v:variablename": "string", "callback_url": "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({"h:headername": 0, "message": "string", "o:tag": "string", "to": "string", "v:variablename": "string", "callback_url": "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, '{"h:headername": 0, "message": "string", "o:tag": "string", "to": "string", "v:variablename": "string", "callback_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/{domain}/messages.mime',
    headers={'Content-Type': 'application/json', 'Authorization': 'Basic BASE64_CREDENTIALS'},
    json={"h:headername": 0, "message": "string", "o:tag": "string", "to": "string", "v:variablename": "string", "callback_url": "string"}
)
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())

Bounces

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

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 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())

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())