triggerdotdev--trigger.dev/generated-integrations/sendgrid/docs/mail-send.mdx

---
title: Mail Send
sidebarTitle: Mail Send
description: Send email to one or more recipients with personalization
---
    
## Params
    
<ParamField path="key" type="string" required={true}>
  A unique string. Please see the [Keys and Resumability](/guides/resumability)
  doc for more info.
</ParamField><ParamField path="params" type="object" required={true}>
   Mail Send Input
<Expandable title="properties" defaultOpen={true}><ParamField path="personalizations" type="array" required={true}>
   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.
<Expandable title="items" defaultOpen={false}><ParamField path="personalizations[n]" type="object" required={true}>
<Expandable title="properties" defaultOpen={false}><ParamField path="to" type="array" required={true}>
   To Email Array
<Expandable title="items" defaultOpen={false}><ParamField path="to[n]" type="object" required={true}>
<Expandable title="properties" defaultOpen={false}><ParamField path="email" type="string" required={true}>
   The intended recipient's email address.
</ParamField><ParamField path="name" type="string" required={false}>
   The intended recipient's name.
</ParamField></Expandable></ParamField></Expandable></ParamField><ParamField path="from" type="object" required={false}>
   From Email Object
<Expandable title="properties" defaultOpen={false}><ParamField path="email" type="string" required={true}>
   The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account.
</ParamField><ParamField path="name" type="string" required={false}>
   A name or title associated with the sending email address.
</ParamField></Expandable></ParamField><ParamField path="cc" type="array" required={false}>
   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.
<Expandable title="items" defaultOpen={false}><ParamField path="cc[n]" type="object" required={false}>
   CC BCC Email Object
<Expandable title="properties" defaultOpen={false}><ParamField path="email" type="string" required={true}>
   The intended recipient's email address.
</ParamField><ParamField path="name" type="string" required={false}>
   The intended recipient's name.
</ParamField></Expandable></ParamField></Expandable></ParamField><ParamField path="bcc" type="array" required={false}>
   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.
<Expandable title="items" defaultOpen={false}><ParamField path="bcc[n]" type="object" required={false}>
   CC BCC Email Object
<Expandable title="properties" defaultOpen={false}><ParamField path="email" type="string" required={true}>
   The intended recipient's email address.
</ParamField><ParamField path="name" type="string" required={false}>
   The intended recipient's name.
</ParamField></Expandable></ParamField></Expandable></ParamField><ParamField path="subject" type="string" required={false}>
   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).
