Sendgrid API

vv3 Base URL: https://sg-api.omnivery.net/v3

Omnivery Sendgrid v3 compatible API

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.

Parameters

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

Request Body application/json

Field Type Required Description

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
`value`	string	Yes	The actual content of the specified MIME type that you are including in your email.
`type`	string	Yes	The MIME type of the content you are including in your email (e.g., `"text/plain"` or `"text/html"`).

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

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.

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.

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
`name`	string	No	A name or title associated with the email address.
`email`	string	Yes	The email address used to send or deliver the message.

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

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".

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.

subject

string

Yes

The subject of your email.

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"`).

categories

array

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

custom_args

object

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
`name`	string	No	A name or title associated with the email address.
`email`	string	Yes	The email address used to send or deliver the message.

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

callback_url 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 '{"content": [], "mail_settings": {}, "personalizations": [], "reply_to": {}, "subject": "string", "attachments": [], "categories": [], "custom_args": {}, "from": {}, "substitutions": {}, "tracking_settings": {}, "callback_url": "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({"content": [], "mail_settings": {}, "personalizations": [], "reply_to": {}, "subject": "string", "attachments": [], "categories": [], "custom_args": {}, "from": {}, "substitutions": {}, "tracking_settings": {}, "callback_url": "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, '{"content": [], "mail_settings": {}, "personalizations": [], "reply_to": {}, "subject": "string", "attachments": [], "categories": [], "custom_args": {}, "from": {}, "substitutions": {}, "tracking_settings": {}, "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://sg-api.omnivery.net/v3/mail/send',
    headers={'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN'},
    json={"content": [], "mail_settings": {}, "personalizations": [], "reply_to": {}, "subject": "string", "attachments": [], "categories": [], "custom_args": {}, "from": {}, "substitutions": {}, "tracking_settings": {}, "callback_url": "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())