Articles in this section

Send-Time Designation


The MessageGears Send-Time Designation feature allows users the flexibility to send to Audiences at different times based on various recipient attributes without ever having to share recipient information outside of their on-premise data store.  This feature can be used at any time and does not require enabling any additional options or services.

Table of Contents

Sample Use Case

Job-level Settings

Recipient-level Settings



Sample Use Case

If you needed to send a promotional message to your audience at 9 AM local time, so that no recipient receives the promotion before their local store is opened. The earliest that a message can go out is 9 AM EST (in the easternmost area covered) and the latest a message can go out is 11 AM PST (in the westernmost area covered).

Note: This functionality is made available largely in two ways: job-level settings and recipient-level settings.


Job-level Settings

There are two job-level settings available via the job submit API:

  • earliestSendTime - the earliest time at which a recipient may be sent a message in this job. If a recipient is scheduled to go before this time, they will be re-scheduled to go at this time.
  • latestSendTime - the latest time at which a recipient may be sent a message. If a recipient is scheduled to go after this time, they are bounced with a bounce category of 24 (timeout). The furthest out a recipient may be scheduled is 36 hours after job submittal, the window between earliest and latest send time must be at least 1 hour

These job-level settings ensure that any ‘windowing’ capabilities are available. In the above use case, that means that the earliestSendTime would be 2019-06-20 09:00:00-04:00 for Eastern Daylight time (possibly 0-05:00 depending on the time of year). and the latestSendTime would be 2019-06-20 11:00-07:00. The Job window must be at least an hour long for the job to be successfully processed - any shorter windows will be rejected. This is to ensure there are no consumer expectations that Timezone-based-sendings will ensure faster delivery of messages.

If a recipient is scheduled to send outside of the job-level sendings, they will be injected for delivery within the job window - either at the earliestSendTime or 1 hour before the latestSendTime (to ensure that the message is sent within the sending window).

Recipient-level Settings

Additionally, for each channel, each recipient has the following attributes:

  • EmailSendTime
  • PushSendTime
  • SmsSendTime
  • EmailExpireTime
  • PushExpireTime
  • SmsExpireTime

The aim is to allow the user to specify when, per recipient, a channel message should be sent by and, for any given reason, NOT sent after. 

  • Job level expiration and earliest send times to override recipient settings.
  • If any of the Send Times are null or blank but the recipient value is present, it will result in a render error.
  • If a recipient is scheduled up to 24 hours in the past, the message will be sent immediately. If a recipient is scheduled greater than 24 hours in the past, the message will not be sent.

These times can take one of the following two formats:

  • A future offset based on when the job hits the MessageGears Cloud, which must be formatted as “+03:00”
    • This must always be a plus sign as this is a generic offset for the future, not a timezone offset.  Using a negative sign will be interpreted as attempting to deliver an email in the past.
    • It must always be six characters long.
      • The plus sign and colon are required.
      • A leading zero is required if the value is less than 10 hours.
  • A timestamp with timezone, which must be formatted like “2019-06-20 16:00:00-04:00”
    • In this format, we're using a timezone offset, so "-04:00" refers to Eastern Daylight Time.
    • The timezone offset is required, and it must include a colon, two digits for the hour, and two digits for the minute. The space is required between the date and the time.


  1. Ensure that each member of your audience has a locale or timezone associated with them in their audience data
  2. Set the earliest and latest times that a recipient could receive a message in this mailing
  3. When selecting and creating the audience, either:
      • Use a future offset approach to ensure that recipients in CST receive +01:00, those in MST receive +02:00, and those in PST receive +03:00
      • Set an explicit send time based on their locale using the format above, ensuring that each recipient receives the message on their selected channel at the right time
  1. Send the campaign
  2. In reporting, use the scheduledRecipients parameter in Bulk Job Summary to aid in reporting, to understand how many recipients have yet to be delivered that are intended to go out in the job
Note: The ‘send times’ in this article refer to when a recipient would be injected into our rendering and delivery process for sending. The actual time the recipient receives the message may be affected by volume through the MG system at that time, render time or deliverability concerns.


Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.