{"note":"OpenAPI conversion -- returning structured metadata","name":"sendgrid-mail","description":"Twilio SendGrid Mail API","version":"1.0.0","base_url":"https://api.sendgrid.com","endpoints":3,"raw":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Twilio SendGrid Mail API\n@base https://api.sendgrid.com\n@version 1.0.0\n@auth Bearer bearer\n@endpoints 3\n@toc mail(3)\n\n@endpoint POST /v3/mail/batch\n@desc Create a batch ID.\n@optional {on-behalf-of: str # Use the `on-behalf-of` header to make API calls for a particular Subuser through the parent account. You can use this header to automate bulk updates or to administer a Subuser without changing the authentication in your code. You will use the parent account's API key when using this header.}\n@returns(201) {batch_id: str} # Batch ID success response.\n@errors {400: Batch ID bad response., 401: Batch ID unauthorized response., 403: Batch ID forbidden response., 404: Batch ID not found response., 405: Get batch ID method not allowed response., 500: Get batch ID internal server error response.}\n\n@endpoint GET /v3/mail/batch/{batch_id}\n@desc Validate a batch ID.\n@optional {on-behalf-of: str # Use the `on-behalf-of` header to make API calls for a particular Subuser through the parent account. You can use this header to automate bulk updates or to administer a Subuser without changing the authentication in your code. You will use the parent account's API key when using this header.}\n@returns(200) {batch_id: str} # Batch ID success response.\n@errors {400: Batch ID bad response., 401: Batch ID unauthorized response., 403: Batch ID forbidden response., 405: Get batch ID method not allowed response., 500: Get batch ID internal server error response.}\n\n@endpoint POST /v3/mail/send\n@desc Send Email with Twilio SendGrid.\n@required {personalizations: [map{from: map, to!: [map], cc: [map], bcc: [map], subject: str, headers: map, substitutions: map, dynamic_template_data: map, custom_args: map, send_at: int}] # An array of messages and their metadata. Each object within the `personalizations` array can be thought of as a mail envelope—it defines who should receive an individual message and how that message should be handled. See [**Personalizations**](https://sendgrid.com/docs/for-developers/sending-email/personalizations/) for more information., from: map{email!: str(email), name: str}}\n@optional {Content-Encoding: str # Use this header when sending a gzip compressed mail body. Mail body compression is available to some high volume accounts. Submit a [request to support](https://support.sendgrid.com/hc/en-us) to have gzip enabled on your account., reply_to: map{email!: str(email), name: str}, reply_to_list: [map{email!: str(email), name: str}] # An array of recipients to whom replies will be sent. Each object in this array must contain a recipient's email address. Each object in the array may optionally contain a recipient's name. You can use either the `reply_to` property or `reply_to_list` property but not both., subject: str # The global or _message level_ subject of your email. Subject lines set in personalizations objects will override this global subject line. See line length limits specified in [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822#section-2.1.1) for guidance on subject line character limits., content: [map{type!: str, value!: str}] # An array of objects, each containing a message body's content and [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types). You must specify at least one MIME type and may include multiple. To include more than one MIME type, add an object for each type to the array., attachments: [map{content!: str, type: str, filename!: str, disposition: str, content_id: str}] # An array of objects where you can define any attachments to be included with the message. Each object contains a `content` property, which must be a Base64 encoded string of the attachment itself, and `type`, `filename`, `disposition`, and `content_id` properties that tell SendGrid how to handle the attachment., template_id: str # 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. If a template ID begins with `d-`, it is a dynamic template and will work with the `dynamic_template_data` property. If the template ID does not begin with `d-`, it is a standard SendGrid template and will work with the `substitutions` property. See [**How to Send an Email with Dynamic Templates**](https://docs.sendgrid.com/ui/sending-email/how-to-send-an-email-with-dynamic-templates) for more information about working with templates., headers: map # A collection of JSON property name and property value pairs allowing you to specify handling instructions for your email. You may not override the following headers: `x-sg-id`, `x-sg-eid`, `received`, `dkim-signature`, `Content-Type`, `Content-Transfer-Encoding`, `To`, `From`, `Subject`, `Reply-To`, `CC`, `BCC`., categories: [str] # An array of category names assigned to this message. Categories allow you to group messages by categories you define. Categories should be used sparingly to create general groups that are relevant to you. Categories are not meant to be used to track individual mail sends. For more granular categorization and tracking, use the `custom_args` property. A category name cannot exceed 255 characters. See [**Working with Categories**](https://docs.sendgrid.com/for-developers/sending-email/categories) for more information., custom_args: str # Values that are specific to the entire send 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 assigned to this property 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., send_at: int # A [unix timestamp](https://en.wikipedia.org/wiki/Unix_time) allowing you to specify when your email should be sent. A send cannot be scheduled more than 72 hours in advance. This property may be overridden by the `send_at` property set at the personalizations level., batch_id: str # An ID representing a batch of emails to be sent at the same time. Including a `batch_id` in your request allows you to include this email in that batch. It also enables you to cancel or pause the delivery of that batch. See the [Scheduled Sends API](https://sendgrid.com/docs/api-reference/) for more information about scheduling your email., asm: map{group_id!: int, groups_to_display: [int]} # An object allowing you to specify how to handle unsubscribes. With SendGrid, an unsubscribe is the action an email recipient takes when they opt-out of receiving your messages. A suppression is the action you take as a sender to filter or suppress an unsubscribed address from your email send. From the perspective of the recipient, your suppression is the result of their unsubscribe. See [**Suppression Groups**](https://www.twilio.com/docs/sendgrid/api-reference/suppressions-unsubscribe-groups/create-a-new-suppression-group) for more information., ip_pool_name: str # The IP Pool that you would like to send this email from. IP Pools allow you to group your dedicated Twilio SendGrid IP addresses in order to have more control over your deliverability. See [**IP Pools**](https://docs.sendgrid.com/ui/account-and-settings/ip-pools) for more information., mail_settings: map{bypass_list_management: map, bypass_spam_management: map, bypass_bounce_management: map, bypass_unsubscribe_management: map, footer: map, sandbox_mode: map} # A collection of different mail settings that you can use to specify how you would like this email to be handled. Mail settings provide extra functionality to your mail send. See [**Mail Settings**](https://docs.sendgrid.com/ui/account-and-settings/mail) for more information., tracking_settings: map{click_tracking: map, open_tracking: map, subscription_tracking: map, ganalytics: map} # Settings to determine how you would like to track the metrics of how your recipients interact with your email. See [**Tracking Settings**](https://docs.sendgrid.com/ui/account-and-settings/tracking) for more information.}\n@returns(202) Accepted\n@errors {400: Mail Send bad response., 401: Mail Send unauthorized response., 403: Mail Send forbidden response., 404: Mail Send not found response., 405: Mail Send method not allowed response., 413: Mail Send content too large response., 500: Mail send internal server error response.}\n@example_request {\"personalizations\":[{\"to\":[{\"email\":\"alex@example.com\",\"name\":\"Alex\"},{\"email\":\"bola@example.com\",\"name\":\"Bola\"}],\"dynamic_template_data\":{\"subject\":\"Hello, Alex\",\"customer_name\":\"Alex\",\"confirmation_number\":\"123abc456def789hij0\"}}],\"from\":{\"email\":\"orders@example.com\",\"name\":\"Example Order Confirmation\"},\"reply_to\":{\"email\":\"customer_service@example.com\",\"name\":\"Example Customer Service Team\"},\"attachments\":[{\"content\":\"PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==\",\"filename\":\"index.html\",\"type\":\"text/html\",\"disposition\":\"attachment\"}],\"template_id\":\"d-123abc456def789hij0klm123nop456qrs789tuv0xyz\",\"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}}}\n\n@end\n"}