openapi: "3.0.3"
info:
  title: Twilio SendGrid v3 API
  description: >-
    The Twilio SendGrid v3 API provides a simple, intuitive RESTful-like
    interface for sending email at scale, monitoring email engagement data
    programmatically, managing account settings, and more. This OpenAPI
    representation of the Twilio SendGrid v3 API allows you to generate helper
    libraries (in addition to the libraries officially released by Twilio
    SendGrid) and build mock servers for testing.
  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://github.com/sendgrid/sendgrid-oai/blob/main/LICENSE
  version: 1.8.1
servers:
  - url: https://https://services.acc.api.htm.nl/sendgrid
    description: The Integration Layer SendGrid API integration (Acceptance).
paths:
  /v3/mail/send:
    post:
      operationId: POST_mail-send
      summary: v3 Mail Send
      tags:
        - Mail Send
      description: |-
        The Mail Send endpoint allows you to send email over SendGrid's v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).
  
        ## Helper Libraries
  
        Twilio SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages:
  
        * [C#](https://github.com/sendgrid/sendgrid-csharp) 
        * [Go](https://github.com/sendgrid/sendgrid-go)
        * [Java](https://github.com/sendgrid/sendgrid-java)
        * [Node JS](https://github.com/sendgrid/sendgrid-nodejs)
        * [PHP](https://github.com/sendgrid/sendgrid-php)
        * [Python](https://github.com/sendgrid/sendgrid-python)
        * [Ruby](https://github.com/sendgrid/sendgrid-ruby)
  
        ## Dynamic Transactional Templates and Handlebars
  
        In order to send a dynamic template, specify the template ID with the `template_id` parameter. 
  
        To specify handlebar substitutions, define your substitutions in the request JSON with this syntax:
  
        ```
        "dynamic_template_data": {
           "guest": "Jane Doe",
           "partysize": "4",
           "english": true,
           "date": "April 1st, 2021"
        }
        ```
  
        For more information about Dynamic Transactional Templates and Handlebars, see our documentation and reference pages.
  
        * [How to send an email with Dynamic Transactional Templates
        ](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/)
        * [Using Handlebars](https://sendgrid.com/docs/for-developers/sending-email/using-handlebars/) 
  
        ## Mail Body Compression
  
        Mail body compression is available to some high volume accounts. Talk to your CSM if you are interested in this functionality. Mail body compression works by setting up a JSON payload as defined on this page, then compressing it with gzip (the gzip file can be no more than 30mb).
  
        To use mail body compression:
  
        1. Add a `Content-Encoding` header, with a value of `gzip`.  
           a. `Content-Encoding: gzip` 
        2. Send the gzip as a data-binary.  
           a. `--data-binary '@data.json.gz'
        `
  
        ## Multiple Reply-To Emails
  
        Using `reply_to_list` allows senders to include more than one recipient email address to receive reply and/or bounce messages from the recipient of the email.
  
        ### Usage Considerations
  
        * `reply_to` is mutually exclusive with `reply_to_list`. If both are used, then the API call will be rejected. 
        * The `reply_to_list` object, when used, must at least have an email parameter and may also contain a name parameter.
        * Each email address in the `reply_to_list` should be unique.
        * There is a limit of 1000 `reply_to_list` emails per mail/send request.
        * In SMTP calls, we will omit any invalid emails.
  
        ### Possible 400 Error Messages
  
        * `reply_to` is mutually exclusive with `reply_to_list`.
        * The `reply_to_list` object, when used, must at least have an email parameter and may also contain a name parameter.
        * Each email address in the `reply_to_list` should be unique.
        * There is a limit of X `reply_to` emails per mail/send request.
        * The `reply_to_list` email does not contain a valid address.
        * The `reply_to_list` email exceeds the maximum total length of X characters.
        * The `reply_to_list` email parameter is required.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                personalizations:
                  type: array
                  description: An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled. See our [Personalizations documentation](https://sendgrid.com/docs/for-developers/sending-email/personalizations/) for examples.
                  uniqueItems: false
                  maxItems: 1000
                  items:
                    type: object
                    properties:
                      from:
                        $ref: "#/components/schemas/from_email_object"
                      to:
                        $ref: "#/components/schemas/to_email_array"
                      cc:
                        type: array
                        description: An array of recipients who will receive a copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.
                        maxItems: 1000
                        items:
                          $ref: "#/components/schemas/cc_bcc_email_object"
                      bcc:
                        type: array
                        description: An array of recipients who will receive a blind carbon copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.
                        maxItems: 1000
                        items:
                          $ref: "#/components/schemas/cc_bcc_email_object"
                      subject:
                        type: string
                        description: The subject of your email. See character length requirements according to [RFC 2822](http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310).
                        minLength: 1
                      headers:
                        type: object
                        description: 'A collection of JSON key/value pairs allowing you to specify handling instructions for your email. You may not overwrite the following headers: `x-sg-id`, `x-sg-eid`, `received`, `dkim-signature`, `Content-Type`, `Content-Transfer-Encoding`, `To`, `From`, `Subject`, `Reply-To`, `CC`, `BCC`'
                      substitutions:
                        type: object
                        description: Substitutions allow you to insert data without using Dynamic Transactional Templates. This field should **not** be used in combination with a Dynamic Transactional Template, which can be identified by a `template_id` starting with `d-`. This field is a collection of key/value pairs following the pattern "substitution_tag":"value to substitute". The key/value pairs must be strings. These substitutions will apply to the text and html content of the body of your email, in addition to the `subject` and `reply-to` parameters. The total collective size of your substitutions may not exceed 10,000 bytes per personalization object.
                        maxProperties: 10000
                      dynamic_template_data:
                        type: object
                        description: Dynamic template data is available using Handlebars syntax in Dynamic Transactional Templates. This field should be used in combination with a Dynamic Transactional Template, which can be identified by a `template_id` starting with `d-`. This field is a collection of key/value pairs following the pattern "variable_name":"value to insert".
                      custom_args:
                        type: object
                        description: Values that are specific to this personalization that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This field may not exceed 10,000 bytes.
                        maxProperties: 10000
                      send_at:
                        type: integer
                        description: A unix timestamp allowing you to specify when your email should be delivered. Scheduling delivery more than 72 hours in advance is forbidden.
                    required:
                      - to
                from:
                  $ref: "#/components/schemas/from_email_object"
                reply_to:
                  $ref: "#/components/schemas/reply_to_email_object"
                reply_to_list:
                  type: array
                  description: An array of recipients who will receive replies and/or bounces. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name. You can either choose to use “reply_to” field or “reply_to_list” but not both.
                  uniqueItems: true
                  maxItems: 1000
                  items:
                    type: object
                    properties:
                      email:
                        type: string
                        description: The email address where any replies or bounces will be returned.
                        format: email
                      name:
                        type: string
                        description: A name or title associated with the `reply_to_list` email address.
                    required:
                      - email
                subject:
                  type: string
                  description: The global or 'message level' subject of your email. This may be overridden by subject lines set in personalizations.
                  minLength: 1
                content:
                  type: array
                  description: An array where you can specify the content of your email. You can include multiple [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of content, but you must specify at least one MIME type. To include more than one MIME type, add another object to the array containing the `type` and `value` parameters.
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        description: The MIME type of the content you are including in your email (e.g., `“text/plain”` or `“text/html”`).
                        minLength: 1
                      value:
                        type: string
                        description: The actual content of the specified MIME type that you are including in your email.
                        minLength: 1
                    required:
                      - type
                      - value
                attachments:
                  type: array
                  description: An array of objects where you can specify any attachments you want to include.
                  items:
                    type: object
                    properties:
                      content:
                        type: string
                        description: The Base64 encoded content of the attachment.
                        minLength: 1
                      type:
                        type: string
                        description: The MIME type of the content you are attaching (e.g., `“text/plain”` or `“text/html”`).
                        minLength: 1
                      filename:
                        type: string
                        description: The attachment's filename.
                      disposition:
                        type: string
                        default: attachment
                        description: The attachment's content-disposition, specifying how you would like the attachment to be displayed. For example, `“inline”` results in the attached file are displayed automatically within the message while `“attachment”` results in the attached file require some action to be taken before it is displayed, such as opening or downloading the file.
                        enum:
                          - inline
                          - attachment
                      content_id:
                        type: string
                        description: The attachment's content ID. This is used when the disposition is set to `“inline”` and the attachment is an image, allowing the file to be displayed within the body of your email.
                    required:
                      - content
                      - filename
                template_id:
                  type: string
                  description: An email template ID. A template that contains a subject and content — either text or html — will override any subject and content values specified at the personalizations or message level.
                headers:
                  description: An object containing key/value pairs of header names and the value to substitute for them. The key/value pairs must be strings. You must ensure these are properly encoded if they contain unicode characters. These headers cannot be one of the reserved headers.
                  type: object
                categories:
                  type: array
                  description: 'An array of category names for this message. Each category name may not exceed 255 characters. '
                  uniqueItems: true
                  maxItems: 10
                  items:
                    type: string
                    maxLength: 255
                custom_args:
                  description: Values that are specific to the entire send that will be carried along with the email and its activity data.  Key/value pairs must be strings. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by `custom_args` set at the personalizations level. Total `custom_args` size may not exceed 10,000 bytes.
                  type: string
                send_at:
                  type: integer
                  description: A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the `send_at` parameter set at the personalizations level. Delivery cannot be scheduled more than 72 hours in advance. If you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid peak times — for example, scheduling at 10:53 — can result in lower deferral rates due to the reduced traffic during off-peak times.
                batch_id:
                  type: string
                  description: An ID representing a batch of emails to be sent at the same time. Including a `batch_id` in your request allows you include this email in that batch. It also enables you to cancel or pause the delivery of that batch. For more information, see the [Cancel Scheduled Sends API](https://sendgrid.com/docs/api-reference/).
                asm:
                  type: object
                  description: An object allowing you to specify how to handle unsubscribes.
                  properties:
                    group_id:
                      type: integer
                      description: The unsubscribe group to associate with this email.
                    groups_to_display:
                      type: array
                      description: An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page.
                      maxItems: 25
                      items:
                        type: integer
                  required:
                    - group_id
                ip_pool_name:
                  type: string
                  description: The IP Pool that you would like to send this email from.
                  minLength: 2
                  maxLength: 64
                mail_settings:
                  type: object
                  description: A collection of different mail settings that you can use to specify how you would like this email to be handled.
                  properties:
                    bypass_list_management:
                      type: object
                      description: Allows you to bypass all unsubscribe groups and suppressions to ensure that the email is delivered to every single recipient. This should only be used in emergencies when it is absolutely necessary that every recipient receives your email. This filter cannot be combined with any other bypass filters. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                    bypass_spam_management:
                      type: object
                      description: Allows you to bypass the spam report list to ensure that the email is delivered to recipients. Bounce and unsubscribe lists will still be checked; addresses on these other lists will not receive the message. This filter cannot be combined with the `bypass_list_management` filter. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                    bypass_bounce_management:
                      type: object
                      description: Allows you to bypass the bounce list to ensure that the email is delivered to recipients. Spam report and unsubscribe lists will still be checked; addresses on these other lists will not receive the message. This filter cannot be combined with the `bypass_list_management` filter. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                    bypass_unsubscribe_management:
                      type: object
                      description: Allows you to bypass the global unsubscribe list to ensure that the email is delivered to recipients. Bounce and spam report lists will still be checked; addresses on these other lists will not receive the message. This filter applies only to global unsubscribes and will not bypass group unsubscribes. This filter cannot be combined with the `bypass_list_management` filter. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                    footer:
                      type: object
                      description: The default footer that you would like included on every email.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                        text:
                          type: string
                          description: The plain text content of your footer.
                        html:
                          type: string
                          description: The HTML content of your footer.
                    sandbox_mode:
                      type: object
                      description: Sandbox Mode allows you to send a test email to ensure that your request body is valid and formatted correctly.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                tracking_settings:
                  type: object
                  description: Settings to determine how you would like to track the metrics of how your recipients interact with your email.
                  properties:
                    click_tracking:
                      type: object
                      description: Allows you to track if a recipient clicked a link in your email.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                        enable_text:
                          type: boolean
                          description: Indicates if this setting should be included in the `text/plain` portion of your email.
                    open_tracking:
                      type: object
                      description: Allows you to track if the email was opened by including a single pixel image in the body of the content. When the pixel is loaded, Twilio SendGrid can log that the email was opened.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                        substitution_tag:
                          type: string
                          description: Allows you to specify a substitution tag that you can insert in the body of your email at a location that you desire. This tag will be replaced by the open tracking pixel.
                    subscription_tracking:
                      type: object
                      description: Allows you to insert a subscription management link at the bottom of the text and HTML bodies of your email. If you would like to specify the location of the link within your email, you may use the `substitution_tag`.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                        text:
                          type: string
                          description: Text to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>
                        html:
                          type: string
                          description: HTML to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>
                        substitution_tag:
                          type: string
                          description: "A tag that will be replaced with the unsubscribe URL. for example: `[unsubscribe_url]`. If this parameter is used, it will override both the `text` and `html` parameters. The URL of the link will be placed at the substitution tag's location with no additional formatting."
                    ganalytics:
                      type: object
                      description: Allows you to enable tracking provided by Google Analytics.
                      properties:
                        enable:
                          type: boolean
                          description: Indicates if this setting is enabled.
                        utm_source:
                          type: string
                          description: Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)
                        utm_medium:
                          type: string
                          description: Name of the marketing medium. (e.g. Email)
                        utm_term:
                          type: string
                          description: Used to identify any paid keywords.
                        utm_content:
                          type: string
                          description: Used to differentiate your campaign from advertisements.
                        utm_campaign:
                          type: string
                          description: The name of the campaign.
              required:
                - personalizations
                - from
                - subject
                - content
              example:
                personalizations:
                  - to:
                      - email: john_doe@example.com
                        name: John Doe
                      - email: julia_doe@example.com
                        name: Julia Doe
                    cc:
                      - email: jane_doe@example.com
                        name: Jane Doe
                    bcc:
                      - email: james_doe@example.com
                        name: Jim Doe
                  - from:
                      email: sales@example.com
                      name: Example Sales Team
                    to:
                      - email: janice_doe@example.com
                        name: Janice Doe
                    bcc:
                      - email: jordan_doe@example.com
                        name: Jordan Doe
                from:
                  email: orders@example.com
                  name: Example Order Confirmation
                reply_to:
                  email: customer_service@example.com
                  name: Example Customer Service Team
                subject: Your Example Order Confirmation
                content:
                  - type: text/html
                    value: <p>Hello from Twilio SendGrid!</p><p>Sending with the email service trusted by developers and marketers for <strong>time-savings</strong>, <strong>scalability</strong>, and <strong>delivery expertise</strong>.</p><p>%open-track%</p>
                attachments:
                  - content: PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==
                    filename: index.html
                    type: text/html
                    disposition: attachment
                categories:
                  - cake
                  - pie
                  - baking
                send_at: 1617260400
                batch_id: AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl
                asm:
                  group_id: 12345
                  groups_to_display:
                    - 12345
                ip_pool_name: transactional email
                mail_settings:
                  bypass_list_management:
                    enable: false
                  footer:
                    enable: false
                  sandbox_mode:
                    enable: false
                tracking_settings:
                  click_tracking:
                    enable: true
                    enable_text: false
                  open_tracking:
                    enable: true
                    substitution_tag: '%open-track%'
                  subscription_tracking:
                    enable: false
      responses:
        '202':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/global_error_response_schema"
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/global_error_response_schema"
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/global_error_response_schema"
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/global_error_response_schema"
        '413':
          description: ''
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/global_error_response_schema"
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/global_error_response_schema"
      security:
        - Authorization: []
components:
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        The API key used to authenticate with the SendGrid v3 API. You can find
        your API key in the [Twilio SendGrid UI](https://app.sendgrid.com/settings/api_keys).
        For more information, see our [API Key documentation](https://sendgrid.com/docs/ui/account-and-settings/api-keys/).
  schemas:
    from_email_object:
      title: From Email Object
      type: object
      properties:
        email:
          type: string
          format: email
          description: The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account.
        name:
          type: string
          description: A name or title associated with the sending email address.
      required:
      - email
      example:
        email: jane_doe@example.com
        name: Jane Doe
    to_email_array:
      title: To Email Array
      type: array
      items:
        type: object
        properties:
          email:
            type: string
            format: email
            description: The intended recipient's email address.
          name:
            type: string
            description: The intended recipient's name.
        required:
        - email
      example:
      - email: john_doe@example.com
        name: John Doe
    cc_bcc_email_object:
      title: CC BCC Email Object
      type: object
      properties:
        email:
          type: string
          format: email
          description: The intended recipient's email address.
        name:
          type: string
          description: The intended recipient's name.
      required:
      - email
      example:
        email: jane_doe@example.com
        name: Jane Doe
    reply_to_email_object:
      title: Reply_to Email Object
      type: object
      properties:
        email:
          type: string
          format: email
          description: The email address where any replies or bounces will be returned.
        name:
          type: string
          description: A name or title associated with the `reply_to` email address.
      required:
      - email
      example:
        email: jane_doe@example.com
        name: Jane Doe
    global_error_response_schema:
      title: Global Error Response Schema
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: the error message
              field:
                description: the field that generated the error
                nullable: true
                type: string
              help:
                type: object
                description: helper text or docs for troubleshooting
            required:
            - message
        id:
          type: string
      example:
        errors:
        - field: field_name
          message: error message
