Guides
  1. Channels
  2. Email
  3. Bulk API (v2.0)

Mail Send CallBack

send bulk email

Overview

High-volume email sending endpoint optimized for sending thousands of emails efficiently. Unlike
the Single API, this endpoint is designed for batch processing and includes features like:

  • Batch submission of multiple emails
  • Template variable substitution
  • Scheduled sending
  • Campaign-level tracking
  • Optimized delivery algorithms

Use for marketing campaigns, newsletters, and any scenario requiring high throughput.

Endpoint Details

HTTP MethodPOST
Endpoint Path/v2/mail/send
API VersionBulk API (v2.0)
Content-Typeapplication/json

Request Parameters

Request Example

Below is a complete example of the request body. Replace placeholder values with your actual credentials and data.

{
  "personalizations": [
    {
      "to": [
        {
          "email": "[email protected]",
          "name": "John Doe"
        },
        {
          "email": "[email protected]",
          "name": "XYZ"
        }
      ],
      "cc": [
        {
          "email": "[email protected]",
          "name": "Jane Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jim Doe"
        }
      ],
      "subject": "John doe"
    },
    {
      "from": {
        "email": "[email protected]",
        "name": "Example Sales Team"
      },
      "to": [
        {
          "email": "[email protected]",
          "name": "Janice Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jordan Doe"
        }
      ]
    }
  ],
  "from": {
    "email": "[email protected]",
    "name": "Example Order Confirmation"
  },
  "reply_to": {
    "email": "[email protected]",
    "name": "Example Customer Service Team"
  },
  "subject": "Sendclean Test Email via Postman",
  "content": [
    {
      "type": "text/html",
      "value": "<p>Hello from Twilio SendGrid!</p><p>Sending with the email service trusted by developers and marketers for <strong>time-savings</strong>, <strong>scalability</strong>, and <strong>delivery expertise</strong>.</p><p>%open-track%</p>"
    }
  ],
  "attachments": [
    {
      "content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==",
      "filename": "index.html",
      "type": "text/html",
      "disposition": "attachment"
    }
  ],
  "categories": [
    "cake",
    "pie",
    "baking"
  ],
  "send_at": 1617260400,
  "batch_id": "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl",
  "asm": {
    "group_id": 12345,
    "groups_to_display": [
      12345
    ]
  },
  "ip_pool_name": "transactional email",
  "mail_settings": {
    "bypass_list_management": {
      "enable": false
    },
    "footer": {
      "enable": false
    },
    "sandbox_mode": {
      "enable": false
    }
  },
  "tracking_settings": {
    "click_tracking": {
      "enable": true,
      "enable_text": false
    },
    "open_tracking": {
      "enable": true,
      "substitution_tag": "%open-track%"
    },
    "subscription_tracking": {
      "enable": false
    }
  }
}

Response Format

Successful Response:

{
    "status": "success",
    "code": 200,
    "message": "Email queued successfully",
    "data": {
        "message_id": "msg_abc123xyz",
        "queued_at": "2026-04-17T10:30:00Z",
        "recipients": 1
    }
}

Common Use Cases

  • Send weekly newsletters to 50,000+ subscribers
  • Distribute promotional campaigns for product launches
  • Send monthly account statements to all customers
  • Deliver event announcements to registered attendees
  • Send scheduled re-engagement campaigns

Best Practices

  • • Batch emails in groups of 1000-5000 for optimal processing
  • • Schedule campaigns during recipient active hours for better engagement
  • • Implement proper list hygiene - remove bounces and unsubscribes regularly
  • • Use segmentation to send relevant content to specific audiences
  • • Monitor sender reputation and adjust sending volume if it drops

Common Errors & Troubleshooting

401 - Unauthorized: Authentication credentials are missing or invalid

Solution: Verify owner_id and token are correct. Ensure they match your account credentials exactly with no extra whitespace.

500 - Internal server error: Unexpected server error occurred

Solution: Retry the request after a brief delay. If error persists, contact SendClean support with the request details and timestamp.

Implementation Examples

Python (requests):

import requests
import json

url = "https://api.sendclean.com/v2/mail/send"

payload =:

