Send a Batch

curl -X POST https://api.tratto.email/v1/emails/batch \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2e0a-batch-2026-10-20" \
  -d '{
    "emails": [
      {
        "from": "hello@yourdomain.com",
        "to": "alice@example.com",
        "subject": "Your receipt",
        "text": "Thanks for your order, Alice."
      },
      {
        "from": "hello@yourdomain.com",
        "to": ["bob@example.com"],
        "cc": ["billing@example.com"],
        "subject": "Your receipt",
        "templateId": "tmpl_abc123",
        "variables": { "firstName": "Bob" }
      }
    ]
  }'

import { randomUUID } from 'node:crypto';

const response = await fetch('https://api.tratto.email/v1/emails/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tratto_live_...',
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID(),
  },
  body: JSON.stringify({
    emails: [
      { from: 'hello@yourdomain.com', to: 'alice@example.com', subject: 'Your receipt', text: 'Thanks, Alice.' },
      { from: 'hello@yourdomain.com', to: 'bob@example.com', subject: 'Your receipt', text: 'Thanks, Bob.' },
    ],
  }),
});
const { data } = await response.json();
console.log(`${data.accepted} queued, ${data.failed} failed`);

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "docs": "https://docs.tratto.email/en/docs/error-codes",
    "details": [{ "path": "/emails/3/to", "message": "An email can have at most 50 recipients across to, cc and bcc (got 51). Split the send, or use a campaign for a larger audience." }]
  }
}

{
  "data": {
    "batchId": "batch_V1StGXR8Z5jdHi6BmyT2a",
    "livemode": true,
    "accepted": 2,
    "failed": 1,
    "emails": [
      { "id": "email_abc123xyz", "status": "queued", "to": ["alice@example.com"] },
      {
        "status": "failed",
        "to": ["bob@example.com"],
        "error": {
          "code": "SERVICE_UNAVAILABLE",
          "message": "Not sent and not charged: it could not be handed to the delivery queue. Send it again in a new batch, with a new Idempotency-Key."
        }
      },
      { "id": "email_def456uvw", "status": "queued", "to": ["carol@example.com"] }
    ]
  }
}

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "This batch has 120 recipients, more than the emails left on the free plan (3000 per month). Each distinct address in to, cc and bcc counts as one email. The quota is shared by every workspace of the account that owns this one.",
    "docs": "https://docs.tratto.email/en/docs/error-codes",
    "suggestion": "Send to fewer recipients, or have the workspace owner upgrade the plan at https://app.tratto.email/settings/billing."
  }
}

import { randomUUID } from 'node:crypto';
import { Tratto } from '@tratto/email';

const tratto = new Tratto(process.env.TRATTO_API_KEY!);

const batch = await tratto.emails.sendBatch(
  [
    { from: 'hello@yourdomain.com', to: 'alice@example.com', subject: 'Your receipt', text: 'Thanks, Alice.' },
    { from: 'hello@yourdomain.com', to: 'bob@example.com', subject: 'Your receipt', text: 'Thanks, Bob.' },
  ],
  randomUUID(),
);

console.log(`${batch.accepted} queued, ${batch.failed} failed`);
for (const e of batch.emails) {
  if (e.status === 'failed') console.error(e.to, e.error.code, e.error.message);
}

import uuid
from tratto import SendEmailOptions, Tratto

client = Tratto('tratto_live_...')

result = client.emails.send_batch(
    [
        SendEmailOptions(from_='hello@yourdomain.com', to='alice@example.com', subject='Your receipt', text='Thanks, Alice.'),
        SendEmailOptions(from_='hello@yourdomain.com', to='bob@example.com', subject='Your receipt', text='Thanks, Bob.'),
    ],
    idempotency_key=str(uuid.uuid4()),
)

print(result['accepted'], result['failed'])
for item in result['emails']:  # same order as the request
    if item['status'] == 'failed':
        print(item['to'], item['error']['code'])

$emails = [
    ['from' => 'hello@yourdomain.com', 'to' => ['alice@example.com'], 'subject' => 'Your receipt', 'text' => 'Thanks, Alice.'],
    ['from' => 'hello@yourdomain.com', 'to' => ['bob@example.com'], 'subject' => 'Your receipt', 'text' => 'Thanks, Bob.'],
];
$batch = $tratto->emails->sendBatch($emails, 'receipts-2026-10-21');

// Resend only the failed emails, in a new batch with a new key.
$failed = [];
foreach ($batch['emails'] as $i => $result) {
    if ($result['status'] === 'failed') {
        $failed[] = $emails[$i];
    }
}
if ($failed !== []) {
    $tratto->emails->sendBatch($failed, 'receipts-2026-10-21-retry-1');
}