MailerSend Developers

Handling Maintenance Modes

Introduction

System downtime can have a significant impact on email sending operations. Downtimes, whether planned or unexpected, can disrupt the flow of emails, potentially causing delays, missed opportunities, or confusion. For this reason, efficient handling of maintenance mode is not just a technical necessity but a business imperative. Handling the disruption to minimize its impact on end-users involves several steps, from receiving and processing webhooks for maintenance events, temporarily storing emails to be sent via API during maintenance, resuming email sending after receiving the maintenance end webhook, handling SMTP retries during maintenance, managing inbound email retries, and utilizing multiple or backup ESPs during maintenance.

In this guide, we will take a detailed look at each step, providing practical advice and best practices to help you navigate maintenance mode so that you can maintain trust and reliability with your users.

Understanding Webhooks for Maintenance Events

In the context of maintenance events for MailerSend, webhooks signal the start and end of a maintenance period. These are the maintenance.start and maintenance.end webhooks.

When a maintenance period begins, MailerSend will send a maintenance.start webhook to all the connected systems. Similarly, when the maintenance period ends, a maintenance.end webhook is sent out.

These webhooks are crucial as they could trigger various processes to handle the maintenance period efficiently. Setting up and receiving these webhooks involves providing MailerSend with a URL in your system where the webhooks should be sent. You can do so via the Create a webhookopen in new window endpoint and selecting the appropriate maintenance events.

Processing Webhooks for Maintenance Events

Once you’ve set up your system to receive webhooks, the next step is to process them appropriately. This involves parsing the incoming webhook payload, validating it to ensure it's from a trusted source, and performing appropriate actions based on the webhook type.

Here is a general outline of how you might set up a PHP script to handle this:

<?php

function isValidWebhook($signature, $requestContent, $signingSecret)
{
    $computedSignature = hash_hmac('sha256', $requestContent, $signingSecret);
    return hash_equals($signature, $computedSignature);
}

function processWebhook($signingSecret)
{
    // Read the Signature header from the request
    $signature = $_SERVER['HTTP_SIGNATURE'];

    // Read the request content
    $requestContent = file_get_contents('php://input');

    // Verify the webhook request
    if (!isValidWebhook($signature, $requestContent, $signingSecret)) {
        header('HTTP/1.1 401 Unauthorized');
        exit;
    }

    // Parse the request content as JSON
    $data = json_decode($requestContent, true);

    // Process the webhook based on the event type
    switch ($data['event']) {
        case 'maintenance.start':
            // TODO: Implement logic for starting maintenance
            break;

        case 'maintenance.end':
            // TODO: Implement logic for ending maintenance
            break;

        // TODO: Add more cases for other event types as needed
    }
  
    header('HTTP/1.1 200 OK');
}

// TODO: Replace with your actual signing secret
$signingSecret = 'your_signing_secret_here';

// Process the incoming webhook
processWebhook($signingSecret);

In this script, isValidWebhook($data) is a placeholder for a function that would validate the incoming webhook. Most ESPs provide a way to validate incoming webhooks, such as a unique signature in the headers or a list of source IPs you can verify against. Webhook requests made by MailerSend include a Signature headeropen in new window, which is automatically generated upon the webhook creation.

Similarly, handleStartMaintenance($data) and handleEndMaintenance($data) are placeholders for functions that would handle the start and end of maintenance, respectively. The actions taken in these functions will depend on your specific needs. On top of this code, you would need additional error handling and security measures in a production system. Additionally, as in this example, you might use a framework or a library to handle incoming HTTP requests rather than handling everything manually.

Temporarily Storing Emails to be Sent via API During Maintenance

The maintenance.start webhook signals the beginning of a maintenance period and the need to alter normal email-sending operations. This would typically involve temporarily storing outgoing emails.

The process would look like this:

  1. Receiving the maintenance.start webhook: Set up your application to receive this webhook and trigger the process of temporarily storing outgoing emails.
  2. Pausing immediate email sending: Pause all email-sending operations while the maintenance is ongoing.
  3. Storing the email data: Securely store each outgoing email sent during maintenance. This includes the recipient(s), subject line, body content additional headers, and any attachments.
  4. Logging and monitoring: Keeping track of all operations during this phase is crucial. Implement logging mechanisms to record all actions, such as the number of emails stored, any issues encountered, and when the maintenance mode started. This information can be invaluable for troubleshooting and post-maintenance analysis.

