Sendgrid API

vv3 Base URL: https://sg-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 SendGrid v3 compatible API of Omnivery.

As this API is fully compatible with the SendGrid (v3) API any existing software or library support ing SendGrid (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 the Authorization header with your access token as a Bearer token (Authorization: Bearer <access token>). API tokens can be found in the UI under Credentials menu in API Keys tab (for domain specific/sending tokens) or under API keys menu. For security reasons we strongly suggest using domain specific API keys rather than account API keys whenever possible.

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

Authentication

API Key: HTTP bearer

Enter your credentials below to use the Try it feature:

Bearer Token

Mail

POST /mail/send Mail Send ▼

This endpoint allows you to send email using SendGrid v3 compatible API

Top level parameters are referred to as "global".
Individual fields within the personalizations array will override any other global, or "message level", parameters that are defined outside of personalizations.

This endpoint requires use of domain level API credentials and can not be used with account level API key.

Scheduled delivery

Set send_at to a unix timestamp to hold the message and deliver it at that time. A global send_at applies to every personalization; a send_at inside a personalization overrides it for that personalization only.

The time must be less than 72 hours in the future. A later time is rejected with HTTP status code 400.

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

A value that is not an integer unix timestamp is rejected with HTTP status code 400.

Every send_at in the request is checked before anything is sent, so one invalid value rejects the whole request. The error's field names the offending value, e.g. send_at or personalizations.1.send_at (0-based).

Parameters

Name	In	Type	Required	Description
`Accept`	header	string	No
`Content-Type`	header	string	No

Request Body application/json

Field Type Required Description

attachments

array

An array of attachment objects to be included in the message.

Field	Type	Required	Description
`content`	string	Yes	The Base64 encoded content of the attachment.
`disposition`	string	No	The attachment's content-disposition, specifying how you would like the attachment to be displayed. For example, `"inline"` results in the attached file are displayed automatically within the message while `"attachment"` results in the attached file require some action to be taken before it is displayed, such as opening or downloading the file.
`filename`	string	Yes	The attachment's filename.
`type`	string	Yes	The MIME type of the content you are attaching (e.g., `"text/plain"` or `"text/html"`).

callback_url string No

categories

array

An array of category names for this message. Each category name may not exceed 64 characters.

content

array

Yes

An array where you can specify the content of your email. You can include multiple MIME types of content, but you must specify at least one MIME type. To include more than one MIME type, add another object to the array containing the type and value parameters.

Field	Type	Required	Description
`type`	string	Yes	The MIME type of the content you are including in your email (e.g., `"text/plain"` or `"text/html"`).
`value`	string	Yes	The actual content of the specified MIME type that you are including in your email.

custom_args

object

Custom values are key/value pairs attached to the message. Key/value pairs must be strings. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. Custom arguments defined in personalizations will override arguments set on global level.

Field	Type	Required	Description
`id`	string	No

from

object

Yes

Email address object with the email address and full name of the sender (from) or recipient (to, cc, bcc or reply-tp).

Field	Type	Required	Description
`email`	string	Yes	The email address used to send or deliver the message.
`name`	string	No	A name or title associated with the email address.

mail_settings

object

Mail settings allow you to control certain attributes of message processing

Field Type Required Description

sandbox_mode

object

Sandbox Mode allows you to send a test email to ensure that your request body is valid and formatted correctly.

Field	Type	Required	Description
`enable`	boolean	No

personalizations

array

Yes

An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled.

Field Type Required Description

bcc

array

An array of recipients who will receive a blind carbon copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.

Field	Type	Required	Description
`email`	string	Yes	The email address used to send or deliver the message.
`name`	string	No	A name or title associated with the email address.

cc

array

An array of recipients who will receive a copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.

Field	Type	Required	Description
`email`	string	Yes	The email address used to send or deliver the message.
`name`	string	No	A name or title associated with the email address.

custom_args

object

Field	Type	Required	Description
`id`	string	No

dynamic_template_data

object

Dynamic template data are variables used in Templates. Unlike custom_args the template data will not be stored and passed back in the webhook. This field is a collection of key/value pairs following the pattern "variable_name":"value to insert".

from

object

Yes

Email address object with the email address and full name of the sender (from) or recipient (to, cc, bcc or reply-tp).

Field	Type	Required	Description
`email`	string	Yes	The email address used to send or deliver the message.
`name`	string	No	A name or title associated with the email address.

send_at

integer

A unix timestamp allowing you to specify when the email for this personalization should be delivered. Overrides the global send_at for this personalization only. Must be less than 72 hours in the future.

subject

string

The subject of your email. When set the subject from the personalizations object takes precedence over the subject set in global parameters.

substitutions

object

An object of key/value pairs following the pattern "substitution_tag":"value to substitute".

Field	Type	Required	Description
`key`	string	No

to

array

Yes

An array of recipients who will receive this email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.

Field	Type	Required	Description
`email`	string	Yes	The email address used to send or deliver the message.
`name`	string	No	A name or title associated with the email address.

reply_to

object

Email address object with the email address and full name of the sender (from) or recipient (to, cc, bcc or reply-tp).

Field	Type	Required	Description
`email`	string	Yes	The email address used to send or deliver the message.
`name`	string	No	A name or title associated with the email address.

send_at

integer

A unix timestamp allowing you to specify when you want your email to be delivered. Applies to every personalization that does not set its own send_at. Must be less than 72 hours in the future; a time that is now or already past sends the message immediately.

subject

string

Yes

The subject of your email.

substitutions

object

An object of key/value pairs following the pattern "substitution_tag":"value to substitute".

Field	Type	Required	Description
`key`	string	No

tracking_settings

object

A collection of different settings that you can use to override domain defaults.

Field Type Required Description

click_tracking

object

Allows you to set specific click tracking overriding the domain's default setting.

Field	Type	Required	Description
`enable`	boolean	No
`enable_text`	boolean	No

open_tracking

object

Allows you to set specific open tracking overriding the domain's default setting.

Field	Type	Required	Description
`enable`	boolean	No
`substitution_tag`	string	No

Responses

202

Accepted

400

Bad Request

402

Payment Required

Code Samples

curl -X POST 'https://sg-api.omnivery.net/v3/mail/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"attachments": [], "callback_url": "string", "categories": [], "content": [], "custom_args": {"id": "string"}, "from": {"email": "string", "name": "string"}, "mail_settings": {"sandbox_mode": {"enable": false}}, "personalizations": [], "reply_to": {"email": "string", "name": "string"}, "send_at": 1.6172604e+09, "subject": "string", "substitutions": {"key": "string"}, "tracking_settings": {"click_tracking": {"enable": false, "enable_text": false}, "open_tracking": {"enable": false, "substitution_tag": "string"}}}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://sg-api.omnivery.net/v3/mail/send", nil)
    req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sg-api.omnivery.net/v3/mail/send', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN'},
  body: JSON.stringify({"attachments": [], "callback_url": "string", "categories": [], "content": [], "custom_args": {"id": "string"}, "from": {"email": "string", "name": "string"}, "mail_settings": {"sandbox_mode": {"enable": false}}, "personalizations": [], "reply_to": {"email": "string", "name": "string"}, "send_at": 1.6172604e+09, "subject": "string", "substitutions": {"key": "string"}, "tracking_settings": {"click_tracking": {"enable": false, "enable_text": false}, "open_tracking": {"enable": false, "substitution_tag": "string"}}})
});
const data = await response.json();

