diff --git a/CLAUDE.md b/CLAUDE.md
index da7e5d2..1608d71 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,7 +16,6 @@ mailtrap-openapi/
├── specs/ # OpenAPI specification files
│ ├── contacts.openapi.yml
│ ├── email-api.openapi.yml
-│ ├── email-batch.openapi.yml
│ ├── email-sending-bulk.openapi.yml
│ ├── email-sending-transactional.openapi.yml
│ ├── email-templates.openapi.yml
@@ -36,7 +35,6 @@ mailtrap-openapi/
|-----------|-------------|----------|
| `email-sending-transactional.openapi.yml` | Transactional email sending | `https://send.api.mailtrap.io` |
| `email-sending-bulk.openapi.yml` | Bulk/marketing email sending | `https://bulk.api.mailtrap.io` |
-| `email-batch.openapi.yml` | Batch email operations | `https://send.api.mailtrap.io` |
| `contacts.openapi.yml` | Contact management API | `https://mailtrap.io` |
| `sandbox.openapi.yml` | Email Sandbox/testing API | `https://mailtrap.io` |
| `general.openapi.yml` | Account, users, permissions, billing | `https://mailtrap.io` |
diff --git a/README.md b/README.md
index ad6b841..5114cb5 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,6 @@ The specifications are located in the `specs/` directory:
|------|------|----------|
| Email Sending (Transactional) | `specs/email-sending-transactional.openapi.yml` | `https://send.api.mailtrap.io` |
| Email Sending (Bulk) | `specs/email-sending-bulk.openapi.yml` | `https://bulk.api.mailtrap.io` |
-| Email Batch | `specs/email-batch.openapi.yml` | `https://send.api.mailtrap.io` |
| Contacts | `specs/contacts.openapi.yml` | `https://mailtrap.io` |
| Sandbox | `specs/sandbox.openapi.yml` | `https://mailtrap.io` |
| General | `specs/general.openapi.yml` | `https://mailtrap.io` |
diff --git a/SUMMARY.md b/SUMMARY.md
index 5f125ab..41b1006 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -34,18 +34,6 @@
kind: openapi
spec: email-sending-bulk
```
-* ```yaml
- props:
- models: false
- downloadLink: false
- expandOperations: false
- type: builtin:openapi
- dependencies:
- spec:
- ref:
- kind: openapi
- spec: email-batch
- ```
## Management
diff --git a/specs/email-batch.openapi.yml b/specs/email-batch.openapi.yml
deleted file mode 100644
index 0f065b7..0000000
--- a/specs/email-batch.openapi.yml
+++ /dev/null
@@ -1,556 +0,0 @@
-openapi: 3.1.0
-info:
- title: Send Email - Batch
- version: 2.0.0
- description: |
- Send up to 500 emails in a single API call. Use the Transactional Stream for user-triggered emails or the Bulk Stream for marketing campaigns.
- contact:
- name: Mailtrap Support
- url: 'https://docs.mailtrap.io'
- email: support@mailtrap.io
- license:
- name: Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
- url: 'https://creativecommons.org/licenses/by-sa/4.0/'
- x-logo:
- url: 'https://mailtrap.io/wp-content/uploads/2021/04/mailtrap-logo.svg'
-
-servers:
- - description: Transactional Stream
- url: 'https://send.api.mailtrap.io'
- - description: Bulk Stream
- url: 'https://bulk.api.mailtrap.io'
-
-security:
- - HeaderAuth: []
- - BearerAuth: []
-
-tags:
- - name: batch-send
- x-page-title: Send Email - Batch
- x-page-icon: layer-group
- x-page-description: Send up to 500 emails in a single request
- description: |
- Efficiently send multiple emails with shared content but different recipients.
-
- {% hint style="info" %}
- **SDK Usage**: To send via Bulk Stream using SDKs, add `bulk: true` to your client configuration.
- {% endhint %}
-
- {% hint style="warning" %}
- **Limits**: 500 messages per API call, 50 MB total payload size
- {% endhint %}
-
-paths:
- /api/batch:
- post:
- summary: Batch send emails
- description: |
- Send up to 500 emails in a single API call. Each email can have unique recipients and content while sharing base properties.
-
- **Limits:**
- - Maximum 500 messages per call
- - Maximum 50 MB total payload size (including attachments)
-
- **Note:** The endpoint returns HTTP 200 even if individual messages fail. Check the `responses` array for individual message status.
- operationId: batchSendEmail
- tags:
- - batch-send
- x-codeSamples:
- - lang: javascript
- label: Node.js
- source: |
- import { MailtrapClient } from "mailtrap";
-
- const client = new MailtrapClient({
- token: process.env.MAILTRAP_API_KEY,
- // Add bulk: true for Bulk Stream
- });
-
- async function sendBatch() {
- const response = await client.batchSend({
- base: {
- from: { email: "sender@example.com" },
- subject: "Important Update",
- text: "Hello {{name}}, we have news for you."
- },
- requests: [
- {
- to: [{ email: "user1@example.com" }],
- custom_variables: { name: "Alice" }
- },
- {
- to: [{ email: "user2@example.com" }],
- custom_variables: { name: "Bob" }
- }
- ]
- });
-
- console.log("Batch sent:", response);
- }
-
- sendBatch();
- - lang: php
- label: PHP
- source: |
- from(new Address('sender@example.com', 'Sender'))
- ->subject('Monthly Newsletter')
- ->text('Check out our latest updates!');
-
- $recipients = [
- (new MailtrapEmail())->to(new Address('user1@example.com', 'User 1')),
- (new MailtrapEmail())->to(new Address('user2@example.com', 'User 2'))
- ];
-
- $response = $mailtrap->batchSend($recipients, $baseEmail);
-
- var_dump(ResponseHelper::toArray($response));
- - lang: python
- label: Python
- source: |
- import mailtrap as mt
-
- client = mt.MailtrapClient(
- token="YOUR_API_KEY"
- # Add bulk=True for Bulk Stream
- )
-
- batch_mail = mt.BatchSendEmailParams(
- base=mt.BatchMail(
- sender=mt.Address(email="sender@example.com"),
- subject="Monthly Newsletter",
- text="Check out our latest updates!"
- ),
- requests=[
- mt.BatchEmailRequest(
- to=[mt.Address(email="user1@example.com")]
- ),
- mt.BatchEmailRequest(
- to=[mt.Address(email="user2@example.com")]
- )
- ]
- )
-
- response = client.batch_send(batch_mail)
- - lang: ruby
- label: Ruby
- source: |
- require 'mailtrap'
-
- client = Mailtrap::Client.new(
- api_key: 'YOUR_API_KEY'
- # Add bulk: true for Bulk Stream
- )
-
- batch_base = Mailtrap::Mail.batch_base_from_content(
- from: { email: 'sender@example.com' },
- subject: 'Monthly Newsletter',
- text: 'Check out our latest updates!'
- )
-
- client.send_batch(
- batch_base,
- [
- Mailtrap::Mail.from_content(
- to: [{ email: 'user1@example.com' }]
- ),
- Mailtrap::Mail.from_content(
- to: [{ email: 'user2@example.com' }]
- )
- ]
- )
- - lang: csharp
- label: .NET
- source: |
- using Mailtrap;
- using Mailtrap.Configuration;
- using Mailtrap.Emails.Requests;
-
- var config = new MailtrapClientOptions
- {
- ApiToken = "YOUR_API_KEY"
- // Add UseBulkApi = true for Bulk Stream
- };
-
- using var mailtrapFactory = new MailtrapClientFactory(config);
- var client = mailtrapFactory.CreateClient();
-
- var batchRequest = BatchEmailRequest.Create()
- .Base(b => b
- .From("sender@example.com")
- .Subject("Monthly Newsletter")
- .Text("Check out our latest updates!"))
- .Requests(r => r
- .To("user1@example.com"))
- .Requests(r => r
- .To("user2@example.com"));
- await client.BatchEmail().Send(batchRequest);
- - lang: java
- label: Java
- source: |
- import io.mailtrap.config.MailtrapConfig;
- import io.mailtrap.factory.MailtrapClientFactory;
- import io.mailtrap.model.request.emails.Address;
- import io.mailtrap.model.request.emails.BatchEmailBase;
- import io.mailtrap.model.request.emails.MailtrapBatchMail;
- import io.mailtrap.model.request.emails.MailtrapMail;
- import java.util.List;
-
- var config = new MailtrapConfig.Builder()
- .token("YOUR_API_KEY")
- .build();
-
- var client = MailtrapClientFactory.createMailtrapClient(config);
-
- var base = BatchEmailBase.builder()
- .from(new Address("sender@example.com"))
- .subject("Monthly Newsletter")
- .text("Check out our latest updates!")
- .build();
-
- var requests = List.of(
- MailtrapMail.builder()
- .to(List.of(new Address("user1@example.com")))
- .build(),
- MailtrapMail.builder()
- .to(List.of(new Address("user2@example.com")))
- .build()
- );
-
- var batchMail = MailtrapBatchMail.builder()
- .base(base)
- .requests(requests)
- .build();
-
- client.sendingApi().emails().batchSend(batchMail);
- - lang: shell
- label: 'cURL'
- source: |
- # Transactional Stream
- curl -X POST https://send.api.mailtrap.io/api/batch \
- -H 'Authorization: Bearer YOUR_API_KEY' \
- -H 'Content-Type: application/json' \
- -d '{
- "base": {
- "from": {"email": "sender@example.com"},
- "subject": "Monthly Newsletter"
- },
- "requests": [
- {"to": [{"email": "user1@example.com"}]},
- {"to": [{"email": "user2@example.com"}]},
- {"to": [{"email": "user3@example.com"}]}
- ]
- }'
-
- # Bulk Stream - change host to bulk.api.mailtrap.io
- curl -X POST https://bulk.api.mailtrap.io/api/batch \
- -H 'Authorization: Bearer YOUR_API_KEY' \
- -H 'Content-Type: application/json' \
- -d '{...}'
- requestBody:
- required: true
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/BatchEmail'
- responses:
- '200':
- description: Batch processed. Check individual responses for delivery status.
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/BatchSentResponse'
- '400':
- $ref: '#/components/responses/BadRequest'
- '401':
- $ref: '#/components/responses/Unauthorized'
- '500':
- $ref: '#/components/responses/InternalError'
-
-components:
- securitySchemes:
- HeaderAuth:
- type: apiKey
- description: API token in Api-Token header
- in: header
- name: Api-Token
- BearerAuth:
- type: http
- scheme: bearer
- bearerFormat: JWT
- description: Bearer token authentication
-
- schemas:
- Address:
- type: object
- properties:
- email:
- type: string
- format: email
- example: john@example.com
- name:
- type: string
- example: John Doe
-
- EmailSender:
- type: object
- required:
- - from
- properties:
- from:
- $ref: '#/components/schemas/Address'
-
- 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
- maxItems: 1000
- items:
- $ref: '#/components/schemas/Address'
-
- EmailReplyTo:
- type: object
- properties:
- reply_to:
- $ref: '#/components/schemas/Address'
-
- EmailSubject:
- type: object
- required:
- - subject
- properties:
- subject:
- type: string
- minLength: 1
- example: Your Order Confirmation
-
- EmailText:
- type: object
- properties:
- text:
- type: string
- minLength: 1
- example: Thank you for your order!
-
- EmailHtml:
- type: object
- properties:
- html:
- type: string
- minLength: 1
- example: Thank you for your order!
-
- EmailCategory:
- type: object
- properties:
- category:
- type: string
- maxLength: 255
- example: transactional
-
- EmailCustomVariables:
- type: object
- properties:
- custom_variables:
- type: object
- additionalProperties:
- type: string
- example:
- user_id: "12345"
- order_id: "ORD-789"
-
- EmailSendingHeaders:
- type: object
- properties:
- headers:
- type: object
- additionalProperties:
- type: string
- example:
- X-Message-Source: api.example.com
- X-Campaign-ID: CAMP-123
-
- EmailAttachments:
- type: object
- properties:
- attachments:
- type: array
- items:
- type: object
- required:
- - content
- - filename
- properties:
- content:
- type: string
- description: Base64 encoded content
- example: base64encodedcontent==
- filename:
- type: string
- example: document.pdf
- type:
- type: string
- description: MIME type
- example: application/pdf
- disposition:
- type: string
- enum: [attachment, inline]
- default: attachment
- content_id:
- type: string
- description: For inline attachments
- example: image001
-
- TemplateUuid:
- type: object
- properties:
- template_uuid:
- type: string
- format: uuid
- description: Email template UUID
- example: b81aabcd-1a1e-41cf-91b6-eca0254b3d96
-
- TemplateVariables:
- type: object
- properties:
- template_variables:
- type: object
- description: Template variable values
- example:
- user_name: John Doe
- order_number: "12345"
-
- BatchEmail:
- title: Batch Email Request
- description: Send multiple emails in a single API call (up to 500)
- type: object
- required:
- - requests
- properties:
- base:
- description: Base properties shared by all 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:
- type: array
- description: Individual email configurations (max 500)
- maxItems: 500
- items:
- 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'
-
- BatchSentResponse:
- type: object
- properties:
- success:
- type: boolean
- description: Overall request success
- example: true
- responses:
- type: array
- description: Individual message results
- items:
- type: object
- properties:
- success:
- type: boolean
- example: true
- message_ids:
- type: array
- items:
- type: string
- example: 0c7fd939-02cf-11ed-88c2-0a58a9feac02
- errors:
- type: array
- items:
- type: string
- errors:
- type: array
- description: General errors
- items:
- type: string
-
- SendEmailErrorResponse:
- type: object
- properties:
- success:
- type: boolean
- example: false
- errors:
- type: array
- items:
- type: string
- example: Invalid sender email address
-
- responses:
- BadRequest:
- description: Bad request. Fix errors listed in response before retrying.
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/SendEmailErrorResponse'
- example:
- success: false
- errors:
- - "'from' address is invalid"
-
- Unauthorized:
- description: Unauthorized. Check your API credentials.
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/SendEmailErrorResponse'
- example:
- success: false
- errors:
- - "Unauthorized"
-
- InternalError:
- description: Internal server error. Retry later or contact support.
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/SendEmailErrorResponse'
diff --git a/specs/email-sending-bulk.openapi.yml b/specs/email-sending-bulk.openapi.yml
index ee58722..a2fb795 100644
--- a/specs/email-sending-bulk.openapi.yml
+++ b/specs/email-sending-bulk.openapi.yml
@@ -236,6 +236,235 @@ paths:
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalError'
+ /api/batch:
+ post:
+ summary: Batch send emails
+ description: |
+ Send up to 500 marketing emails in a single API call. Each email can have unique recipients and content while sharing base properties.
+
+ **Limits:**
+ - Maximum 500 messages per call
+ - Maximum 50 MB total payload size (including attachments)
+
+ **Note:** The endpoint returns HTTP 200 even if individual messages fail. Check the `responses` array for individual message status.
+ operationId: batchSendEmail
+ tags:
+ - send-email
+ x-codeSamples:
+ - lang: javascript
+ label: Node.js
+ source: |
+ import { MailtrapClient } from "mailtrap";
+
+ const client = new MailtrapClient({
+ token: process.env.MAILTRAP_API_KEY,
+ bulk: true
+ });
+
+ async function sendBatch() {
+ const response = await client.batchSend({
+ base: {
+ from: { email: "sender@example.com" },
+ subject: "Important Update",
+ text: "Hello {{name}}, we have news for you."
+ },
+ requests: [
+ {
+ to: [{ email: "user1@example.com" }],
+ custom_variables: { name: "Alice" }
+ },
+ {
+ to: [{ email: "user2@example.com" }],
+ custom_variables: { name: "Bob" }
+ }
+ ]
+ });
+
+ console.log("Batch sent:", response);
+ }
+
+ sendBatch();
+ - lang: php
+ label: PHP
+ source: |
+ from(new Address('sender@example.com', 'Sender'))
+ ->subject('Monthly Newsletter')
+ ->text('Check out our latest updates!');
+
+ $recipients = [
+ (new MailtrapEmail())->to(new Address('user1@example.com', 'User 1')),
+ (new MailtrapEmail())->to(new Address('user2@example.com', 'User 2'))
+ ];
+
+ $response = $mailtrap->batchSend($recipients, $baseEmail);
+
+ var_dump(ResponseHelper::toArray($response));
+ - lang: python
+ label: Python
+ source: |
+ import mailtrap as mt
+
+ client = mt.MailtrapClient(
+ token="YOUR_API_KEY",
+ bulk=True
+ )
+
+ batch_mail = mt.BatchSendEmailParams(
+ base=mt.BatchMail(
+ sender=mt.Address(email="sender@example.com"),
+ subject="Monthly Newsletter",
+ text="Check out our latest updates!"
+ ),
+ requests=[
+ mt.BatchEmailRequest(
+ to=[mt.Address(email="user1@example.com")]
+ ),
+ mt.BatchEmailRequest(
+ to=[mt.Address(email="user2@example.com")]
+ )
+ ]
+ )
+
+ response = client.batch_send(batch_mail)
+ - lang: ruby
+ label: Ruby
+ source: |
+ require 'mailtrap'
+
+ client = Mailtrap::Client.new(
+ api_key: 'YOUR_API_KEY',
+ bulk: true
+ )
+
+ batch_base = Mailtrap::Mail.batch_base_from_content(
+ from: { email: 'sender@example.com' },
+ subject: 'Monthly Newsletter',
+ text: 'Check out our latest updates!'
+ )
+
+ client.send_batch(
+ batch_base,
+ [
+ Mailtrap::Mail.from_content(
+ to: [{ email: 'user1@example.com' }]
+ ),
+ Mailtrap::Mail.from_content(
+ to: [{ email: 'user2@example.com' }]
+ )
+ ]
+ )
+ - lang: csharp
+ label: .NET
+ source: |
+ using Mailtrap;
+ using Mailtrap.Configuration;
+ using Mailtrap.Emails.Requests;
+
+ var config = new MailtrapClientOptions
+ {
+ ApiToken = "YOUR_API_KEY",
+ UseBulkApi = true
+ };
+
+ using var mailtrapFactory = new MailtrapClientFactory(config);
+ var client = mailtrapFactory.CreateClient();
+
+ var batchRequest = BatchEmailRequest.Create()
+ .Base(b => b
+ .From("sender@example.com")
+ .Subject("Monthly Newsletter")
+ .Text("Check out our latest updates!"))
+ .Requests(r => r
+ .To("user1@example.com"))
+ .Requests(r => r
+ .To("user2@example.com"));
+ await client.BatchEmail().Send(batchRequest);
+ - lang: java
+ label: Java
+ source: |
+ import io.mailtrap.config.MailtrapConfig;
+ import io.mailtrap.factory.MailtrapClientFactory;
+ import io.mailtrap.model.request.emails.Address;
+ import io.mailtrap.model.request.emails.BatchEmailBase;
+ import io.mailtrap.model.request.emails.MailtrapBatchMail;
+ import io.mailtrap.model.request.emails.MailtrapMail;
+ import java.util.List;
+
+ var config = new MailtrapConfig.Builder()
+ .token("YOUR_API_KEY")
+ .build();
+
+ var client = MailtrapClientFactory.createMailtrapClient(config);
+
+ var base = BatchEmailBase.builder()
+ .from(new Address("sender@example.com"))
+ .subject("Monthly Newsletter")
+ .text("Check out our latest updates!")
+ .build();
+
+ var requests = List.of(
+ MailtrapMail.builder()
+ .to(List.of(new Address("user1@example.com")))
+ .build(),
+ MailtrapMail.builder()
+ .to(List.of(new Address("user2@example.com")))
+ .build()
+ );
+
+ var batchMail = MailtrapBatchMail.builder()
+ .base(base)
+ .requests(requests)
+ .build();
+
+ client.bulkSendingApi().emails().batchSend(batchMail);
+ - lang: shell
+ label: 'cURL'
+ source: |
+ curl -X POST https://bulk.api.mailtrap.io/api/batch \
+ -H 'Authorization: Bearer YOUR_API_KEY' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "base": {
+ "from": {"email": "sender@example.com"},
+ "subject": "Monthly Newsletter"
+ },
+ "requests": [
+ {"to": [{"email": "user1@example.com"}]},
+ {"to": [{"email": "user2@example.com"}]},
+ {"to": [{"email": "user3@example.com"}]}
+ ]
+ }'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BatchEmail'
+ responses:
+ '200':
+ description: Batch processed. Check individual responses for delivery status.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BatchSentResponse'
+ '400':
+ $ref: '#/components/responses/BadRequest'
+ '401':
+ $ref: '#/components/responses/Unauthorized'
+ '500':
+ $ref: '#/components/responses/InternalError'
components:
securitySchemes:
@@ -263,6 +492,12 @@ components:
example: John Doe
EmailSender:
+ type: object
+ properties:
+ from:
+ $ref: '#/components/schemas/Address'
+
+ EmailSenderRequired:
type: object
required:
- from
@@ -296,6 +531,14 @@ components:
$ref: '#/components/schemas/Address'
EmailSubject:
+ type: object
+ properties:
+ subject:
+ type: string
+ minLength: 1
+ example: Monthly Newsletter
+
+ EmailSubjectRequired:
type: object
required:
- subject
@@ -306,6 +549,14 @@ components:
example: Monthly Newsletter
EmailText:
+ type: object
+ properties:
+ text:
+ type: string
+ minLength: 1
+ example: Check out our latest updates!
+
+ EmailTextRequired:
type: object
required:
- text
@@ -316,6 +567,14 @@ components:
example: Check out our latest updates!
EmailHtml:
+ type: object
+ properties:
+ html:
+ type: string
+ minLength: 1
+ example: Our Latest Updates
+
+ EmailHtmlRequired:
type: object
required:
- html
@@ -387,6 +646,15 @@ components:
example: image001
TemplateUuid:
+ type: object
+ properties:
+ template_uuid:
+ type: string
+ format: uuid
+ description: Email template UUID
+ example: b81aabcd-1a1e-41cf-91b6-eca0254b3d96
+
+ TemplateUuidRequired:
type: object
required:
- template_uuid
@@ -410,11 +678,11 @@ components:
EmailWithText:
title: Text Only
allOf:
- - $ref: '#/components/schemas/EmailSender'
+ - $ref: '#/components/schemas/EmailSenderRequired'
- $ref: '#/components/schemas/EmailRecipients'
- $ref: '#/components/schemas/EmailReplyTo'
- - $ref: '#/components/schemas/EmailSubject'
- - $ref: '#/components/schemas/EmailText'
+ - $ref: '#/components/schemas/EmailSubjectRequired'
+ - $ref: '#/components/schemas/EmailTextRequired'
- $ref: '#/components/schemas/EmailAttachments'
- $ref: '#/components/schemas/EmailSendingHeaders'
- $ref: '#/components/schemas/EmailCustomVariables'
@@ -423,11 +691,11 @@ components:
EmailWithHtml:
title: HTML Only
allOf:
- - $ref: '#/components/schemas/EmailSender'
+ - $ref: '#/components/schemas/EmailSenderRequired'
- $ref: '#/components/schemas/EmailRecipients'
- $ref: '#/components/schemas/EmailReplyTo'
- - $ref: '#/components/schemas/EmailSubject'
- - $ref: '#/components/schemas/EmailHtml'
+ - $ref: '#/components/schemas/EmailSubjectRequired'
+ - $ref: '#/components/schemas/EmailHtmlRequired'
- $ref: '#/components/schemas/EmailAttachments'
- $ref: '#/components/schemas/EmailSendingHeaders'
- $ref: '#/components/schemas/EmailCustomVariables'
@@ -436,12 +704,12 @@ components:
EmailWithTextAndHtml:
title: Text and HTML
allOf:
- - $ref: '#/components/schemas/EmailSender'
+ - $ref: '#/components/schemas/EmailSenderRequired'
- $ref: '#/components/schemas/EmailRecipients'
- $ref: '#/components/schemas/EmailReplyTo'
- - $ref: '#/components/schemas/EmailSubject'
- - $ref: '#/components/schemas/EmailText'
- - $ref: '#/components/schemas/EmailHtml'
+ - $ref: '#/components/schemas/EmailSubjectRequired'
+ - $ref: '#/components/schemas/EmailTextRequired'
+ - $ref: '#/components/schemas/EmailHtmlRequired'
- $ref: '#/components/schemas/EmailAttachments'
- $ref: '#/components/schemas/EmailSendingHeaders'
- $ref: '#/components/schemas/EmailCustomVariables'
@@ -450,10 +718,10 @@ components:
EmailFromTemplate:
title: From Template
allOf:
- - $ref: '#/components/schemas/EmailSender'
+ - $ref: '#/components/schemas/EmailSenderRequired'
- $ref: '#/components/schemas/EmailRecipients'
- $ref: '#/components/schemas/EmailReplyTo'
- - $ref: '#/components/schemas/TemplateUuid'
+ - $ref: '#/components/schemas/TemplateUuidRequired'
- $ref: '#/components/schemas/TemplateVariables'
- $ref: '#/components/schemas/EmailAttachments'
- $ref: '#/components/schemas/EmailSendingHeaders'
@@ -484,6 +752,77 @@ components:
type: string
example: Invalid sender email address
+ BatchEmail:
+ title: Batch Email Request
+ description: Send multiple emails in a single API call (up to 500)
+ type: object
+ required:
+ - requests
+ properties:
+ base:
+ description: Base properties shared by all 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:
+ type: array
+ description: Individual email configurations (max 500)
+ maxItems: 500
+ items:
+ 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'
+
+ BatchSentResponse:
+ type: object
+ properties:
+ success:
+ type: boolean
+ description: Overall request success
+ example: true
+ responses:
+ type: array
+ description: Individual message results
+ items:
+ type: object
+ properties:
+ success:
+ type: boolean
+ example: true
+ message_ids:
+ type: array
+ items:
+ type: string
+ example: 0c7fd939-02cf-11ed-88c2-0a58a9feac02
+ errors:
+ type: array
+ items:
+ type: string
+ errors:
+ type: array
+ description: General errors
+ items:
+ type: string
+
responses:
BadRequest:
description: Bad request. Fix errors listed in response before retrying.
diff --git a/specs/email-sending-transactional.openapi.yml b/specs/email-sending-transactional.openapi.yml
index 09eec44..9222166 100644
--- a/specs/email-sending-transactional.openapi.yml
+++ b/specs/email-sending-transactional.openapi.yml
@@ -210,6 +210,230 @@ paths:
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalError'
+ /api/batch:
+ post:
+ summary: Batch send emails
+ description: |
+ Send up to 500 transactional emails in a single API call. Each email can have unique recipients and content while sharing base properties.
+
+ **Limits:**
+ - Maximum 500 messages per call
+ - Maximum 50 MB total payload size (including attachments)
+
+ **Note:** The endpoint returns HTTP 200 even if individual messages fail. Check the `responses` array for individual message status.
+ operationId: batchSendEmail
+ tags:
+ - send-email
+ x-codeSamples:
+ - lang: javascript
+ label: Node.js
+ source: |
+ import { MailtrapClient } from "mailtrap";
+
+ const client = new MailtrapClient({
+ token: process.env.MAILTRAP_API_KEY
+ });
+
+ async function sendBatch() {
+ const response = await client.batchSend({
+ base: {
+ from: { email: "sender@example.com" },
+ subject: "Important Update",
+ text: "Hello {{name}}, we have news for you."
+ },
+ requests: [
+ {
+ to: [{ email: "user1@example.com" }],
+ custom_variables: { name: "Alice" }
+ },
+ {
+ to: [{ email: "user2@example.com" }],
+ custom_variables: { name: "Bob" }
+ }
+ ]
+ });
+
+ console.log("Batch sent:", response);
+ }
+
+ sendBatch();
+ - lang: php
+ label: PHP
+ source: |
+ from(new Address('sender@example.com', 'Sender'))
+ ->subject('Monthly Newsletter')
+ ->text('Check out our latest updates!');
+
+ $recipients = [
+ (new MailtrapEmail())->to(new Address('user1@example.com', 'User 1')),
+ (new MailtrapEmail())->to(new Address('user2@example.com', 'User 2'))
+ ];
+
+ $response = $mailtrap->batchSend($recipients, $baseEmail);
+
+ var_dump(ResponseHelper::toArray($response));
+ - lang: python
+ label: Python
+ source: |
+ import mailtrap as mt
+
+ client = mt.MailtrapClient(
+ token="YOUR_API_KEY"
+ )
+
+ batch_mail = mt.BatchSendEmailParams(
+ base=mt.BatchMail(
+ sender=mt.Address(email="sender@example.com"),
+ subject="Monthly Newsletter",
+ text="Check out our latest updates!"
+ ),
+ requests=[
+ mt.BatchEmailRequest(
+ to=[mt.Address(email="user1@example.com")]
+ ),
+ mt.BatchEmailRequest(
+ to=[mt.Address(email="user2@example.com")]
+ )
+ ]
+ )
+
+ response = client.batch_send(batch_mail)
+ - lang: ruby
+ label: Ruby
+ source: |
+ require 'mailtrap'
+
+ client = Mailtrap::Client.new(
+ api_key: 'YOUR_API_KEY'
+ )
+
+ batch_base = Mailtrap::Mail.batch_base_from_content(
+ from: { email: 'sender@example.com' },
+ subject: 'Monthly Newsletter',
+ text: 'Check out our latest updates!'
+ )
+
+ client.send_batch(
+ batch_base,
+ [
+ Mailtrap::Mail.from_content(
+ to: [{ email: 'user1@example.com' }]
+ ),
+ Mailtrap::Mail.from_content(
+ to: [{ email: 'user2@example.com' }]
+ )
+ ]
+ )
+ - lang: csharp
+ label: .NET
+ source: |
+ using Mailtrap;
+ using Mailtrap.Configuration;
+ using Mailtrap.Emails.Requests;
+
+ var config = new MailtrapClientOptions
+ {
+ ApiToken = "YOUR_API_KEY"
+ };
+
+ using var mailtrapFactory = new MailtrapClientFactory(config);
+ var client = mailtrapFactory.CreateClient();
+
+ var batchRequest = BatchEmailRequest.Create()
+ .Base(b => b
+ .From("sender@example.com")
+ .Subject("Monthly Newsletter")
+ .Text("Check out our latest updates!"))
+ .Requests(r => r
+ .To("user1@example.com"))
+ .Requests(r => r
+ .To("user2@example.com"));
+ await client.BatchEmail().Send(batchRequest);
+ - lang: java
+ label: Java
+ source: |
+ import io.mailtrap.config.MailtrapConfig;
+ import io.mailtrap.factory.MailtrapClientFactory;
+ import io.mailtrap.model.request.emails.Address;
+ import io.mailtrap.model.request.emails.BatchEmailBase;
+ import io.mailtrap.model.request.emails.MailtrapBatchMail;
+ import io.mailtrap.model.request.emails.MailtrapMail;
+ import java.util.List;
+
+ var config = new MailtrapConfig.Builder()
+ .token("YOUR_API_KEY")
+ .build();
+
+ var client = MailtrapClientFactory.createMailtrapClient(config);
+
+ var base = BatchEmailBase.builder()
+ .from(new Address("sender@example.com"))
+ .subject("Monthly Newsletter")
+ .text("Check out our latest updates!")
+ .build();
+
+ var requests = List.of(
+ MailtrapMail.builder()
+ .to(List.of(new Address("user1@example.com")))
+ .build(),
+ MailtrapMail.builder()
+ .to(List.of(new Address("user2@example.com")))
+ .build()
+ );
+
+ var batchMail = MailtrapBatchMail.builder()
+ .base(base)
+ .requests(requests)
+ .build();
+
+ client.sendingApi().emails().batchSend(batchMail);
+ - lang: shell
+ label: 'cURL'
+ source: |
+ curl -X POST https://send.api.mailtrap.io/api/batch \
+ -H 'Authorization: Bearer YOUR_API_KEY' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "base": {
+ "from": {"email": "sender@example.com"},
+ "subject": "Monthly Newsletter"
+ },
+ "requests": [
+ {"to": [{"email": "user1@example.com"}]},
+ {"to": [{"email": "user2@example.com"}]},
+ {"to": [{"email": "user3@example.com"}]}
+ ]
+ }'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BatchEmail'
+ responses:
+ '200':
+ description: Batch processed. Check individual responses for delivery status.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BatchSentResponse'
+ '400':
+ $ref: '#/components/responses/BadRequest'
+ '401':
+ $ref: '#/components/responses/Unauthorized'
+ '500':
+ $ref: '#/components/responses/InternalError'
components:
securitySchemes:
@@ -237,6 +461,12 @@ components:
example: John Doe
EmailSender:
+ type: object
+ properties:
+ from:
+ $ref: '#/components/schemas/Address'
+
+ EmailSenderRequired:
type: object
required:
- from
@@ -270,6 +500,14 @@ components:
$ref: '#/components/schemas/Address'
EmailSubject:
+ type: object
+ properties:
+ subject:
+ type: string
+ minLength: 1
+ example: Your Order Confirmation
+
+ EmailSubjectRequired:
type: object
required:
- subject
@@ -280,6 +518,14 @@ components:
example: Your Order Confirmation
EmailText:
+ type: object
+ properties:
+ text:
+ type: string
+ minLength: 1
+ example: Thank you for your order!
+
+ EmailTextRequired:
type: object
required:
- text
@@ -290,6 +536,14 @@ components:
example: Thank you for your order!
EmailHtml:
+ type: object
+ properties:
+ html:
+ type: string
+ minLength: 1
+ example: Thank you for your order!
+
+ EmailHtmlRequired:
type: object
required:
- html
@@ -361,6 +615,15 @@ components:
example: image001
TemplateUuid:
+ type: object
+ properties:
+ template_uuid:
+ type: string
+ format: uuid
+ description: Email template UUID
+ example: b81aabcd-1a1e-41cf-91b6-eca0254b3d96
+
+ TemplateUuidRequired:
type: object
required:
- template_uuid
@@ -384,11 +647,11 @@ components:
EmailWithText:
title: Text Only
allOf:
- - $ref: '#/components/schemas/EmailSender'
+ - $ref: '#/components/schemas/EmailSenderRequired'
- $ref: '#/components/schemas/EmailRecipients'
- $ref: '#/components/schemas/EmailReplyTo'
- - $ref: '#/components/schemas/EmailSubject'
- - $ref: '#/components/schemas/EmailText'
+ - $ref: '#/components/schemas/EmailSubjectRequired'
+ - $ref: '#/components/schemas/EmailTextRequired'
- $ref: '#/components/schemas/EmailAttachments'
- $ref: '#/components/schemas/EmailSendingHeaders'
- $ref: '#/components/schemas/EmailCustomVariables'
@@ -397,11 +660,11 @@ components:
EmailWithHtml:
title: HTML Only
allOf:
- - $ref: '#/components/schemas/EmailSender'
+ - $ref: '#/components/schemas/EmailSenderRequired'
- $ref: '#/components/schemas/EmailRecipients'
- $ref: '#/components/schemas/EmailReplyTo'
- - $ref: '#/components/schemas/EmailSubject'
- - $ref: '#/components/schemas/EmailHtml'
+ - $ref: '#/components/schemas/EmailSubjectRequired'
+ - $ref: '#/components/schemas/EmailHtmlRequired'
- $ref: '#/components/schemas/EmailAttachments'
- $ref: '#/components/schemas/EmailSendingHeaders'
- $ref: '#/components/schemas/EmailCustomVariables'
@@ -410,12 +673,12 @@ components:
EmailWithTextAndHtml:
title: Text and HTML
allOf:
- - $ref: '#/components/schemas/EmailSender'
+ - $ref: '#/components/schemas/EmailSenderRequired'
- $ref: '#/components/schemas/EmailRecipients'
- $ref: '#/components/schemas/EmailReplyTo'
- - $ref: '#/components/schemas/EmailSubject'
- - $ref: '#/components/schemas/EmailText'
- - $ref: '#/components/schemas/EmailHtml'
+ - $ref: '#/components/schemas/EmailSubjectRequired'
+ - $ref: '#/components/schemas/EmailTextRequired'
+ - $ref: '#/components/schemas/EmailHtmlRequired'
- $ref: '#/components/schemas/EmailAttachments'
- $ref: '#/components/schemas/EmailSendingHeaders'
- $ref: '#/components/schemas/EmailCustomVariables'
@@ -424,10 +687,10 @@ components:
EmailFromTemplate:
title: From Template
allOf:
- - $ref: '#/components/schemas/EmailSender'
+ - $ref: '#/components/schemas/EmailSenderRequired'
- $ref: '#/components/schemas/EmailRecipients'
- $ref: '#/components/schemas/EmailReplyTo'
- - $ref: '#/components/schemas/TemplateUuid'
+ - $ref: '#/components/schemas/TemplateUuidRequired'
- $ref: '#/components/schemas/TemplateVariables'
- $ref: '#/components/schemas/EmailAttachments'
- $ref: '#/components/schemas/EmailSendingHeaders'
@@ -458,6 +721,77 @@ components:
type: string
example: Invalid sender email address
+ BatchEmail:
+ title: Batch Email Request
+ description: Send multiple emails in a single API call (up to 500)
+ type: object
+ required:
+ - requests
+ properties:
+ base:
+ description: Base properties shared by all 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:
+ type: array
+ description: Individual email configurations (max 500)
+ maxItems: 500
+ items:
+ 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'
+
+ BatchSentResponse:
+ type: object
+ properties:
+ success:
+ type: boolean
+ description: Overall request success
+ example: true
+ responses:
+ type: array
+ description: Individual message results
+ items:
+ type: object
+ properties:
+ success:
+ type: boolean
+ example: true
+ message_ids:
+ type: array
+ items:
+ type: string
+ example: 0c7fd939-02cf-11ed-88c2-0a58a9feac02
+ errors:
+ type: array
+ items:
+ type: string
+ errors:
+ type: array
+ description: General errors
+ items:
+ type: string
+
responses:
BadRequest:
description: Bad request. Fix errors listed in response before retrying.