{
  "personalizations": [
    {
      "to": [
        {
          "email": "[email protected]",
          "name": "John Doe"
        },
        {
          "email": "[email protected]",
          "name": "XYZ"
        }
      ],
      "cc": [
        {
          "email": "[email protected]",
          "name": "Jane Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jim Doe"
        }
      ],
      "subject": "John doe"
    },
    {
      "from": {
        "email": "[email protected]",
        "name": "Example Sales Team"
      },
      "to": [
        {
          "email": "[email protected]",
          "name": "Janice Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jordan Doe"
        }
      ]
    }
  ],
  "from": {
    "email": "[email protected]",
    "name": "Example Order Confirmation"
  },
  "reply_to": {
    "email": "[email protected]",
    "name": "Example Customer Service Team"
  },
  "subject": "Sendclean Test Email via Postman",
  "content": [
    {
      "type": "text/html",
      "value": "<p>Hello from Twilio SendGrid!</p><p>Sending with the email service trusted by developers and marketers for <strong>time-savings</strong>, <strong>scalability</strong>, and <strong>delivery expertise</strong>.</p><p>%open-track%</p>"
    }
  ],
  "attachments": [
    {
      "content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==",
      "filename": "index.html",
      "type": "text/html",
      "disposition": "attachment"
    }
  ],
  "categories": [
    "cake",
    "pie",
    "baking"
  ],
  "send_at": 1617260400,
  "batch_id": "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl",
  "asm": {
    "group_id": 12345,
    "groups_to_display": [
      12345
    ]
  },
  "ip_pool_name": "transactional email",
  "mail_settings": {
    "bypass_list_management": {
      "enable": false
    },
    "footer": {
      "enable": false
    },
    "sandbox_mode": {
      "enable": false
    }
  },
  "tracking_settings": {
    "click_tracking": {
      "enable": true,
      "enable_text": false
    },
    "open_tracking": {
      "enable": true,
      "substitution_tag": "%open-track%"
    },
    "subscription_tracking": {
      "enable": false
    }
  }
}

headers =:

