Email Campaigns

From WHMCS Documentation

Using Email Campaigns lets you send form field email messages to clients based on specific criteria. With a queueing process and email delivery provider integration, Email Campaigns lets you transparently process many campaigns at once. It also has retry capabilities to protect against network availability issues.

In WHMCS 8.0, this replaced the less fully-featured Mass Mail Tool at Clients > Mass Mail.

Create a New Campaign

Use Email Campaigns to send an email message to a group of clients. You can choose to send the message to all of your clients or limit it to clients that meet specific criteria.

To create a new email campaign:

  1. Go to Utilities > Email Campaigns and click Create New Campaign.
  2. Enter an email campaign name.
  3. Choose the type of email to send, which sets the criteria to use to select the email's recipients.
    • By default, the email type is General, which only lets you filter on the client status or country criteria. You can also choose:
      • Product/Service, to filter by product-related criteria.
      • Addon, to filter by addon-related criteria.
      • Domain, to filter by domain-related criteria.
    • If you do not want to filter clients by a specific criteria, leave that filter unchanged and it will be ignored.
  4. Update Client Criteria to filter by the correct Client Group, Country, Language, and Client Status. To do this, select one or more items from the lists. For example, if you select United States for Country to only send the email campaign to clients in the US.
  5. Click Compose Message.
    Composing an Email Campaign Message
  6. Check the From information and list of recipients to ensure that they're correct.
  7. Enter any CC or BCC recipients as a comma-separated list.
  8. Enter a subject and body message for the email.
    • The bottom of the interface lists values that you can display in the message, like displaying the client's name or an Unsubscribe link.
    • Click Message Preview to preview your message.
    • Click Enable/Disable Rich-Text Editor to use the rich-text editor.
  9. Add any Attachments.
  10. Check Marketing Email? to prevent sending this message to anyone who has opted out of marketing emails.
  11. Check Save Message and enter a name to save the message for future use.
  12. Use Start Date/Time to schedule when the email will send.
  13. Click Save Draft to save the message. Click Send Campaign to send the message immediately or, if you set one, at the scheduled time.

When you compose the email, you will see the first 50 clients matching your selected criteria in the To field, so that you can review the recipients. However, the system will send each email individually. The receiver will not see any other client addresses in the To field of the copy they receive.

Filtering by Country

You can send mass mailings to only clients in specific countries. To do this, select the countries as in the example below.

Filtering by Country


You can use contacts to send a copy of a message to a different email address. When sending one-time or mass mails, clients and users with the General email notification option enabled will receive a copy of any General mass mails that you send to the master account holder.

If the contact has Product email notifications enabled, they will receive copies of mass mails with the Product/Service email type. If they have Domain email notifications enabled, they will receive copies of mass mails with the Domain email type.

The recipients list doesn't include contacts when composing the message. However, if the master account appears in the list and the contact has the appropriate email permissions, they will receive a copy.

Mailing Lists

You can create a mailing list using custom client fields. To do this, navigate to Configuration () > System Settings > Custom Fields. You can use the Dropdown or TickBox field types. If you choose Dropdown, make sure to enter the necessary options.

Custom Mailing List Field

This will display as a client filter option. You can only send this to clients who have chosen to receive these mailings.

Sending to Mailing List

Working with Email Campaigns

After you create a campaign, it will appear in the list, with information about its status, sending progress, and other details. You can also perform some actions.

Email Campaigns

Internal Queue vs. External Send Requests

You may see campaigns that display 100% completion for Sending Progress but that have Sending as their Status. This is due to differences between the internal email campaign process queue and external send requests.

When WHMCS starts sending a campaign, it will batch messages to the recipients (determined by your criteria) in increments of 50. A batch of these messages goes into a process queue every five minutes, at maximum, or with the frequency at which your cron runs if it runs less frequently. For example, if your cron runs every three minutes, the batches would go to the process queue every five minutes. If your cron runs every ten minutes, the batches would go to the process queue every ten minutes.

  • Sending Progress reports the status of this process. WHMCS sends the items in the process queue as API requests or emails to your mail provider. This occurs at a rate of 25 recipients per minute, depending on the frequency of your cron command.
  • The Sending Report contains the status of the external send requests, including a list of failures. See Sending Report below.

Sending Report

Click View Sending Report under Sending Progress to view a report on the external send request status for the campaign.

Email Campaigns Sending Report

This report includes the time at which the campaign started sending and the completion date if there is one. Below this, you can view a sending progress bar and a list of failed recipients.

The progress bar increments as messages are accepted by the mail provider. If a message isn't accepted by the mail provider or there are failures to contact the mail server, WHMCS will automatically retry sending the message three times. After three retries, that message is added to the list of failures.

Managing Campaigns

To manage your campaigns, click Manage Campaign under Actions. Then, choose one of the options below:

Editing and Pausing Campaigns

If you created an Email Campaign and saved it as a draft, or if you scheduled it for the future but it hasn't started sending yet, you can edit it. To do this, click Edit in the list of campaigns.

If the Email Campaign has started sending, you can't edit it. You can, however, click Pause to stop it from continuing to queue more messages. Queued emails will continue to send after the campaign is paused.

Click Pause to pause further queuing-up of messages for sending under this campaign. You can then click Resume here to resume queueing. Queued emails will continue to send after the campaign is paused.

Message Preview

Click Message Preview to view a preview of the campaign message. To update this message for queued campaigns, click Edit.


Click Delete to delete the campaign. This will prevent future campaign emails from sending and will remove the campaign from the list.

Common Problems

No Recipients

If the criteria for an email includes no recipients, the system can't send it. Go back and select a different set of criteria.

Most commonly, this is because you selected a client group or language to which you have assigned no clients.

Invalid Email Addresses

For any recipients with invalid email addresses, the system will abort sending the message. The system will not retry sending to these addresses.

External Problems

If the system experiences external problems during sending, such as invalid SMTP details or problems with the SMTP server, it will retry sending indefinitely, with a new attempt every five minutes. If this occurs, pause the campaign, fix the external issue, and then click Resume.