Handle batch sending and partial failures in Send API v3.1
masterThe Send API v3.1 allows batch sending via the Messages array. Batch sending is not an atomic operation. A 2xx HTTP response only means Mailjet accepted the request; individual messages within the batch can still fail.
To handle this correctly:
- Inspect individual statuses: Check the
Statusof each entry inresult.body.Messages.Status: 'success': Message accepted and being delivered.Status: 'error': Message failed. Check theErrorsarray forErrorCode,ErrorMessage, andErrorIdentifier.
- Enable Advanced Error Handling: Set
AdvanceErrorHandling: truein the request body to receive oneErrorsentry per validation problem with machine-readable fields. - Avoid duplicates during retry:
- Assign a unique
CustomIDto every message. - On failure, only retry messages where
Statusis'error'. Never re-include messages that were'success'. - Use the
Errors[].StatusCodeto decide if a retry is appropriate (e.g., retry onStatusCode >= 500, but not on validation errors).
- Assign a unique
import { Client, SendEmailV3_1, LibraryResponse } from 'node-mailjet';
const mailjet = new Client({
apiKey: process.env.MJ_APIKEY_PUBLIC,
apiSecret: process.env.MJ_APIKEY_PRIVATE
});
(async () => {
const data: SendEmailV3_1.Body = {
Messages: [
{
From: { Email: 'pilot@test.com' },
To: [{ Email: 'passenger1@test.com' }],
Subject: 'This message is expected to succeed.',
TextPart: 'Success message.',
CustomID: 'order-1001',
},
{
From: { Email: 'pilot@test.com' },
To: [{ Email: 'not-a-valid-address' }],
Subject: 'This message is expected to fail.',
TextPart: 'Failure message.',
CustomID: 'order-1002',
},
],
AdvanceErrorHandling: true,
};
const result: LibraryResponse<SendEmailV3_1.Response> = await mailjet
.post('send', { version: 'v3.1' })
.request(data);
const succeeded = result.body.Messages.filter((message) => message.Status === 'success');
const failed = result.body.Messages.filter((message) => message.Status !== 'success');
})();