Mail Settings

The following settings can also be used when sending mail via the Web API v3 Mail Send endpoint by enabling your desired settings within the "mail_settings" object of your JSON payload.

Get Mail Settings [GET]

URI Parameter Required Requirements Description
limit No number Number of settings to return.
Example: 20
offset No number Paging offset.
Example: 1

Request

1
GET https://api.sendgrid.com/v3/mail_settings?limit={limit}&offset={offset} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
HTTP/1.1 200
{
  "result": [
    {
      "name": "bcc",
      "title": "BCC",
      "description": "lorem ipsum... .",
      "enabled": true
    }
  ]
}

Get BCC Settings [GET]

Request

1
GET https://api.sendgrid.com/v3/mail_settings/bcc HTTP/1.1

Response

1
2
3
4
5
HTTP/1.1 200
{
  "enabled": true,
  "email": "email@example.com"
}

Update BCC Settings [PATCH]

Request

1
PATCH https://api.sendgrid.com/v3/mail_settings/bcc HTTP/1.1
Request Body
1
2
3
4
{
  "enabled": true,
  "email": "email@example.com"
}

Response

1
2
3
4
5
HTTP/1.1 200
{
  "enabled": true,
  "email": "email@example.com"
}

Get Address Whitelist Settings [GET]

Request

1
GET https://api.sendgrid.com/v3/mail_settings/address_whitelist HTTP/1.1

Response

1
2
3
4
5
6
7
8
HTTP/1.1 200
{
  "enabled": true,
  "list": [
    "email1@example.com",
    "example.com"
  ]
}

Update Address Whitelist Settings [PATCH]

Request

1
PATCH https://api.sendgrid.com/v3/mail_settings/address_whitelist HTTP/1.1
Request Body
1
2
3
4
5
6
7
{
  "enabled": true,
  "list": [
    "email1@example.com",
    "example.com"
  ]
}

Response

1
2
3
4
5
6
7
8
HTTP/1.1 200
{
  "enabled": true,
  "list": [
    "email1@example.com",
    "example.com"
  ]
}

Get Footer Settings [GET]

Request

1
GET https://api.sendgrid.com/v3/mail_settings/footer HTTP/1.1

Response

1
2
3
4
5
6
HTTP/1.1 200
{
  "enabled": true,
  "html_content": "...",
  "plain_content": "..."
}

Update Footer Settings [PATCH]

Request

1
PATCH https://api.sendgrid.com/v3/mail_settings/footer HTTP/1.1
Request Body
1
2
3
4
5
{
  "enabled": true,
  "html_content": "...",
  "plain_content": "..."
}

Response

1
2
3
4
5
6
HTTP/1.1 200
{
  "enabled": true,
  "html_content": "...",
  "plain_content": "..."
}

Get Forward Spam Settings [GET]

Request

1
GET https://api.sendgrid.com/v3/mail_settings/forward_spam HTTP/1.1

Response

1
2
3
4
5
HTTP/1.1 200
{
  "enabled": true,
  "email": "email address"
}

Update Forward Spam Settings [PATCH]

Request

1
PATCH https://api.sendgrid.com/v3/mail_settings/forward_spam HTTP/1.1
Request Body
1
2
3
4
{
  "enabled": true,
  "email": "email address"
}

Response

1
2
3
4
5
HTTP/1.1 200
{
  "enabled": true,
  "email": "email address"
}

Get Plain Content Settings [GET]

Request

1
GET https://api.sendgrid.com/v3/mail_settings/plain_content HTTP/1.1

Response

1
2
3
4
HTTP/1.1 200
{
  "enabled": true
}

Update Plain Text Content [PATCH]

Request

1
PATCH https://api.sendgrid.com/v3/mail_settings/plain_content HTTP/1.1
Request Body
1
2
3
{
  "enabled": true
}

Response

1
2
3
4
HTTP/1.1 200
{
  "enabled": true
}

Get Spam Check Settings [GET]

max_score should be between 1 and 10 inclusively

Request

1
GET https://api.sendgrid.com/v3/mail_settings/spam_check HTTP/1.1

Response

1
2
3
4
5
6
HTTP/1.1 200
{
  "enabled": true,
  "url": "url",
  "max_score": 5
}

Update Spam Check Settings [PATCH]

max_score should be between 1 and 10 inclusively url can be url or email

Request

1
PATCH https://api.sendgrid.com/v3/mail_settings/spam_check HTTP/1.1
Request Body
1
2
3
4
5
{
  "enabled": true,
  "url": "url",
  "max_score": 5
}

Response

1
2
3
4
5
6
HTTP/1.1 200
{
  "enabled": true,
  "url": "url",
  "max_score": 5
}

Get Template Settings [GET]

Request

1
GET https://api.sendgrid.com/v3/mail_settings/template HTTP/1.1

Response

1
2
3
4
5
HTTP/1.1 200
{
  "enabled": true,
  "html_content": "<% body %>"
}

Update Template Settings [PATCH]

Request

1
PATCH https://api.sendgrid.com/v3/mail_settings/template HTTP/1.1
Request Body
1
2
3
4
{
  "enabled": true,
  "html_content": "<% body %>"
}

Response

1
2
3
4
5
HTTP/1.1 200
{
  "enabled": true,
  "html_content": "<% body %>"
}

Get Bounce Purge Settings [GET]

hard_bounces and soft_bounces should be positive integers.

Request

1
GET https://api.sendgrid.com/v3/mail_settings/bounce_purge HTTP/1.1

Response

1
2
3
4
5
6
HTTP/1.1 200
{
  "enabled": true,
  "hard_bounces": 5,
  "soft_bounces": 5
}

Update Bounce Purge Settings [PATCH]

hard_bounces and soft_bounces should be positive integers.

Request

1
PATCH https://api.sendgrid.com/v3/mail_settings/bounce_purge HTTP/1.1
Request Body
1
2
3
4
5
{
  "enabled": true,
  "hard_bounces": 5,
  "soft_bounces": 5
}

Response

1
2
3
4
5
6
HTTP/1.1 200
{
  "enabled": true,
  "hard_bounces": 5,
  "soft_bounces": 5
}

Get Forward Bounce Settings [GET]

Request

1
GET https://api.sendgrid.com/v3/mail_settings/forward_bounce HTTP/1.1

Response

1
2
3
4
5
HTTP/1.1 200
{
  "enabled": true,
  "email": "email address"
}

Update Forward Bounce Settings [PATCH]

Request

1
PATCH https://api.sendgrid.com/v3/mail_settings/forward_bounce HTTP/1.1
Request Body
1
2
3
4
{
  "enabled": true,
  "email": "email address"
}

Response

1
2
3
4
5
HTTP/1.1 200
{
  "enabled": true,
  "email": "email address"
}