</ParamField><ParamField path="headers" type="object" required={false}>
   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`
</ParamField><ParamField path="substitutions" type="object" required={false}>
   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.
</ParamField><ParamField path="dynamic_template_data" type="object" required={false}>
   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".
</ParamField><ParamField path="custom_args" type="object" required={false}>
   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.
</ParamField><ParamField path="send_at" type="integer" required={false}>
   A unix timestamp allowing you to specify when your email should be delivered. Scheduling delivery more than 72 hours in advance is forbidden.
</ParamField></Expandable></ParamField></Expandable></ParamField><ParamField path="from" type="object" required={true}>
   From Email Object
<Expandable title="properties" defaultOpen={false}><ParamField path="email" type="string" required={true}>
   The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account.
</ParamField><ParamField path="name" type="string" required={false}>
   A name or title associated with the sending email address.
</ParamField></Expandable></ParamField><ParamField path="subject" type="string" required={true}>
   The global or 'message level' subject of your email. This may be overridden by subject lines set in personalizations.
</ParamField><ParamField path="content" type="array" required={true}>
   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.
<Expandable title="items" defaultOpen={false}><ParamField path="content[n]" type="object" required={true}>
<Expandable title="properties" defaultOpen={false}><ParamField path="type" type="string" required={true}>
   The MIME type of the content you are including in your email (e.g., `“text/plain”` or `“text/html”`).
</ParamField><ParamField path="value" type="string" required={true}>
   The actual content of the specified MIME type that you are including in your email.
</ParamField></Expandable></ParamField></Expandable></ParamField><ParamField path="reply_to" type="object" required={false}>
   Reply_to Email Object
<Expandable title="properties" defaultOpen={false}><ParamField path="email" type="string" required={true}>
   The email address where any replies or bounces will be returned.
</ParamField><ParamField path="name" type="string" required={false}>
   A name or title associated with the `reply_to` email address.
</ParamField></Expandable></ParamField><ParamField path="reply_to_list" type="array" required={false}>
   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.
<Expandable title="items" defaultOpen={false}><ParamField path="reply_to_list[n]" type="object" required={false}>
<Expandable title="properties" defaultOpen={false}><ParamField path="email" type="string" required={true}>
   The email address where any replies or bounces will be returned.
</ParamField><ParamField path="name" type="string" required={false}>
   A name or title associated with the `reply_to_list` email address.
</ParamField></Expandable></ParamField></Expandable></ParamField><ParamField path="attachments" type="array" required={false}>
   An array of objects where you can specify any attachments you want to include.
<Expandable title="items" defaultOpen={false}><ParamField path="attachments[n]" type="object" required={false}>
<Expandable title="properties" defaultOpen={false}><ParamField path="content" type="string" required={true}>
   The Base64 encoded content of the attachment.
</ParamField><ParamField path="filename" type="string" required={true}>
   The attachment's filename.
</ParamField><ParamField path="type" type="string" required={false}>
   The MIME type of the content you are attaching (e.g., `“text/plain”` or `“text/html”`).
</ParamField><ParamField path="disposition" type="string" required={false}>
   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.
</ParamField><ParamField path="content_id" type="string" required={false}>
   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.
</ParamField></Expandable></ParamField></Expandable></ParamField><ParamField path="template_id" type="string" required={false}>
   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.
</ParamField><ParamField path="headers" type="object" required={false}>
   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.
</ParamField><ParamField path="categories" type="array" required={false}>
   An array of category names for this message. Each category name may not exceed 255 characters. 
<Expandable title="items" defaultOpen={false}><ParamField path="categories[n]" type="string" required={false}>
</ParamField></Expandable></ParamField><ParamField path="custom_args" type="string" required={false}>
   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.
</ParamField><ParamField path="send_at" type="integer" required={false}>
   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.
</ParamField><ParamField path="batch_id" type="string" required={false}>
   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/).
</ParamField><ParamField path="asm" type="object" required={false}>
   An object allowing you to specify how to handle unsubscribes.
<Expandable title="properties" defaultOpen={false}><ParamField path="group_id" type="integer" required={true}>
   The unsubscribe group to associate with this email.
</ParamField><ParamField path="groups_to_display" type="array" required={false}>
   An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page.
<Expandable title="items" defaultOpen={false}><ParamField path="groups_to_display[n]" type="integer" required={false}>
</ParamField></Expandable></ParamField></Expandable></ParamField><ParamField path="ip_pool_name" type="string" required={false}>
   The IP Pool that you would like to send this email from.
</ParamField><ParamField path="mail_settings" type="object" required={false}>
   A collection of different mail settings that you can use to specify how you would like this email to be handled.
<Expandable title="properties" defaultOpen={false}><ParamField path="bypass_list_management" type="object" required={false}>
   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.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField></Expandable></ParamField><ParamField path="bypass_spam_management" type="object" required={false}>
   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.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField></Expandable></ParamField><ParamField path="bypass_bounce_management" type="object" required={false}>
   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.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField></Expandable></ParamField><ParamField path="bypass_unsubscribe_management" type="object" required={false}>
   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.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField></Expandable></ParamField><ParamField path="footer" type="object" required={false}>
   The default footer that you would like included on every email.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField><ParamField path="text" type="string" required={false}>
   The plain text content of your footer.
</ParamField><ParamField path="html" type="string" required={false}>
   The HTML content of your footer.
</ParamField></Expandable></ParamField><ParamField path="sandbox_mode" type="object" required={false}>
   Sandbox Mode allows you to send a test email to ensure that your request body is valid and formatted correctly.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField></Expandable></ParamField></Expandable></ParamField><ParamField path="tracking_settings" type="object" required={false}>
   Settings to determine how you would like to track the metrics of how your recipients interact with your email.
<Expandable title="properties" defaultOpen={false}><ParamField path="click_tracking" type="object" required={false}>
   Allows you to track if a recipient clicked a link in your email.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField><ParamField path="enable_text" type="boolean" required={false}>
   Indicates if this setting should be included in the `text/plain` portion of your email.
</ParamField></Expandable></ParamField><ParamField path="open_tracking" type="object" required={false}>
   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.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField><ParamField path="substitution_tag" type="string" required={false}>
   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.
</ParamField></Expandable></ParamField><ParamField path="subscription_tracking" type="object" required={false}>
   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`.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField><ParamField path="text" type="string" required={false}>
   Text to be appended to the email with the subscription tracking link. You may control where the link is by using the tag &lt;% %&gt;
</ParamField><ParamField path="html" type="string" required={false}>
   HTML to be appended to the email with the subscription tracking link. You may control where the link is by using the tag &lt;% %&gt;
</ParamField><ParamField path="substitution_tag" type="string" required={false}>
   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.
</ParamField></Expandable></ParamField><ParamField path="ganalytics" type="object" required={false}>
   Allows you to enable tracking provided by Google Analytics.
<Expandable title="properties" defaultOpen={false}><ParamField path="enable" type="boolean" required={false}>
   Indicates if this setting is enabled.
</ParamField><ParamField path="utm_source" type="string" required={false}>
   Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)
</ParamField><ParamField path="utm_medium" type="string" required={false}>
   Name of the marketing medium. (e.g. Email)
</ParamField><ParamField path="utm_term" type="string" required={false}>
   Used to identify any paid keywords.
</ParamField><ParamField path="utm_content" type="string" required={false}>
   Used to differentiate your campaign from advertisements.
</ParamField><ParamField path="utm_campaign" type="string" required={false}>
   The name of the campaign.
</ParamField></Expandable></ParamField></Expandable></ParamField></Expandable></ParamField>