> 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/send-email-including-templates.md).

# Send email (including templates)

Send email message to the specified sandbox.

```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":{"EmailWithText":{"title":"Text Only","allOf":[{"$ref":"#/components/schemas/EmailSenderRequired"},{"$ref":"#/components/schemas/EmailRecipients"},{"$ref":"#/components/schemas/EmailReplyTo"},{"$ref":"#/components/schemas/EmailAttachments"},{"$ref":"#/components/schemas/EmailSendingHeaders"},{"$ref":"#/components/schemas/EmailCustomVariables"},{"$ref":"#/components/schemas/EmailSubjectRequired"},{"$ref":"#/components/schemas/EmailTextRequired"},{"$ref":"#/components/schemas/EmailHtml"},{"$ref":"#/components/schemas/EmailCategory"}]},"EmailSenderRequired":{"type":"object","required":["from"],"properties":{"from":{"$ref":"#/components/schemas/Address"}}},"Address":{"title":"Address","type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"}}},"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"}}}},"EmailReplyTo":{"type":"object","properties":{"reply_to":{"$ref":"#/components/schemas/Address"}}},"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"}}}},"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"}}}},"EmailSubjectRequired":{"type":"object","required":["subject"],"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}}},"EmailTextRequired":{"type":"object","required":["text"],"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}}},"EmailCategory":{"type":"object","properties":{"category":{"type":"string","maxLength":255}}},"EmailWithHtml":{"title":"HTML Only","allOf":[{"$ref":"#/components/schemas/EmailSenderRequired"},{"$ref":"#/components/schemas/EmailRecipients"},{"$ref":"#/components/schemas/EmailReplyTo"},{"$ref":"#/components/schemas/EmailAttachments"},{"$ref":"#/components/schemas/EmailSendingHeaders"},{"$ref":"#/components/schemas/EmailCustomVariables"},{"$ref":"#/components/schemas/EmailSubjectRequired"},{"$ref":"#/components/schemas/EmailText"},{"$ref":"#/components/schemas/EmailHtmlRequired"},{"$ref":"#/components/schemas/EmailCategory"}]},"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}}},"EmailHtmlRequired":{"type":"object","required":["html"],"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}}},"EmailWithTextAndHtml":{"title":"Text and HTML","allOf":[{"$ref":"#/components/schemas/EmailSenderRequired"},{"$ref":"#/components/schemas/EmailRecipients"},{"$ref":"#/components/schemas/EmailReplyTo"},{"$ref":"#/components/schemas/EmailAttachments"},{"$ref":"#/components/schemas/EmailSendingHeaders"},{"$ref":"#/components/schemas/EmailCustomVariables"},{"$ref":"#/components/schemas/EmailSubjectRequired"},{"$ref":"#/components/schemas/EmailTextRequired"},{"$ref":"#/components/schemas/EmailHtmlRequired"},{"$ref":"#/components/schemas/EmailCategory"}]},"EmailFromTemplate":{"title":"From Template","allOf":[{"$ref":"#/components/schemas/EmailSenderRequired"},{"$ref":"#/components/schemas/EmailRecipients"},{"$ref":"#/components/schemas/EmailReplyTo"},{"$ref":"#/components/schemas/EmailAttachments"},{"$ref":"#/components/schemas/EmailSendingHeaders"},{"$ref":"#/components/schemas/EmailCustomVariables"},{"$ref":"#/components/schemas/TemplateUuidRequired"},{"$ref":"#/components/schemas/TemplateVariables"}]},"TemplateUuidRequired":{"type":"object","required":["template_uuid"],"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"}}},"SentResponse":{"title":"SentResponse","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"}}}},"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/send/{sandbox_id}":{"post":{"description":"Send email message to the specified sandbox.","operationId":"sendEmail","summary":"Send email (including templates)","tags":["Test Emails"],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EmailWithText"},{"$ref":"#/components/schemas/EmailWithHtml"},{"$ref":"#/components/schemas/EmailWithTextAndHtml"},{"$ref":"#/components/schemas/EmailFromTemplate"}]}}}},"responses":{"200":{"description":"Success. Message has been delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentResponse"}}}},"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"}}}},"429":{"description":"Billing plan limit exhausted or sandbox rate limit exceeded (see the response for details).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmailErrorResponse"}}}},"500":{"description":"Internal error. Mail was 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/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.