Schedule Send

Schedule a message to be sent at a specified date and time in the future.

The Email SDK supports scheduling draft email messages to be sent at a specified time in the future. The Email Service will periodically check for messages that have been scheduled whose sendAt times have passed and will send them as normal. Your runtime instance can be configured to specify how often you want this check to occur. More frequent checks will increase the chances that the messages will be sent as close to the specified time as possible. If a message fails to send for any reason, it may also be retried a configurable number of times.

Scheduling a Draft Message

To schedule a draft message to be sent in the future, call the scheduleSendDraftMessage method. This method takes in the id of the draft message to schedule, the emailAddressId of the email address that owns the draft message and the sendAt timestamp of when to send the message. The call will return a record of the scheduled message with useful information including the sendAt timestamp, the updatedAt timestamp and the state of the scheduled message. There are four states that the scheduled message may be in:

State	Meaning
SCHEDULED	The message has been scheduled and will be sent once the sendAt time has passed.
FAILED	The message failed to send after the sendAt passed.
SENT	The message has successfully been sent. It should appear in the SENT folder of the user's email address.
CANCELLED	The message was cancelled and will not be sent.

TypeScript

// Obtain the draftId and emailAddressId however makes sense for your application
const id = draft.id
const emailAddressId = senderEmailAddress.id
const sendAt = DateTime.now().plus({ day: 1 }).toJSDate() // Adjust this to the required time in the future
try {
    const scheduledDraftMessage = await emailClient.scheduleSendDraftMessage({
        id,
        emailAddressId,
        sendAt,
    })
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the draftId and emailAddressId however makes sense for your application
let id = draft.id
let emailAddressId = senderEmailAddress.id
let sendAt = Date().addingTimeInterval(+86400) // Adjust this to the required time in the future
let input = ScheduleSendDraftMessageInput(
    id: id,
    emailAddressId: emailAddressId,
    sendAt: sendAt
)
do {
    let scheduledDraftMessage = try await emailClient.scheduleSendDraftMessage(withInput: input)
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the draftId and emailAddressId however makes sense for your application
val id = draft.id
val emailAddressId = senderEmailAddress.id
val sendAt = Date(Date().time + Duration.ofDays(1).toMillis()) // Adjust this to the required time in the future
launch {
    try {
        val input = ScheduleSendDraftMessageInput(
            id,
            emailAddressId,
            sendAt,
        )
        val scheduledDraftMessage = withContext(Dispatchers.IO) {
            emailClient.scheduleSendDraftMessage(input)
        }
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}

Cancelling a Scheduled Draft Message

A previously scheduled draft message can be cancelled at any time before it's specified sendAt time by calling the cancelScheduledDraftMessage method. This method takes the draft message id and the emailAddressId of the email address that owns the draft and will return the draft id on successful cancellation.

TypeScript

// Obtain the draftId and emailAddressId however makes sense for your application
const id = draft.id
const emailAddressId = senderEmailAddress.id
try {
    const cancelledScheduledDraftId = await client.cancellScheduledDraftMessage({
        id,
        emailAddressId,
    })
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the draftId and emailAddressId however makes sense for your application
let id = draft.id
let emailAddressId = senderEmailAddress.id
let input = CancelScheduledDraftMessageInput(
    id: id,
    emailAddressId: emailAddressId,
)
do {
    let cancelledScheduledDraftId = try await emailClient.cancelScheduledDraftMessage(withInput: input)
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the draftId and emailAddressId however makes sense for your application
val id = draft.id
val emailAddressId = senderEmailAddress.id
launch {
    try {
        val input = CancelScheduledDraftMessageInput(
            id,
            emailAddressId,
        )
        val cancelledScheduledDraftId = withContext(Dispatchers.IO) {
            emailClient.cancelScheduledDraftMessage(input)
        }
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}

Listing Scheduled Draft Messages

To retrieve a list of previously scheduled draft messages, call the listScheduledDraftMessagesForEmailAddressId method. This method takes the emailAddressId , an optional filters argument to filter your results and pagination arguments (See Pagination for details). It will return a list of Scheduled Draft Messages.

TypeScript

// Obtain the emailAddressId however makes sense for your application
const emailAddressId = senderEmailAddress.id
const filter: ScheduledDraftMessageFilterInput = {
    state: {
        notEqual: ScheduledDraftMessageState.CANCELLED,
    },
}
try {
    const listResult = await emailClient.listScheduledDraftMessagesForEmailAddressId({
        emailAddressId,
        filter,
    })
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the emailAddressId however makes sense for your application
let emailAddressId = senderEmailAddress.id
let input = ListScheduledDraftMessagesForEmailAddressIdInput(
    emailAddressId: emailAddressId,
    limit: nil,
    nextToken: nil,
    filter: ScheduledDraftMessageFilter(
        state: ScheduledDraftMessageStateFilter.notEqual(.cancelled)
    )
)
do {
    let listResult = try await emailClient.listScheduledDraftMessagesForEmailAddressId(withInput: input)
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the draftId and emailAddressId however makes sense for your application
val emailAddressId = senderEmailAddress.id
launch {
    try {
        vval input = ListScheduledDraftMessagesForEmailAddressIdInput(
            emailAddressId,
            filter = ScheduledDraftMessageFilterInput(
                state = NotEqualStateFilter(
                    notEqual = ScheduledDraftMessageState.CANCELLED,
                ),
            ),
        )
        val listResult = withContext(Dispatchers.IO) {
            emailClient.listScheduledDraftMessagesForEmailAddressId(input)
        }
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}

The listScheduledDraftMessagesForEmailAddressId method currently supports filtering results by state. The above example would list all results where the state is not equal to CANCELLED , but there are other options as defined below:

Filter Option	Type	Meaning
equal	ScheduledDraftMessageState	Return only results that match the given state.
oneOf	Array<ScheduledDraftMessageState>	Return only results that match one of the given states.
notEqual	ScheduledDraftMessageState	Return only results that do not match the given state.
notOneOf	Array<ScheduledDraftMessageState>	Return only results that do not match any of the given states.