openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid IP Warmup API
  summary: The Twilio SendGrid IP Warm Up API allows you to gradually increasing the
    volume of mail sent with a dedicated IP address according to a predetermined schedule.
  description: 'The Twilio SendGrid IP Warm Up API allows you to gradually increasing
    the volume of mail sent with a dedicated IP address according to a predetermined
    schedule. This gradual process helps to establish a reputation with ISPs (Internet
    Service Providers) as a legitimate email sender.


    SendGrid can automatically warm up dedicated IP addresses by limiting the amount
    of mail that can be sent through them per hour. The limit is determined by how
    long the IP address has been warming up.


    See the [warmup schedule](https://sendgrid.com/docs/ui/sending-email/warming-up-an-ip-address/#automated-ip-warmup-hourly-send-schedule)
    to learn how SendGrid limits your email traffic for IPs in warmup.


    You can also choose to use Twilio SendGrid''s automated IP warmup for any of your
    IPs from the **IP Addresses** settings menu in the [Twilio SendGrid application
    user interface](https://app.sendgrid.com/settings/ip_addresses).'
  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: ip_warmup
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/ips/warmup:
    post:
      operationId: WarmUpIp
      summary: Start warming up an IP address
      tags:
      - IP Warmup
      description: '**This endpoint allows you to put an IP address into warmup mode.**'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ip:
                  type: string
                  description: The IP address that you want to begin warming up.
              example:
                ip: 0.0.0.0
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpWarmup200'
              examples:
                response:
                  value:
                  - ip: 0.0.0.0
                    start_date: 1409616000
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: The errors that were encountered.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          nullable: true
                        message:
                          type: string
                          description: A message explaining why the IP couldn't entered
                            into warmup mode.
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: resource not found
    get:
      operationId: ListWarmUpIp
      summary: Retrieve all IPs currently in warmup
      tags:
      - IP Warmup
      description: '**This endpoint allows you to retrieve all of your IP addresses
        that are currently warming up.**'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpWarmup200'
              examples:
                response:
                  value:
                  - ip: 0.0.0.0
                    start_date: 1409616000
  /v3/ips/warmup/{ip_address}:
    parameters:
    - name: ip_address
      in: path
      description: The IP address that you want to retrieve the warmup status for.
      required: true
      schema:
        type: string
    get:
      operationId: GetWarmUpIp
      summary: Retrieve the warmup status for a specific IP address
      tags:
      - IP Warmup
      description: '**This endpoint allows you to retrieve the warmup status for a
        specific IP address.**


        You can retrieve all of your warming IPs using the "Retrieve all IPs currently
        in warmup" endpoint.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpWarmup200'
              examples:
                response:
                  value:
                  - ip: 0.0.0.0
                    start_date: 1409616000
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: The errors that were encountered.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          nullable: true
                        message:
                          type: string
                          description: A message explaining why the warmup status
                            could not be retrieved.
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: resource not found
    delete:
      operationId: StopIpWarmUp
      summary: Stop warming up an IP address
      tags:
      - IP Warmup
      description: "**This endpoint allows you to remove an IP address from warmup\
        \ mode.**\n\nYour request will return a 204 status code if the specified IP\
        \ was successfully removed from warmup mode. To retrieve details of the IP\u2019\
        s warmup status *before* removing it from warmup mode, call the  \"Retrieve\
        \ the warmpup status for a specific IP address\" endpoint."
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: The errors that were encountered.
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          nullable: true
                        message:
                          type: string
                          description: A message explaining why the IP couldn't be
                            removed from warmup.
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: resource not found
components:
  schemas:
    IpWarmup200:
      title: 'IP Warmup: IP'
      type: array
      items:
        type: object
        properties:
          ip:
            type: string
            description: The IP address.
          start_date:
            type: integer
            description: A Unix timestamp indicating when the IP address entered warmup
              mode.
        required:
        - ip
        - start_date
      example:
      - ip: 0.0.0.0
        start_date: 1409616000
  responses: {}
  parameters: {}
  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: IP Warmup
  description: Twilio SendGrid IP Warmup API
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid