Wooxy API v.3.0

Send Batch Email

The Send Batch Email method allows you to send bulk emails to multiple recipients (up to 100 recipients) in a single request and manually select the domain from which they will be sent. This method also allows you to send personalized templates using Twig without the need to generate templates for each individual contact on your side.

IMPORTANT: In a single request, you can send communications to no more than 100 contacts at once.

Request

POST

https://api.wooxy.com/v3/mailer/batch-send

IMPORTANT: Do not send more than 10 concurrent API requests.

Body Example

                                        {
            "from": {
                "email": "notify@domain.co",
                "name": "fromName",
            },
            "replyTo": {
                "email": "notify@domain.co",
                "name": "replyToName",
            },
            "recipients": [
                {
                    "email": "testcontact@domain.co",
                    "name": "testContact",
                    "variables": [
                        {
                            "name": "someString",
                            "value": "User Name"
                        },
                       {
                            "name": "someDate",
                            "value": "2012-03-03"
                        }
                    ]
                },
                {
                    "email": "testcontact+1@domain.co"
                },
                {
                    "email": "testcontact+2@domain.co"
                }
            ],
            "subject": "Hello {{someString}}",
            "html": "<p>Hello {{someString}}<\/p>",
            "text": "Hello {{someString}}",
            "tags": ["YOUR_BATCH_TAGS",],
            "headers": {"X-Additional-Header": "additional-header-value"},
            "priority": 1,
            "variables": [
                       {
                            "name": "someString",
                            "value": "User Name"
                       },
                       {
                            "name": "someDate",
                            "value": "2012-03-03"
                       }
             ],
            "ignoreHard": false,
            "ignoreComplaint": false,
            "ignoreUnsubscribe": false,
            "ignoreBlackList": false,
        }

Parameters

