Concepts: Task Emails

Introduction

Agility Blue allows you to create and send emails that are linked directly to tasks in order to maintain the context of the conversation associated with a task. With the available scripting cmdlets, you have the opportunity to automate a variety of needs at different stages of email processes. For example, you could intercept an outbound email prior to it getting sent and automatically add or remove recipients using an event trigger, you could set up a script to automatically compose and send an email when a task is completed based on specific criteria, or you could setup a scheduled job to generate a task email on a recurring schedule.

Composing and Sending a Task Email

There are 4 steps involved with composing and sending a task email:

1) Create the email message

Create a new email using the Add-EmailMessage cmdlet (separate multiple recipients with a semicolon). You can also add Cc and Bcc recipients as desired.

$emailMessage = @{
    To = "someone1@somewhere.com; someone2@somewhere.com"
    FromAddress = "someone@somewhere.com"
    FromName = "Someone's Name"
    Subject = "Email was created from a script"
    Body = "<p>This is an email created from a script.</p><p>It accepts html that email clients allow.</p>"
}

$createdEmailMessage = Add-EmailMessage $emailMessage

Email “From” Information

Please note that all outbound email from Agility Blue will always come from a single managed email account. The information you are adding here for the “from” line is placed into the body of the email for the benefit of the recipients to know who created the message, however, the email is not being sent directly from the address you put here.

2) Add contact relationships to the email message

Add contact relationships to the email message with the Add-EmailMessageContacts cmdlet. This is important in order for the UI to populate the To/Cc/Bcc fields when replying to the email.

# The list of recipients (contacts must already exist prior to doing 
# this step and you need to know their ids)
$emailMessageContacts = @(
  @{
    EmailMessageId = $createdEmailMessage.EmailMessageId
    ContactId = 1 
    RelationshipTypeId = 1
  }
)

Add-EmailMessageContacts $emailMessageContacts | Out-Null

Use the following table to determine which RelationshipTypeId to use for the contact:

3) Create the email to task association

Create a task email with the Add-TaskEmailMessage cmdlet to link the email with an existing task.

$taskEmailMessage = @{
  TaskId = 29877 # put your task id in here
  EmailMessageId = $createdEmailMessage.EmailMessageId
}

# Create the link
Add-TaskEmailMessage -Entry $taskEmailMessage | Out-Null

4) Send the email message

Use the Send-EmailMessage cmdlet to send the email.

Send-EmailMessage -Id $createdEmailMessage.EmailMessageId | Out-Null

Email Logs and Status

All inbound and outbound email is logged and the status of these emails can be observed within the Notification Logs page in the app. After issuing a command to send the email, give the system about 30 seconds to prepare and send your email. After which, you can check the notification log or the email message within the task on the status. If the status indicates Sent, your email was successfully sent. Any other message would indicate it has not yet been sent. Contact support if you need help troubleshooting a message that did not get sent.