# Send Test Emails
Test Emails
## Send email (including templates)
> Send email message to the specified inbox.
```json
{"openapi":"3.1.0","info":{"title":"Email Sandbox","version":"2.0.0"},"tags":[{"name":"Test Emails","description":"Test Emails"}],"servers":[{"description":"Mailtrap Sandbox API","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","type":"object","properties":{"success":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/api/send/{inbox_id}":{"post":{"description":"Send email message to the specified inbox.","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 inbox 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"}}}}}}}}}
```
## 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 API","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","type":"object","properties":{"success":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/api/batch/{inbox_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: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.mailtrap.io/developers/email-sandbox/send-test-emails.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.