API reference

Send email

POST /api/v1/json/bulk/email sends a subject and body to up to 2,000 addresses from a registered email sender. HTML bodies are detected automatically.

POST/api/v1/json/bulk/email

Send one email to one or more addresses. Requires an API key (see Authentication).

Parameters

Parameter	Type	Description
`from` Required	string	An email sender registered and active on your account (the address you send from). Matched case-insensitively. Example: `[email protected]`
`to` Required	string \| string[]	One address, or an array of 1 to 2,000 addresses. Example: `["[email protected]", "[email protected]"]`
`subject` Required	string	1 to 200 characters. Example: `Your order is confirmed`
`email_body` Required	string	The body, 1 to 100,000 characters. HTML is detected automatically and sent as HTML; anything else is sent as plain text. Example: `<p>Thanks for your order. Order ZM4821 is confirmed.</p>`
`reply_to` Optional	string	Address replies should go to, when it differs from the sender. Example: `[email protected]`
`user_reference_id` Optional	string	Your own reference for this send. A reference already used for the same address and sender is refused. Example: `order-10421`
`callback_url` Optional	string	HTTPS URL that receives a POST with the delivery status of each email. See Delivery webhooks. Example: `https://example.com/webhooks/unicom360/email`
`source` Optional	string	A label for the system that sent the email, shown in your reports. Example: `shop`

fromRequiredstring: An email sender registered and active on your account (the address you send from). Matched case-insensitively.
Example: [email protected]
toRequiredstring | string[]: One address, or an array of 1 to 2,000 addresses.
Example: ["[email protected]", "[email protected]"]
subjectRequiredstring: 1 to 200 characters.
Example: Your order is confirmed
email_bodyRequiredstring: The body, 1 to 100,000 characters. HTML is detected automatically and sent as HTML; anything else is sent as plain text.
Example: <p>Thanks for your order. Order ZM4821 is confirmed.</p>
reply_toOptionalstring: Address replies should go to, when it differs from the sender.
Example: [email protected]
user_reference_idOptionalstring: Your own reference for this send. A reference already used for the same address and sender is refused.
Example: order-10421
callback_urlOptionalstring: HTTPS URL that receives a POST with the delivery status of each email. See Delivery webhooks.
Example: https://example.com/webhooks/unicom360/email
sourceOptionalstring: A label for the system that sent the email, shown in your reports.
Example: shop

Example request

curl -X POST https://api.unicom360.com/api/v1/json/bulk/email \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]", "[email protected]"],
    "subject": "Your order is confirmed",
    "email_body": "<p>Thanks for your order. Order ZM4821 is confirmed.</p>",
    "reply_to": "[email protected]",
    "callback_url": "https://example.com/webhooks/unicom360/email"
  }'

Responses

200 acceptedjson

{
  "api_reference": "1764184470578998353",
  "data": [
    {
      "message_id": "48213",
      "status": "ACKNOWLEDGED",
      "email_address": "[email protected]"
    },
    {
      "message_id": "48214",
      "status": "ACKNOWLEDGED",
      "email_address": "[email protected]"
    }
  ],
  "message": "successful",
  "success": true
}

One entry per address, but not in the order given once a request has more than ten addresses. Match each entry to its address by email_address (the address exactly as you sent it), never by position. message_id is numeric here (a string in this response, a number in the delivery callback: compare them as strings).

200 business errorjson

{
  "message": "Insufficient bundle",
  "success": false,
  "api_reference": "1764184470578998353"
}

Other messages: Invalid Sender, Sender not allowed, Invalid Recipient Limit, duplicate user reference id, Invalid parameters provided (an address that is not valid, a subject over 200 characters, or an empty or oversized body refuses the whole request).

400 validation errorjson

{
  "message": "Missing required keys: [\"email_body\"]",
  "success": false,
  "api_reference": "1764184470578998353"
}

Before you send

from is an email sender registered on your account and approved, matched case-insensitively. Register the addresses you send from in the portal before the first send.
Each address in to must look like an address (something, an @, something). One bad address refuses the whole request with Invalid parameters provided; validate on your side first.
email_body is sent as HTML when it contains HTML, otherwise as plain text. There is no field to force one or the other; if a plain-text body contains angle brackets you want kept literal, encode them as entities.
Each email costs one unit from your email bundle, whatever its size, and the bundle must cover every address in the request.
user_reference_id works as it does for SMS: a reference already used for the same address and sender is refused, which makes retries safe. See Your own reference.

Tracking delivery

Give a callback_url to be told when each email is SENT, DELIVERED or FAILED. The callback's message_id is this response's message_id as a number. See Delivery webhooks.