The Twilio SendGrid Enforced TLS API allows you to specify whether or not the recipient of your mail send is required to support TLS or have a valid certificate. Twilio SendGrid sends all emails with [Opportunistic TLS](https://sendgrid.com/blog/myth-opportunistic-tls-email-privacy/) by default, meaning email is sent with TLS, and if the recipient's inbox provider does not accept the TLS encryption, we then send the message unencrypted.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Enforced TLS API
summary: The Twilio SendGrid Enforced TLS API allows you to specify whether or not
the recipient of your mail send is required to support TLS or have a valid certificate.
description: "The Twilio SendGrid Enforced TLS API allows you to specify whether\
\ or not the recipient of your mail send is required to support TLS or have a\
\ valid certificate.\n\nTwilio SendGrid sends all emails with [Opportunistic TLS](https://sendgrid.com/blog/myth-opportunistic-tls-email-privacy/)\
\ by default, meaning email is sent with TLS, and if the recipient's inbox provider\
\ does not accept the TLS encryption, we then send the message unencrypted.\n\n\
You can optionally choose to enforce TLS encryption, meaning that if the recipient's\
\ inbox provider does not accept the TLS encryption, Twilio SendGrid drops the\
\ message and sends a block event with the message, \u201CTLS required but not\
\ supported\u201D as the description."
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: enforced_tls
servers:
- url: https://api.sendgrid.com
description: for global users and subusers
- url: https://api.eu.sendgrid.com
description: for EU regional subusers
paths:
/v3/user/settings/enforced_tls:
get:
operationId: ListEnforcedTlsSetting
summary: Retrieve current Enforced TLS settings.
tags:
- Enforced TLS
description: "**This endpoint allows you to retrieve your current Enforced TLS\
\ settings.**\n\nThe Enforced TLS settings specify whether or not the recipient\
\ is required to support TLS or have a valid certificate.\n\nIf either `require_tls`\
\ or `require_valid_cert` is set to `true`, the recipient must support TLS\
\ 1.1 or higher or have a valid certificate. If these conditions are not met,\
\ Twilio SendGrid will drop the message and send a block event with \u201C\
TLS required but not supported\u201D as the description."
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EnforcedTlsRequestResponse'
examples:
response:
value:
require_tls: false
require_valid_cert: false
'401':
$ref: '#/components/responses/EnforcedTls401'
'403':
$ref: '#/components/responses/EnforcedTls403'
'404':
$ref: '#/components/responses/EnforcedTls404'
'500':
$ref: '#/components/responses/EnforcedTls500'
patch:
operationId: UpdateEnforcedTlsSetting
summary: Update Enforced TLS settings
tags:
- Enforced TLS
description: "**This endpoint allows you to update your Enforced TLS settings.**\n\
\nTo require TLS from recipients, set `require_tls` to `true`. If either `require_tls`\
\ or `require_valid_cert` is set to `true`, the recipient must support TLS\
\ 1.1 or higher or have a valid certificate. If these conditions are not met,\
\ Twilio SendGrid will drop the message and send a block event with \u201C\
TLS required but not supported\u201D as the description."
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnforcedTlsRequestResponse'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EnforcedTlsRequestResponse'
examples:
response:
value:
require_tls: true
require_valid_cert: false
'401':
$ref: '#/components/responses/EnforcedTls401'
'403':
$ref: '#/components/responses/EnforcedTls403'
'404':
$ref: '#/components/responses/EnforcedTls404'
'500':
$ref: '#/components/responses/EnforcedTls500'
components:
schemas:
EnforcedTlsRequestResponse:
title: Enforced TLS Request Response
type: object
properties:
require_tls:
type: boolean
description: 'Indicates if you want to require your recipients to support
TLS. '
require_valid_cert:
type: boolean
description: Indicates if you want to require your recipients to have a
valid certificate.
version:
type: number
format: float
description: The minimum required TLS certificate version.
default: 1.1
$ref: '#/components/schemas/Version'
example:
require_tls: true
require_valid_cert: true
version: 1.1
ErrorResponse:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
description: An error message.
field:
description: When applicable, this property value will be the field
that generated the error.
nullable: true
type: string
help:
type: object
description: When applicable, this property value will be helper text
or a link to documentation to help you troubleshoot the error.
id:
type: string
description: When applicable, this property value will be an error ID.
example:
errors:
- field: field_name
message: error message
Version:
type: number
enum:
- 1.1
- 1.2
- 1.3
responses:
EnforcedTls401:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
EnforcedTls403:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
EnforcedTls404:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
EnforcedTls500:
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
parameters:
OnBehalfOf:
name: on-behalf-of
in: header
description: 'The `on-behalf-of` header allows you to make API calls from a
parent account on behalf of the parent''s Subusers or customer accounts. You
will use the parent account''s API key when using this header. When making
a call on behalf of a customer account, the property value should be "account-id"
followed by the customer account''s ID (e.g., `on-behalf-of: account-id <account-id>`).
When making a call on behalf of a Subuser, the property value should be the
Subuser''s username (e.g., `on-behalf-of: <subuser-username>`). See [**On
Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of)
for more information.'
required: false
schema:
type: string
examples: {}
requestBodies: {}
headers: {}
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Twilio SendGrid requires you to authenticate with its APIs using
an API key. The API key must be sent as a bearer token in the Authorization
header.
tags:
- name: Enforced TLS
description: The Twilio SendGrid Enforced TLS API
externalDocs:
description: Twilio SendGrid's official developer documentation.
url: https://www.twilio.com/docs/sendgrid