Title	Type	Description
from required	string	An array of sender information. You can use only domain name verified in your account.
from.name optional	string	Optional from name to be used.
from.email required	string	The sender email address.
replyTo optional	string	An array of optional reply-to information. Email address used to compose the email’s Custom “Reply-To” header. If no reply-to address provided “From” will be used instead.
replyTo.name optional	string	The optional display name to use for the reply-to recipient.
replyTo.email required	string	The email address of the reply-to recipient.
recipients required	array	An array of recipients information. You can send to 100 different recipients in one request. You can add an array of data to be used in the templates to personalize the messages.
recipients.email required	string	The email address of the recipient.
recipients.name optional	string	The optional display name to use for the recipient.
recipients.variables optional	array	An array of unique variables for each contact. Please, take in account variables usage priorities is case of conflicting variables: `First Priority`: Variable from API request; `Second Priority`: Variable from the Content Custom Variables; `Third Priority`: Variable from the selected list. Important! Variables passed to the contact have the highest priority when used in the template.
recipients.variables.name required	string	The name of the contact's unique variable. `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
recipients.variables.value required	string\|integer\|boolean	The value of the contact's unique variable. Variable value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly.
subject required	string	The message subject.
html required	string	The full HTML or text content to be sent. Use double curly brackets (Example: {{someData}}) to mark variables in the content for Twig to personalize the content.
text optional	string	Optional plain text content to be sent. If no text version of the email is provided, Wooxy will generate it from the HTML copy.
tags optional	array	An array of strings that can be used to tag a message. Statistics are accumulated using tags, and the number of tags available depends on the plan. All tags you want to use must be created in advance on the platform in the tags section. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.
headers optional	object	Optional extra headers to add to the message (most headers are allowed). `IMPORTANT` Headers should start with `X-`.
priority optional	integer	Add priority parameter to the outgoing emails to avoid delivery delays for important messages due to large promo campaigns in queue. INFO Defaults: Priority 1 is default value; You can have up to 5 priority levels; Priority level over 5 will be rounded to 5.
variables optional	array	An array of common variables that will be applied to the sending for each individual recipient. Please, take in account variables usage priorities is case of conflicting variables: `First Priority`: Variable from API request; `Second Priority`: Variable from the Content Custom Variables; `Third Priority`: Variable from the selected list.
variables.name required	string	The name of the variable that will be applied in the template for each contact. `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
variables.value required	string\|integer\|boolean	The value of the variable that will be applied in the template for each contact. Variable value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly.
ignoreHard optional	boolean	By setting the filter to true, your message will bypass all unsubscribes and suppressions in all lists. `IMPORTANT`That parameter is only available for the Enterprise Plan. Request the parameter activation from the support team via support@wooxy.com.
ignoreComplaint optional	boolean	By setting the filter to true, your message will bypass the bounce list. The spam report and global unsubscribe lists will be checked and respected. `IMPORTANT`That parameter is only available for the Enterprise Plan. Request the parameter activation from the support team via support@wooxy.com.
ignoreUnsubscribe optional	boolean	By setting the filter to true, your message will bypass the spam report list. The bounce and global unsubscribe lists will be checked and respected. `IMPORTANT`That parameter is only available for the Enterprise Plan. Request the parameter activation from the support team via support@wooxy.com.
ignoreBlackList optional	boolean	By setting the filter to true, your message will bypass the global unsubscribe list. The spam report and bounce lists will be checked and respected. `IMPORTANT`That parameter is only available for the Enterprise Plan. Request the parameter activation from the support team via support@wooxy.com.

Response

                                        {
  "result": true,
  "success": {
    "testcontact@domain.co": "Message ID",
    "testcontact+1@domain.co": "Message ID",
    "testcontact+2@domain.co": "Message ID"
  },
  "failed": {
    "testcontact+3@domain.co": "Error description"
  }
}

Parameters

Title	Type	Description
result	boolean	Indicated that the query was successful or not: true: The value indicates that the query was successful. false: The value indicates that the query wasn't successful.
success	object	An object containing all successful email sends, including the contacts to whom the emails were sent and the `messageId` of each send.
success.email	string	The email of the contact to whom the successful send was made.
success[messageId]	string	The Message ID of a successful send to a specific contact.
failed	object	An object with failed email sends, including the contact email that could not receive the communication and the reason why the send was unsuccessful.
failed.email	string	The email of the contact to whom the communication could not be sent.
failed[error]	string	The error that prevented the sending to a specific contact.

Method Errors

                                        {
  "result": false,
  "errors": [
    "Error description"
  ]
}

Error
"Argument contacts must be an array of objects"
"Argument variables must be an array of arrays with \"name\" and \"value\" fields"
"name of variable must be a string"
"name of variable can not be empty"
"variable \"{name}\" is reserved and can not be added as custom variable"
"invalid name of variable {name}"
"Argument templateId must be a non-empty string"
"Template with id {templateId} not found"
"Argument tags must be an array"
"Tag name must be a non-empty string"
"Tags should be 50 characters or less"
"Any tags starting with an underscore are reserved for internal use and will cause errors"
"Tag %s is not registered in account tags"
"Argument variables must be an array of arrays with \"name\" and \"value\" fields"
"variable \"{name}\" is reserved and can not be added as custom variable"
"Argument ignoreHard must be a boolean"
"You are not allowed to use ignoreHard option"
"Argument ignoreComplaint must be a boolean"
"You are not allowed to use ignoreComplaint option"
"Argument ignoreUnsubscribe must be a boolean"
"You are not allowed to use ignoreUnsubscribe option"
"Argument ignoreBlackList must be a boolean"
"You are not allowed to use ignoreBlackList option"
"Payment required"
"Fail to publish message"
"No contacts to handle"
"Twig syntax error: {error}"
"Invalid authorization token!"
"Internal server error"
"Bad Request"
"no matches found for access token {accessToken}"
"user {id} not enabled"
"no data found for key {userId}"
"access token check failed for key/secret $key/$accessToken"
"Argument {argument} required"
"from field must contain email and name fields"
"email parameter at from field required"
"Argument email must be a non-empty string"
"Invalid RFC2822 email {email}"
"name parameter at from field must be a string"
"Each recipient must contain email field"
"Amount of recipients must be less or equal 100"
"Parameter "email" at to field is required"
"Name of recipient must be a string"
"replyTo field must contain email and name fields"
"email parameter at replyTo field required"
"Final subject line is empty"
"Final HTML content is empty"
"Argument text must be a string"
"Argument headers must be an array with header-names as keys and header-values as values"
"header name must be a non-empty string"
"header value must be a non-empty string"
"Argument priority must be an integer"
"Argument priority must be between 1 and 5"
You cannot use domain {domain} as sender domain in from email"
"You cannot use from email {email} by domain verification policy. Use {senderEmail} instead"
"No recipients to handle"
"Argument recipients must be an array of objects"
"Parameter \"email\" at to field is required"
"Duplicated as {email}"
"name parameter at replyTo field must be a string"
"Argument subject must be a non-empty string"
"Argument html must be a non-empty string"
"You cannot use domain {domain} as sender domain in from email"

Code Examples

PHP

                $accessToken = 'YOUR_API_KEY';
$url = 'https://api.wooxy.com/v3/mailer/addresses-batch';

$body = json_encode([
    "from" => [
        "email" => "notify@domain.c",
        "name" => "fromName"
    ],
    "replyTo" => [
        "email" => "notify@domain.c",
        "name" => "replyToName"
    ],
    "recipients" => [
        [
            "email" => "testcontact@domain.co",
            "name" => "testContact",
            "variables" => [
                [
                    "name" => "someVar",
                    "value" => "someVarValue"
                ],
                [
                    "name" => "someDate",
                    "value" => "2012-03-03"
                ]
            ]
        ],
        [
            "email" => "testcontact+1@domain.co"
        ],
        [
            "email" => "testcontact+2@domain.co"
        ]
    ],
    "subject" => "Hello {{email}}",
    "html" => "<p>Hello {{email}}</p>",
    "text" => "Hello {{email}}",
    "tags" => ["YOUR_BATCH_TAGS"],
    "headers" => [
        "X-Additional-Header" => "additional-header-value"
    ],
    "priority" => 1,
    "variables" => [
        [
            "name" => "someDate",
            "value" => "2012-03-03"
        ]
    ],
    "ignoreHard" => false,
    "ignoreComplaint" => false,
    "ignoreUnsubscribe" => false,
    "ignoreBlackList" => false
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body)
]);

$result = curl_exec($ch);

if ($result === false) {
    echo 'cURL error: ' . curl_error($ch) . PHP_EOL;
} else {
    echo $result . PHP_EOL;
}

curl_close($ch);