Resuming Email Sending After Maintenance

Once the maintenance period ends, MailerSend sends a maintenance.end webhook. This signals your system to resume normal operations, including sending out any emails stored during the maintenance period.

Here is an outline of the steps involved:

  1. Receiving the maintenance.end webhook: Set up your application to receive this webhook and resume email-sending operations.
  2. Preparation for email sending: Gradually increase the sending rate to avoid sudden spikes in email traffic.
  3. Retrieving stored emails: Retrieve the emails stored during the maintenance period.
  4. Prioritizing emails: If there are many emails to be sent, it might be beneficial to prioritize them. For example, time-sensitive emails could be sent first, followed by less urgent ones. You can set up tags within your emails to categorize them by priority.
  5. Sending the emails: Send out the retrieved emails. Handling errors or issues during this process, such as emails that fail to send, is essential. Consider implementing a retry mechanism for these failed emails.
  6. Monitoring and logging: Keep track of the emails sent, any errors or issues, and how long it takes to clear the backlog of stored emails. This information can be helpful for future planning and for improving your handling of maintenance periods.

Remember, the goal is not just to resume email-sending operations but to do so in a way that minimizes the impact on MailerSend’s servers and the email recipients. If done correctly, the end of the maintenance period should be a smooth transition back to normal operations, with minimal disruption to your email communication.

Handling SMTP Retries During Maintenance

During a maintenance period, your application might attempt to send an email and receive an SMTP error from MailerSend, indicating that the operation failed.

In this case, MailerSend returns a 421 error code with the message "Service isn't available, try again later" during maintenance. This is a temporary SMTP error, indicating that the email might be able to be sent later when MailerSend is available again. Here are the key points to look out for during SMTP maintenance.

  1. Detecting and identifying SMTP errors: Your system should be set up to detect when an SMTP error occurs and should check if the status code is 421. This involves checking the status code of the SMTP response and the associated message.
  2. Queuing emails for retry: If a 421 error is detected, your system should queue the email for a retry later. The strategy for this can vary—some systems use a fixed delay before retrying, while others use an exponential backoff strategy to increase the delay with each failed attempt gradually.
  3. Resuming retries after maintenance: Once the maintenance period ends and a maintenance.end webhook is received, your system should resume retrying any emails that encountered the 421 error during the maintenance. This process should be done gradually to avoid overwhelming MailerSend with a sudden influx of emails.
  4. Handling other SMTP errors: Aside from the 421 error, your system might encounter other SMTP errors during maintenance. Your system should classify these errors based on whether they are permanent or temporary and handle them accordingly.
  5. By appropriately handling the 421 and other SMTP errors, your system can ensure that as many emails as possible are sent, even in the face of temporary setbacks.

Utilizing Multiple/Backup Email Service Providers (ESPs) During Maintenance

Having multiple backup Email Service Providers (ESPs) is an excellent strategy to ensure your system's email operations continue uninterrupted, even when MailerSend goes into maintenance mode. It involves setting up multiple ESPs and routing emails through a different provider when your primary one is unavailable.

  1. Choosing and setting up a backup ESP: The first step is to choose a backup ESP. This could be any ESP that fits your feature, cost, volume, and reliability needs. Once chosen, configure the SMTP settings, and set up any necessary authentication and webhooks, if the backup ESP supports it
  2. Routing emails to the backup ESP: When MailerSend goes into maintenance mode and sends a maintenance.start webhook, your application should change the SMTP settings in your email sending code
  3. Monitoring and logging: Keep track of the emails sent through the backup ESP, and any errors or issues as well as when the switch happened. This information can be helpful for future planning and improving your handling of maintenance periods
  4. Switching back to the primary ESP: When the maintenance period ends and the maintenance.end webhook is received, your system should switch back to sending emails through the primary ESP. This should be done carefully to avoid any disruptions to your email operations.

Conclusion

Maintenance periods are inevitable when working with any kind of email platform. With careful planning and innovative strategies, you can minimize disruptions and maintain a smooth email experience for your users. Each component ensures that your system responds appropriately to maintenance events. By implementing these strategies, you can ensure that your email operations are resilient, robust, and reliable, regardless of the maintenance schedules of MailerSend.

Last Updated: