Twilio SendGrid Email API

openapi: 3.1.0
info:
  title: Twilio SendGrid Email API
  description: >-
    Send, manage, and analyze emails at scale using the Twilio SendGrid Email
    API. Supports transactional and marketing email, dynamic templates,
    email validation, sender authentication, suppressions management, and
    real-time analytics.
  version: '3.0'
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com
    email: [email protected]
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.twilio.com/legal/tos
externalDocs:
  description: Twilio SendGrid API Documentation
  url: https://www.twilio.com/docs/sendgrid
servers:
  - url: https://api.sendgrid.com/v3
    description: SendGrid API v3
tags:
  - name: Contacts
    description: Manage marketing contacts
  - name: Email Validation
    description: Validate email addresses
  - name: Lists
    description: Manage contact lists
  - name: Mail Send
    description: Send email messages
  - name: Senders
    description: Manage verified sender identities
  - name: Stats
    description: Retrieve email analytics and statistics
  - name: Suppressions
    description: Manage email suppressions and bounces
  - name: Templates
    description: Manage dynamic email templates
security:
  - bearerAuth: []
paths:
  /mail/send:
    post:
      operationId: sendEmail
      summary: Twilio Send an Email
      description: >-
        Send an email message to one or more recipients. Supports
        personalizations, dynamic templates, attachments, categories,
        and scheduling.
      tags:
        - Mail Send
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
      responses:
        '202':
          description: Email accepted for delivery
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '413':
          description: Payload too large
        '429':
          description: Rate limit exceeded
  /templates:
    get:
      operationId: listTemplates
      summary: Twilio List Email Templates
      description: >-
        Retrieve all transactional or dynamic templates.
      tags:
        - Templates
      parameters:
        - name: generations
          in: query
          description: Filter by template generation
          schema:
            type: string
            enum:
              - legacy
              - dynamic
        - name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
      responses:
        '200':
          description: List of templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateList'
    post:
      operationId: createTemplate
      summary: Twilio Create an Email Template
      tags:
        - Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Template name (max 100 characters)
                  maxLength: 100
                generation:
                  type: string
                  enum: [legacy, dynamic]
                  default: dynamic
      responses:
        '201':
          description: Template created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
  /templates/{template_id}:
    get:
      operationId: fetchTemplate
      summary: Twilio Fetch a Template
      tags:
        - Templates
      parameters:
        - name: template_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Template details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '404':
          description: Template not found
    patch:
      operationId: updateTemplate
      summary: Twilio Update a Template
      tags:
        - Templates
      parameters:
        - name: template_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
      responses:
        '200':
          description: Template updated
    delete:
      operationId: deleteTemplate
      summary: Twilio Delete a Template
      tags:
        - Templates
      parameters:
        - name: template_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Template deleted
  /templates/{template_id}/versions:
    post:
      operationId: createTemplateVersion
      summary: Twilio Create a Template Version
      tags:
        - Templates
      parameters:
        - name: template_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateVersionRequest'
      responses:
        '201':
          description: Template version created
  /marketing/contacts:
    get:
      operationId: listContacts
      summary: Twilio List Marketing Contacts
      description: >-
        Retrieve a paginated list of marketing contacts.
      tags:
        - Contacts
      responses:
        '200':
          description: List of contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
    put:
      operationId: upsertContacts
      summary: Twilio Add or Update Contacts
      description: >-
        Add new contacts or update existing ones. Contacts are matched
        by email address.
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                list_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: List IDs to add contacts to
                contacts:
                  type: array
                  items:
                    $ref: '#/components/schemas/ContactRequest'
                  maxItems: 30000
      responses:
        '202':
          description: Contacts accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: string
    delete:
      operationId: deleteContacts
      summary: Twilio Delete Contacts
      tags:
        - Contacts
      parameters:
        - name: ids
          in: query
          required: true
          description: Comma-separated contact IDs
          schema:
            type: string
      responses:
        '202':
          description: Contacts deletion accepted
  /marketing/contacts/search:
    post:
      operationId: searchContacts
      summary: Twilio Search Contacts
      description: >-
        Search contacts using SGQL (SendGrid Query Language).
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: SGQL query string
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
  /marketing/lists:
    get:
      operationId: listContactLists
      summary: Twilio List Contact Lists
      tags:
        - Lists
      parameters:
        - name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: List of contact lists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListCollection'
    post:
      operationId: createContactList
      summary: Twilio Create a Contact List
      tags:
        - Lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
      responses:
        '201':
          description: List created
  /marketing/lists/{list_id}:
    get:
      operationId: fetchContactList
      summary: Twilio Fetch a Contact List
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Contact list details
    patch:
      operationId: updateContactList
      summary: Twilio Update a Contact List
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: List updated
    delete:
      operationId: deleteContactList
      summary: Twilio Delete a Contact List
      tags:
        - Lists
      parameters:
        - name: list_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: delete_contacts
          in: query
          description: Whether to delete contacts in the list
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: List deleted
  /verified_senders:
    get:
      operationId: listVerifiedSenders
      summary: Twilio List Verified Senders
      tags:
        - Senders
      responses:
        '200':
          description: List of verified senders
    post:
      operationId: createVerifiedSender
      summary: Twilio Create a Verified Sender
      tags:
        - Senders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerifiedSenderRequest'
      responses:
        '201':
          description: Verified sender created
        '400':
          description: Invalid request
  /suppression/bounces:
    get:
      operationId: listBounces
      summary: Twilio List Bounced Emails
      tags:
        - Suppressions
      parameters:
        - name: start_time
          in: query
          schema:
            type: integer
            description: Start of date range (Unix timestamp)
        - name: end_time
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of bounces
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bounce'
    delete:
      operationId: deleteBounces
      summary: Twilio Delete Bounces
      tags:
        - Suppressions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                delete_all:
                  type: boolean
                emails:
                  type: array
                  items:
                    type: string
                    format: email
      responses:
        '204':
          description: Bounces deleted
  /suppression/blocks:
    get:
      operationId: listBlocks
      summary: Twilio List Blocked Emails
      tags:
        - Suppressions
      parameters:
        - name: start_time
          in: query
          schema:
            type: integer
        - name: end_time
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
      responses:
        '200':
          description: List of blocks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
  /suppression/unsubscribes:
    get:
      operationId: listGlobalUnsubscribes
      summary: Twilio List Global Unsubscribes
      tags:
        - Suppressions
      parameters:
        - name: start_time
          in: query
          schema:
            type: integer
        - name: end_time
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
      responses:
        '200':
          description: List of global unsubscribes
  /stats:
    get:
      operationId: fetchGlobalStats
      summary: Twilio Fetch Global Email Stats
      description: >-
        Retrieve aggregate email statistics including requests, deliveries,
        opens, clicks, bounces, and more.
      tags:
        - Stats
      parameters:
        - name: start_date
          in: query
          required: true
          description: Start date (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          description: End date (YYYY-MM-DD)
          schema:
            type: string
            format: date
        - name: aggregated_by
          in: query
          schema:
            type: string
            enum:
              - day
              - week
              - month
      responses:
        '200':
          description: Email statistics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StatEntry'
  /validations/email:
    post:
      operationId: validateEmail
      summary: Twilio Validate an Email Address
      description: >-
        Check if an email address is valid and deliverable.
      tags:
        - Email Validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                source:
                  type: string
                  description: Source identifier for validation tracking
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidation'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use a SendGrid API key as the bearer token for authentication.
  schemas:
    SendEmailRequest:
      type: object
      required:
        - personalizations
        - from
      properties:
        personalizations:
          type: array
          items:
            $ref: '#/components/schemas/Personalization'
          minItems: 1
          maxItems: 1000
          description: Recipients and per-recipient settings
        from:
          $ref: '#/components/schemas/EmailAddress'
        reply_to:
          $ref: '#/components/schemas/EmailAddress'
        reply_to_list:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          maxItems: 1000
        subject:
          type: string
          description: Global subject line
        content:
          type: array
          items:
            type: object
            required:
              - type
              - value
            properties:
              type:
                type: string
                description: MIME type (text/plain or text/html)
              value:
                type: string
                description: Content body
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        template_id:
          type: string
          description: ID of a dynamic template to use
        headers:
          type: object
          additionalProperties:
            type: string
        categories:
          type: array
          items:
            type: string
          maxItems: 10
          description: Categories for tracking (max 10)
        send_at:
          type: integer
          description: Unix timestamp for scheduled send (up to 72 hours)
        batch_id:
          type: string
          description: Batch ID for grouping scheduled sends
        asm:
          type: object
          properties:
            group_id:
              type: integer
              description: Unsubscribe group ID
            groups_to_display:
              type: array
              items:
                type: integer
              maxItems: 25
        ip_pool_name:
          type: string
          description: Name of the IP pool for sending
        tracking_settings:
          type: object
          properties:
            click_tracking:
              type: object
              properties:
                enable:
                  type: boolean
                enable_text:
                  type: boolean
            open_tracking:
              type: object
              properties:
                enable:
                  type: boolean
                substitution_tag:
                  type: string
            subscription_tracking:
              type: object
              properties:
                enable:
                  type: boolean
    Personalization:
      type: object
      required:
        - to
      properties:
        to:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          minItems: 1
        cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        subject:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        substitutions:
          type: object
          additionalProperties:
            type: string
        dynamic_template_data:
          type: object
          description: Dynamic template handlebars data
        custom_args:
          type: object
          additionalProperties:
            type: string
        send_at:
          type: integer
    EmailAddress:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
        name:
          type: string
    Attachment:
      type: object
      required:
        - content
        - filename
      properties:
        content:
          type: string
          description: Base64 encoded attachment content
        filename:
          type: string
        type:
          type: string
          description: MIME type of the attachment
        disposition:
          type: string
          enum: [inline, attachment]
          default: attachment
        content_id:
          type: string
          description: Content ID for inline attachments
    Template:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        generation:
          type: string
          enum: [legacy, dynamic]
        updated_at:
          type: string
          format: date-time
        versions:
          type: array
          items:
            $ref: '#/components/schemas/TemplateVersion'
    TemplateVersion:
      type: object
      properties:
        id:
          type: string
          format: uuid
        template_id:
          type: string
          format: uuid
        name:
          type: string
        subject:
          type: string
        html_content:
          type: string
        plain_content:
          type: string
        active:
          type: integer
          enum: [0, 1]
        editor:
          type: string
          enum: [code, design]
        generate_plain_content:
          type: boolean
        updated_at:
          type: string
          format: date-time
    TemplateList:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/Template'
        _metadata:
          type: object
          properties:
            count:
              type: integer
    CreateTemplateVersionRequest:
      type: object
      required:
        - name
        - subject
      properties:
        name:
          type: string
          maxLength: 100
        subject:
          type: string
        html_content:
          type: string
        plain_content:
          type: string
        active:
          type: integer
          enum: [0, 1]
        editor:
          type: string
          enum: [code, design]
        generate_plain_content:
          type: boolean
          default: true
        test_data:
          type: string
          description: JSON test data for template preview
    ContactRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        address_line_1:
          type: string
        address_line_2:
          type: string
        city:
          type: string
        state_province_region:
          type: string
        postal_code:
          type: string
        country:
          type: string
        phone_number:
          type: string
        alternate_emails:
          type: array
          items:
            type: string
            format: email
          maxItems: 5
        custom_fields:
          type: object
          additionalProperties: true
    Contact:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        phone_number:
          type: string
        address_line_1:
          type: string
        address_line_2:
          type: string
        city:
          type: string
        state_province_region:
          type: string
        postal_code:
          type: string
        country:
          type: string
        alternate_emails:
          type: array
          items:
            type: string
        list_ids:
          type: array
          items:
            type: string
        custom_fields:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ContactList:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        contact_count:
          type: integer
        _metadata:
          type: object
    ContactListCollection:
      type: object
      properties:
        result:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              contact_count:
                type: integer
              _metadata:
                type: object
    CreateVerifiedSenderRequest:
      type: object
      required:
        - nickname
        - from_email
        - from_name
        - reply_to
        - reply_to_name
        - address
        - city
        - country
      properties:
        nickname:
          type: string
        from_email:
          type: string
          format: email
        from_name:
          type: string
        reply_to:
          type: string
          format: email
        reply_to_name:
          type: string
        address:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        country:
          type: string
    Bounce:
      type: object
      properties:
        email:
          type: string
          format: email
        status:
          type: string
          description: SMTP status code
        reason:
          type: string
          description: Bounce reason from the receiving server
        created:
          type: integer
          description: Unix timestamp when the bounce occurred
    Block:
      type: object
      properties:
        email:
          type: string
          format: email
        status:
          type: string
        reason:
          type: string
        created:
          type: integer
    StatEntry:
      type: object
      properties:
        date:
          type: string
          format: date
        stats:
          type: array
          items:
            type: object
            properties:
              metrics:
                type: object
                properties:
                  requests:
                    type: integer
                  delivered:
                    type: integer
                  opens:
                    type: integer
                  unique_opens:
                    type: integer
                  clicks:
                    type: integer
                  unique_clicks:
                    type: integer
                  bounces:
                    type: integer
                  bounce_drops:
                    type: integer
                  spam_reports:
                    type: integer
                  spam_report_drops:
                    type: integer
                  unsubscribes:
                    type: integer
                  unsubscribe_drops:
                    type: integer
                  invalid_emails:
                    type: integer
                  blocks:
                    type: integer
                  deferred:
                    type: integer
                  processed:
                    type: integer
    EmailValidation:
      type: object
      properties:
        result:
          type: object
          properties:
            email:
              type: string
              format: email
            verdict:
              type: string
              enum:
                - Valid
                - Risky
                - Invalid
            score:
              type: number
              minimum: 0
              maximum: 1
              description: Confidence score (0 to 1)
            local:
              type: string
              description: Local part of the email
            host:
              type: string
              description: Domain part of the email
            suggestion:
              type: string
              description: Suggested correction if applicable
            has_mx_or_a_record:
              type: boolean
            checks:
              type: object
              properties:
                domain:
                  type: object
                  properties:
                    has_valid_address_syntax:
                      type: boolean
                    has_mx_or_a_record:
                      type: boolean
                    is_suspected_disposable_address:
                      type: boolean
                local_part:
                  type: object
                  properties:
                    is_suspected_role_address:
                      type: boolean
                additional:
                  type: object
                  properties:
                    has_known_bounces:
                      type: boolean
                    has_suspected_bounces:
                      type: boolean
            ip_address:
              type: string
              description: IP address used for validation