Get started

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:

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.

Parameters

NameInTypeRequiredDescription
Accept header string No
Content-Type header string No

Request Body application/json

FieldTypeRequiredDescription
attachments array No

An array of attachment objects to be included in the message.
FieldTypeRequiredDescription
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 No

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.
FieldTypeRequiredDescription
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 No

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.
FieldTypeRequiredDescription
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).
FieldTypeRequiredDescription
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 No

Mail settings allow you to control certain attributes of message processing
FieldTypeRequiredDescription
sandbox_mode object No

Sandbox Mode allows you to send a test email to ensure that your request body is valid and formatted correctly.
FieldTypeRequiredDescription
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.
FieldTypeRequiredDescription
bcc array No

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.
FieldTypeRequiredDescription
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 No

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.
FieldTypeRequiredDescription
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 No

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.
FieldTypeRequiredDescription
id string No
dynamic_template_data object No

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).
FieldTypeRequiredDescription
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.
subject string No

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

An object of key/value pairs following the pattern "substitution_tag":"value to substitute".
FieldTypeRequiredDescription
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.
FieldTypeRequiredDescription
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 No

Email address object with the email address and full name of the sender (from) or recipient (to, cc, bcc or reply-tp).
FieldTypeRequiredDescription
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.
subject string Yes

The subject of your email.
substitutions object No

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

A collection of different settings that you can use to override domain defaults.
FieldTypeRequiredDescription
click_tracking object No

Allows you to set specific click tracking overriding the domain's default setting.
FieldTypeRequiredDescription
enable boolean No
enable_text boolean No
open_tracking object No

Allows you to set specific open tracking overriding the domain's default setting.
FieldTypeRequiredDescription
enable boolean No
substitution_tag string No

Responses

202

Accepted
400

Bad Request

 
{
  "errors": [
    {
      "field": "from.email",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.from",
      "message": "The from email does not contain a valid address."
    },
    {
      "field": "personalizations.0.to.0.email",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.to",
      "message": "Does not contain a valid address."
    },
    {
      "field": "personalizations.0.to.1.email",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.to",
      "message": "Does not contain a valid address."
    },
    {
      "field": "personalizations.0.cc.0.email",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.cc",
      "message": "Does not contain a valid address."
    },
    {
      "field": "personalizations.0.bcc.0.email",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.bcc",
      "message": "Does not contain a valid address."
    },
    {
      "field": "personalizations.1.to.0.email",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.to",
      "message": "Does not contain a valid address."
    },
    {
      "field": "personalizations.1.bcc.0.email",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.bcc",
      "message": "Does not contain a valid address."
    },
    {
      "field": "personalizations.1.from.email",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.from",
      "message": "Does not contain a valid address."
    },
    {
      "field": "personalizations.1.from",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.from",
      "message": "The top level from email domain does not match all the from email domains in the personalization array"
    },
    {
      "field": "reply_to.email",
      "help": "http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.reply_to",
      "message": "The reply_to email does not contain a valid address."
    }
  ]
}
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"}, "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"}, "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"}, "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"}, "subject": "string", "substitutions": {"key": "string"}, "tracking_settings": {"click_tracking": {"enable": false, "enable_text": false}, "open_tracking": {"enable": false, "substitution_tag": "string"}}}
)
print(response.json())
Response

                            

                        

                    

                

            

            
        

        
        

            
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

                        

                            
                                
NameInTypeRequiredDescription

                            
                            
                                
                                

                                    Accept
                                    header
                                    string
                                    No
                                    
                                

                                
                                

                                    Content-Type
                                    header
                                    string
                                    No
                                    
                                

                                
                            
                        

                    

                    

                    
                    

                        
Request Body application/json

                        



    
        
FieldTypeRequiredDescription

    
    
        
        

            email
            string
            Yes
            
Email address to validate


        

        
        
        
    




                    

                    

                    
                    

                        
Responses

                        
                        

                            

                                200
                                
OK


                            

                            
                        

                        
                    

                    

                    

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

                            
                        

                    


                    

                        
                        

                            

                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                
                                

                                    
                                    
                                

                                
                                
                                
                                

                                    
                                    
                                

                                
                                
                                
                                

                                    
                                    
                                

                                
                                
                            

                            

                                
Response