Multiple recipients

Send the same message to several people in a single call. Each recipient gets their own link and, if you use SMS, their own code; a password, if any, is the same for everyone.

Prerequisites

A configured client and your credentials loaded: see Credentials and environments. Sending itself works as for a single recipient: see Send a message.

Example

Pass the list of recipients, then go through the answer: it contains one answer per recipient, with its own status and tracking number.

var recipients = new List<RecipientInfo>
{
    new RecipientInfo { Email = "recipient1@example.com" },
    new RecipientInfo { Email = "recipient2@example.com" },
    new RecipientInfo { Email = "recipient3@example.com" }
};

var args = new MutliRecipientArgs(
    endPointUri: endpoint, serial: serial, user: apiUser, psw: apiPassword,
    recipients: recipients, message: message, subject: subject,
    password: null, filesList: null,
    sendMode: SendMethodEnum.onlyEmail, getBackHtml: false,
    showSubject: true, getNotify: false,   // no notification on every opening
    cultureID: "en-CA", maximumOpenTime: 5, minutesExpiration: 10080);

var response = MessageHelper.MultiRecipientMessage(args);
if (response.Status != 200)
    throw new InvalidOperationException($"Sending refused, status {response.Status}");

foreach (var ra in response.RecipientsAnswer)
{
    if (ra.Answer?.Status == 200)
        SaveTracking(ra.Recipient.Email, ra.Answer.TrackingID);   // your own function
    else
        ReportFailure(ra.Recipient.Email, ra.Answer?.Status);    // your own function
}

recipients = [
    RecipientInfo(email="recipient1@example.com"),
    RecipientInfo(email="recipient2@example.com"),
    RecipientInfo(email="recipient3@example.com"),
]

answer = MessageHelper.multi_recipient_message(
    api_client=client, sems_client=sems_client,
    serial=serial, api_user=api_user, api_password=api_password,
    recipients=recipients, message=message, subject=subject,
    get_back_html=False, get_notify=False,  # no notification on every opening
    culture_id="en-CA", maximum_open_time=5,
)
if answer.status != 200:
    raise RuntimeError(f"Sending refused, status {answer.status}")

for ra in answer.recipients_answer:
    if ra.answer and ra.answer.status == 200:
        save_tracking(ra.recipient.email, ra.answer.tracking_id)  # your own function
    else:
        report_failure(ra.recipient.email, ra.answer.status if ra.answer else None)

$recipients = [
    new RecipientInfo(email: 'recipient1@example.com'),
    new RecipientInfo(email: 'recipient2@example.com'),
    new RecipientInfo(email: 'recipient3@example.com'),
];

$answer = MessageHelper::multiRecipientMessage(
    apiClient: $client, semsClient: $sems,
    serial: $serial, apiUser: $apiUser, apiPassword: $apiPassword,
    recipients: $recipients, message: $message, subject: $subject,
    getBackHtml: false, getNotify: false,   // no notification on every opening
    cultureId: 'en-CA', maximumOpenTime: 5,
);
if ($answer->status !== 200) {
    throw new RuntimeException('Sending refused, status ' . $answer->status);
}

foreach ($answer->recipientsAnswer as $ra) {
    if ($ra->answer !== null && $ra->answer->status === 200) {
        saveTracking($ra->recipient->email, $ra->answer->trackingId);   // your own function
    } else {
        reportFailure($ra->recipient->email, $ra->answer->status ?? null);
    }
}

Good to know

Point	Detail
One link per recipient	Each recipient gets their own link, and their own code if it is sent by SMS.
Password	If there is one (`password`), it is the same for every recipient.
Status per recipient	Check the overall status, then each recipient's: a send can succeed for some recipients and fail for others.
Tracking number	Keep it for each recipient: it is used to read the logs or to delete the message.
Notifications	With `getNotify` set to true, you are notified on every opening. For a send to many recipients, set it to false.

Warning

Do not log the links. The link given to a recipient grants access to the message: do not write it to your logs or to a database. Keep the tracking number instead. The recipient's address is personal information: protect it as such.

Common errors

Symptom	Likely cause	Solution
Overall status 200, but one recipient received nothing	Failure for that recipient only	Check their status in the answer, then their address.
Status 400	Empty recipient list, or invalid address	Check the list before sending.
Status 401 or 403	Credentials or licence	See Status codes.