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