<?php
$ch = curl_init('https://sg-api.omnivery.net/v3/mail/send');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_TOKEN']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"attachments": [], "callback_url": "string", "categories": [], "content": [], "custom_args": {"id": "string"}, "from": {"email": "string", "name": "string"}, "mail_settings": {"sandbox_mode": {"enable": false}}, "personalizations": [], "reply_to": {"email": "string", "name": "string"}, "send_at": 1.6172604e+09, "subject": "string", "substitutions": {"key": "string"}, "tracking_settings": {"click_tracking": {"enable": false, "enable_text": false}, "open_tracking": {"enable": false, "substitution_tag": "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://sg-api.omnivery.net/v3/mail/send',
    headers={'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN'},
    json={"attachments": [], "callback_url": "string", "categories": [], "content": [], "custom_args": {"id": "string"}, "from": {"email": "string", "name": "string"}, "mail_settings": {"sandbox_mode": {"enable": false}}, "personalizations": [], "reply_to": {"email": "string", "name": "string"}, "send_at": 1.6172604e+09, "subject": "string", "substitutions": {"key": "string"}, "tracking_settings": {"click_tracking": {"enable": false, "enable_text": false}, "open_tracking": {"enable": false, "substitution_tag": "string"}}}
)
print(response.json())

Address

POST /validations/email Validate Email Address ▼

Email Address Validation provides real-time detailed information on the validity of email addresses. You can integrate this validation process into your platform's signup form and customize the best use of email address validation for your use case.

Email validation must be enabled in the domain settings requires use of domain level API credentials.

Parameters

Name	In	Type	Required	Description
`Accept`	header	string	No
`Content-Type`	header	string	No

Request Body application/json

Field	Type	Required	Description
`email`	string	Yes	Email address to validate

Responses

200

Code Samples

curl -X POST 'https://sg-api.omnivery.net/v3/validations/email' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"email": "string"}'

package main

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("POST", "https://sg-api.omnivery.net/v3/validations/email", nil)
    req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
    resp, _ := http.DefaultClient.Do(req)
    fmt.Println(resp.Status)
}

const response = await fetch('https://sg-api.omnivery.net/v3/validations/email', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN'},
  body: JSON.stringify({"email": "string"})
});
const data = await response.json();

<?php
$ch = curl_init('https://sg-api.omnivery.net/v3/validations/email');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_TOKEN']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"email": "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://sg-api.omnivery.net/v3/validations/email',
    headers={'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN'},
    json={"email": "string"}
)
print(response.json())