Skip to main content
POST
/
api
/
v2
/
emails
/
batch
import { Inbound } from '@inboundemail/sdk';

const inbound = new Inbound('your_api_key');

const { data, error } = await inbound.email.batch.send([
  {
    from: 'Acme <noreply@yourdomain.com>',
    to: ['customer1@example.com'],
    subject: 'Welcome to Acme!',
    html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  },
  {
    from: 'Acme <noreply@yourdomain.com>',
    to: ['customer2@example.com'],
    subject: 'Welcome to Acme!',
    html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  },
], {
  validationMode: 'strict'
});

if (error) {
  console.error('Error:', error);
} else {
  console.log('Emails queued:', data.data);
  if (data.errors) {
    console.log('Errors:', data.errors);
  }
}

{
  "data": [
    { "id": "em_1234567890abcdef" },
    { "id": "em_0987654321fedcba" }
  ]
}
This endpoint is compatible with Resend’s batch email sending API, making it easy to migrate from Resend to Inbound.

​
Authentication

This endpoint requires authentication via:
  • API key auth: Bearer token in Authorization header

​
Body Parameters

The request body is an array of email objects. Each email object follows the same structure as the Send Email endpoint.
​
emails
array
required
Array of email objects to send. Maximum 1000 emails per batch.
Each email object must include the same fields as a single email send request: from, to, subject, and either html or text.

​
Headers

​
Authorization
string
required
Bearer token for API authentication.
​
x-batch-validation
string
Batch validation mode. Controls how invalid emails are handled.
  • strict (default): All emails must be valid. If any email fails validation, the entire batch is rejected with a 400 error.
  • permissive: Process all valid emails and return errors for invalid ones in the response errors array.
In permissive mode, you’ll receive a data array with IDs for successfully queued emails and an errors array with validation failures.

​
Request Example

import { Inbound } from '@inboundemail/sdk';

const inbound = new Inbound('your_api_key');

const { data, error } = await inbound.email.batch.send([
  {
    from: 'Acme <noreply@yourdomain.com>',
    to: ['customer1@example.com'],
    subject: 'Welcome to Acme!',
    html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  },
  {
    from: 'Acme <noreply@yourdomain.com>',
    to: ['customer2@example.com'],
    subject: 'Welcome to Acme!',
    html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  },
], {
  validationMode: 'strict'
});

if (error) {
  console.error('Error:', error);
} else {
  console.log('Emails queued:', data.data);
  if (data.errors) {
    console.log('Errors:', data.errors);
  }
}

​
Response

​
data
array
required
Array of email objects with their unique IDs. Each object contains:
​
errors
array
Array of error objects (only present in permissive validation mode when there are validation failures).
{
  "data": [
    { "id": "em_1234567890abcdef" },
    { "id": "em_0987654321fedcba" }
  ]
}

​
Important Notes

Domain Verification Required: You can only send emails from domains that you own and have verified in your Inbound account. Attempting to send from an unverified domain will result in validation errors.
Email Processing: Each email in the batch is queued separately via QStash with a 500ms delay between each email. This ensures distributed sending and prevents overwhelming the email service. Each email creates a separate database record for individual tracking.
Email Limits: Each email in the batch counts individually toward your monthly email sending limit. The API will validate your limits before queuing emails.
Individual Tracking: Each email in the batch gets its own unique ID and can be tracked individually. Use the /api/v2/emails/{id} endpoint to check the status of any email in the batch.
Rate Limiting: Emails are sent with 500ms delays between each to prevent rate limiting issues. This means a batch of 1000 emails will take approximately 500 seconds (~8.3 minutes) to fully process.

​
Limitations

Current Limitations:
  • Maximum 1000 emails per batch
  • scheduled_at parameter is not supported in batch sends (use individual send endpoint for scheduled emails)
  • Each email must have the same validation requirements as individual sends
  • Combined recipients (to, cc, bcc) per email cannot exceed 50 addresses

​
Migration from Resend

This endpoint is designed to be compatible with Resend’s batch email sending API. To migrate:
  1. Replace your Resend batch endpoint with https://inbound.new/api/v2/emails/batch
  2. Replace your Resend API key with your Inbound API key
  3. Ensure your sending domain is verified in Inbound
  4. Update validation mode header from Resend’s format to x-batch-validation
Supported Resend Features:
  • Batch sending (Inbound supports up to 1000 emails vs Resend’s 100)
  • Strict and permissive validation modes
  • Error reporting with index references
  • All standard email parameters per email object
Differences from Resend:
  • Validation mode header is x-batch-validation (not x-batch-validation-mode)
  • Each email is queued separately with delays (not sent immediately)
  • Each email creates a separate database record for tracking
  • scheduled_at is not supported in batch sends