{
  "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 200:
result = response.json()
print("Success:", result)
else:
print("Error:", response.status_code, response.text)

cURL:

curl -X POST \
  https://api.sendclean.com/v2/mail/send \
  -H 'Content-Type: application/json' \
  -d '{
  "personalizations": [
    {
      "to": [
        {
          "email": "[email protected]",
          "name": "John Doe"
        },
        {
          "email": "[email protected]",
          "name": "XYZ"
        }
      ],
      "cc": [
        {
          "email": "[email protected]",
          "name": "Jane Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jim Doe"
        }
      ],
      "subject": "John doe"
    },
    {
      "from": {
        "email": "[email protected]",
        "name": "Example Sales Team"
      },
      "to": [
        {
          "email": "[email protected]",
          "name": "Janice Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jordan Doe"
        }
      ]
    }

"from":

{
  "email": "[email protected]",
  "name": "Example Order Confirmation"
},

"reply_to":

{
  "email": "[email protected]",
  "name": "Example Customer Service Team"
},

"subject": "Sendclean Test Email via Postman",
"content": [

    {
      "type": "text/html",
      "value": "<p>Hello from Twilio SendGrid!</p><p>Sending with the email service trusted by developers and marketers for <strong>time-savings</strong>, <strong>scalability</strong>, and <strong>delivery expertise</strong>.</p><p>%open-track%</p>"
    }

"attachments": [

    {
      "content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==",
      "filename": "index.html",
      "type": "text/html",
      "disposition": "attachment"
    }

"categories": [
"cake",
"pie",
"baking"
"send_at": 1617260400,
"batch_id": "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl",

"asm":

{
  "group_id": 12345,
  "groups_to_display":
  [
    12345
  ]
},

"ip_pool_name": "transactional email",

"mail_settings":

{
  "bypass_list_management":
  {
    "enable": false
  },
  "footer":
  {
    "enable": false
  },
  "sandbox_mode":
  {
    "enable": false
  }
},

"tracking_settings":

{
  "click_tracking": {
    "enable": true,
    "enable_text": false
  },
  "open_tracking": {
    "enable": true,
    "substitution_tag": "%open-track%"
  },
  "subscription_tracking": {
    "enable": false
  }
}

}'

Node.js (axios):

const axios = require('axios');

const url = 'https://api.sendclean.com/v2/mail/send';

const payload = {
  "personalizations": [
    {
      "to": [
        {
          "email": "[email protected]",
          "name": "John Doe"
        },
        {
            "email": "[email protected]",
            "name": "XYZ"
        }
      ],
      "cc": [
        {
          "email": "[email protected]",
          "name": "Jane Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jim Doe"
        }
      ],
      "subject":"John doe"
    },
    {
      "from": {
        "email": "[email protected]",
        "name": "Example Sales Team"
      },
      "to": [
        {
          "email": "[email protected]",
          "name": "Janice Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jordan Doe"
        }
      ]
    }

"from":

{
  "email": "[email protected]",
  "name": "Example Order Confirmation"
},

"reply_to":

{
  "email": "[email protected]",
  "name": "Example Customer Service Team"
},

"subject": "Sendclean Test Email via Postman",
"content": [

    {
      "type": "text/html",
      "value": "<p>Hello from Twilio SendGrid!</p><p>Sending with the email service trusted by developers and marketers for <strong>time-savings</strong>, <strong>scalability</strong>, and <strong>delivery expertise</strong>.</p><p>%open-track%</p>"
    }

"attachments": [

    {
      "content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==",
      "filename": "index.html",
      "type": "text/html",
      "disposition": "attachment"
    }

"categories": [
"cake",
"pie",
"baking"
"send_at": 1617260400,
"batch_id": "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl",

"asm":

{
  "group_id": 12345,
  "groups_to_display":
  [
    12345
  ]
},

"ip_pool_name": "transactional email",

"mail_settings":

{
  "bypass_list_management":
  {
    "enable": false
  },
  "footer":
  {
    "enable": false
  },
  "sandbox_mode":
  {
    "enable": false
  }
},

"tracking_settings":

{
  "click_tracking": {
    "enable": true,
    "enable_text": false
  },
  "open_tracking": {
    "enable": true,
    "substitution_tag": "%open-track%"
  },
  "subscription_tracking": {
    "enable": false
  }
}

};

axios.post(url, payload, {
    headers: {
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log('Success:', response.data);
})
.catch(error => {
    console.error('Error:', error.response ? error.response.data : error.message);
});

PHP:

<?php

$url = 'https://api.sendclean.com/v2/mail/send';

$payload = json_decode('{
  "personalizations": [
    {
      "to": [
        {
          "email": "[email protected]",
          "name": "John Doe"
        },
        {
            "email": "[email protected]",
            "name": "XYZ"
        }
      ],
      "cc": [
        {
          "email": "[email protected]",
          "name": "Jane Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jim Doe"
        }
      ],
      "subject":"John doe"
    },
    {
      "from": {
        "email": "[email protected]",
        "name": "Example Sales Team"
      },
      "to": [
        {
          "email": "[email protected]",
          "name": "Janice Doe"
        }
      ],
      "bcc": [
        {
          "email": "[email protected]",
          "name": "Jordan Doe"
        }
      ]
    }

"from":

{
  "email": "[email protected]",
  "name": "Example Order Confirmation"
},

"reply_to":

{
  "email": "[email protected]",
  "name": "Example Customer Service Team"
},

"subject": "Sendclean Test Email via Postman",
"content": [

    {
      "type": "text/html",
      "value": "<p>Hello from Twilio SendGrid!</p><p>Sending with the email service trusted by developers and marketers for <strong>time-savings</strong>, <strong>scalability</strong>, and <strong>delivery expertise</strong>.</p><p>%open-track%</p>"
    }

"attachments": [

    {
      "content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==",
      "filename": "index.html",
      "type": "text/html",
      "disposition": "attachment"
    }

"categories": [
"cake",
"pie",
"baking"
"send_at": 1617260400,
"batch_id": "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl",

"asm":

{
  "group_id": 12345,
  "groups_to_display":
  [
    12345
  ]
},

"ip_pool_name": "transactional email",

"mail_settings":

{
  "bypass_list_management":
  {
    "enable": false
  },
  "footer":
  {
    "enable": false
  },
  "sandbox_mode":
  {
    "enable": false
  }
},

"tracking_settings":

{
  "click_tracking": {
    "enable": true,
    "enable_text": false
  },
  "open_tracking": {
    "enable": true,
    "substitution_tag": "%open-track%"
  },
  "subscription_tracking": {
    "enable": false
  }
}

  • }', true);

  • $ch = curl_init($url);

  • curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  • curl_setopt($ch, CURLOPT_POST, true);

  • curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

  • curl_setopt($ch, CURLOPT_HTTPHEADER, [

    'Content-Type: application/json'
    ]);

  • $response = curl_exec($ch);

  • $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  • curl_close($ch);

  • if ($httpCode == 200) {

  • $result = json_decode($response, true);

  • print_r($result);

  • } else {

    echo "Error: $httpCode - $response";

?>

Updated 2 months ago

Did this page help you?