> For the complete documentation index, see [llms.txt](https://docs.mailtrap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mailtrap.io/developers/email-sandbox/send-test-emails/batch-send-email-including-templates.md).

# Batch send email (including templates)

Batch send email (text, html, text\&html, templates). Please note that the endpoint will return a 200-level http status, even when sending for individual messages may fail. Users of this endpoint should check the success and errors for each message in the response (the results are ordered the same as the original messages - `requests`). Please note that the endpoint accepts up to 500 messages per API call, and up to 50 MB payload size, including attachments.

```json
{"openapi":"3.1.0","info":{"title":"Email Sandbox","version":"2.0.0"},"tags":[{"name":"Test Emails","description":"Test Emails"}],"servers":[{"description":"Mailtrap Sandbox Send API. Error bodies use `success: false` and an `errors` array (same family as\n`send.api` / `bulk.api`), not the `mailtrap.io` account shape (`error` / string `errors`).\nUse a normal HTTP client `User-Agent` (e.g. `curl`); bare requests may be blocked by edge protection.\n","url":"https://sandbox.api.mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"BatchEmail":{"title":"BatchEmail","type":"object","properties":{"base":{"title":"BatchEmailBase","description":"General properties of all emails in the batch. Each of them can be overridden in `requests` for individual emails.","allOf":[{"$ref":"#/components/schemas/EmailSender"},{"$ref":"#/components/schemas/EmailReplyTo"},{"$ref":"#/components/schemas/EmailSubject"},{"$ref":"#/components/schemas/EmailText"},{"$ref":"#/components/schemas/EmailHtml"},{"$ref":"#/components/schemas/EmailAttachments"},{"$ref":"#/components/schemas/EmailSendingHeaders"},{"$ref":"#/components/schemas/EmailCategory"},{"$ref":"#/components/schemas/EmailCustomVariables"},{"$ref":"#/components/schemas/TemplateUuid"},{"$ref":"#/components/schemas/TemplateVariables"}]},"requests":{"description":"The list of emails. Each of them requires recipients (one of `to`, `cc`, or `bcc`). Each email inherits properties from `base` but can override them.","type":"array","items":{"title":"BatchEmailRequests","allOf":[{"$ref":"#/components/schemas/EmailSender"},{"$ref":"#/components/schemas/EmailRecipients"},{"$ref":"#/components/schemas/EmailReplyTo"},{"$ref":"#/components/schemas/EmailSubject"},{"$ref":"#/components/schemas/EmailText"},{"$ref":"#/components/schemas/EmailHtml"},{"$ref":"#/components/schemas/EmailAttachments"},{"$ref":"#/components/schemas/EmailSendingHeaders"},{"$ref":"#/components/schemas/EmailCategory"},{"$ref":"#/components/schemas/EmailCustomVariables"},{"$ref":"#/components/schemas/TemplateUuid"},{"$ref":"#/components/schemas/TemplateVariables"}]}}},"required":["requests"]},"EmailSender":{"type":"object","properties":{"from":{"$ref":"#/components/schemas/Address"}}},"Address":{"title":"Address","type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}},"EmailReplyTo":{"type":"object","properties":{"reply_to":{"$ref":"#/components/schemas/Address"}}},"EmailSubject":{"type":"object","properties":{"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}}},"EmailText":{"type":"object","properties":{"text":{"type":"string","description":"Text version of the body of the email. Can be used along with `html` to create a fallback for non-html clients. Required in the absence of `html`.","minLength":1}}},"EmailHtml":{"type":"object","properties":{"html":{"type":"string","description":"HTML version of the body of the email. Can be used along with `text` to create a fallback for non-html clients. Required in the absence of `text`.","minLength":1}}},"EmailAttachments":{"type":"object","properties":{"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"]}}}},"EmailSendingHeaders":{"type":"object","properties":{"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. `Content-Transfer-Encoding` header will be ignored and replaced with `quoted-printable`.","type":"object","additionalProperties":{"type":"string"}}}},"EmailCategory":{"type":"object","properties":{"category":{"type":"string","maxLength":255}}},"EmailCustomVariables":{"type":"object","properties":{"custom_variables":{"description":"Values that are specific to the entire send that will be carried along with the email and its activity data. Total size of custom variables in JSON form must not exceed 1000 bytes.","type":"object","additionalProperties":{"type":"string"}}}},"TemplateUuid":{"type":"object","properties":{"template_uuid":{"type":"string","minLength":1,"format":"uuid","description":"UUID of email template.\nSubject, text and html will be generated from template using optional template_variables.\nIf template_uuid is provided then subject, text and html params are forbidden."}}},"TemplateVariables":{"type":"object","properties":{"template_variables":{"type":"object","description":"Optional template variables that will be used to generate actual subject, text and html from email template"}}},"EmailRecipients":{"type":"object","properties":{"to":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"cc":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Address"}},"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/Address"}}}},"BatchSentResponse":{"title":"BatchSentResponse","type":"object","properties":{"success":{"description":"Indicates whether the was a general error. When false, you should check the `errors` array for information. When true, you should check individual message `responses` and their `success`.\n","type":"boolean"},"responses":{"description":"Individual message responses. The results are ordered the same as the original messages - `requests`.","type":"array","items":{"type":"object","properties":{"success":{"type":"boolean"},"message_ids":{"description":"An array of message IDs, one per recipient, in order of To, Cc, Bcc.","type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"string"}}}}},"errors":{"description":"General request errors.","type":"array","items":{"type":"string"}}}},"SendEmailErrorResponse":{"title":"SendEmailErrorResponse","description":"Error responses use `success: false` and an `errors` array of strings (same pattern as Transactional\nand Bulk sending APIs).\n","type":"object","properties":{"success":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/api/batch/{sandbox_id}":{"post":{"description":"Batch send email (text, html, text&html, templates). Please note that the endpoint will return a 200-level http status, even when sending for individual messages may fail. Users of this endpoint should check the success and errors for each message in the response (the results are ordered the same as the original messages - `requests`). Please note that the endpoint accepts up to 500 messages per API call, and up to 50 MB payload size, including attachments.\n","operationId":"batchSendEmail","summary":"Batch send email (including templates)","tags":["Test Emails"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEmail"}}}},"responses":{"200":{"description":"Success. Check individual `responses` if messages have been delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSentResponse"}}}},"400":{"description":"Bad request. Fix errors listed in response before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailErrorResponse"}}}},"401":{"description":"Unauthorized. Make sure you are sending correct credentials with the request before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailErrorResponse"}}}},"500":{"description":"Internal error. Messages were not delivered. Retry later or contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mailtrap.io/developers/email-sandbox/send-test-emails/batch-send-email-including-templates.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.