Mail¶

Internal service for sending e-mails.

Rationale¶

Currently only one end-point is exposed for sending a single email to one user at a time, and only SERVICE principals is authorized to do so. The endpoint does take multiple mails as a bulk request, but they are sent individually

Email templates are pre-defined and are not controllable by clients.

Table of Contents¶

1. Examples

Description
Sending an email
Forwarding a support ticket to Jira
Changing e-mail settings

2. Remote Procedure Calls

Name	Description
`retrieveEmailSettings`	Changes an end-user's e-mail preferences
`sendDirect`	No description
`sendSupport`	Forwards a support ticket into Jira
`sendToUser`	Sends an email to an end-user based on a pre-defined template
`toggleEmailSettings`	Retrieves an end-user's e-mail preferences

3. Data Models

Name	Description
`EmailSettings`	No description
`EmailSettingsItem`	No description
`Mail`	No description
`Mail.GrantApplicationApproveMail`	No description
`Mail.GrantApplicationApproveMailToAdmins`	No description
`Mail.GrantApplicationRejectedMail`	No description
`Mail.GrantApplicationStatusChangedToAdmin`	No description
`Mail.GrantApplicationUpdatedMail`	No description
`Mail.GrantApplicationUpdatedMailToAdmins`	No description
`Mail.GrantApplicationWithdrawnMail`	No description
`Mail.JobEvents`	No description
`Mail.LowFundsMail`	No description
`Mail.NewCommentOnApplicationMail`	No description
`Mail.NewGrantApplicationMail`	No description
`Mail.ProjectInviteMail`	No description
`Mail.ResetPasswordMail`	No description
`Mail.StillLowFundsMail`	No description
`Mail.TransferApplicationMail`	No description
`Mail.UserLeftMail`	No description
`Mail.UserRemovedMail`	No description
`Mail.UserRemovedMailToUser`	No description
`Mail.UserRoleChangeMail`	No description
`Mail.VerificationReminderMail`	No description
`Mail.VerifyEmailAddress`	No description
`RetrieveEmailSettingsRequest`	No description
`SendDirectMandatoryEmailRequest`	No description
`SendRequestItem`	No description
`SendSupportEmailRequest`	No description
`RetrieveEmailSettingsResponse`	No description

Example: Sending an email¶

Frequency of use	Common
Actors	The UCloud/Core service user (`ucloud`)

Communication Flow: Kotlin

MailDescriptions.sendToUser.call(
    bulkRequestOf(SendRequestItem(
        mail = Mail.LowFundsMail(
            categories = listOf("u1-standard"), 
            projectTitles = listOf("Science Project"), 
            providers = listOf("ucloud"), 
            subject = "Wallets low on resource", 
        ), 
        mandatory = false, 
        receiver = "User#1234", 
        receivingEmail = null, 
        testMail = null, 
    )),
    ucloud
).orThrow()

/*
Unit
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as ucloud
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/mail/sendToUser" -d '{
    "items": [
        {
            "receiver": "User#1234",
            "mail": {
                "type": "lowFunds",
                "categories": [
                    "u1-standard"
                ],
                "providers": [
                    "ucloud"
                ],
                "projectTitles": [
                    "Science Project"
                ],
                "subject": "Wallets low on resource"
            },
            "mandatory": false,
            "receivingEmail": null,
            "testMail": null
        }
    ]
}'


# {
# }

Communication Flow: Visual

Example: Forwarding a support ticket to Jira¶

Frequency of use	Common
Actors	The UCloud/Core service user (`ucloud`)

Communication Flow: Kotlin

MailDescriptions.sendSupport.call(
    SendSupportEmailRequest(
        fromEmail = "foo@bar", 
        message = "Message", 
        subject = "Subject", 
    ),
    ucloud
).orThrow()

/*
Unit
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as ucloud
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/mail/support" -d '{
    "fromEmail": "foo@bar",
    "subject": "Subject",
    "message": "Message"
}'


# {
# }

Communication Flow: Visual

Example: Changing e-mail settings¶

Frequency of use	Common
Actors	An authenticated user (`user`)

Communication Flow: Kotlin

MailDescriptions.retrieveEmailSettings.call(
    RetrieveEmailSettingsRequest(
        username = null, 
    ),
    user
).orThrow()

/*
RetrieveEmailSettingsResponse(
    settings = EmailSettings(
        applicationStatusChange = true, 
        applicationTransfer = true, 
        grantApplicationApproved = true, 
        grantApplicationRejected = true, 
        grantApplicationUpdated = true, 
        grantApplicationWithdrawn = true, 
        jobStarted = false, 
        jobStopped = false, 
        lowFunds = true, 
        newCommentOnApplication = true, 
        newGrantApplication = true, 
        projectUserInvite = true, 
        projectUserRemoved = true, 
        userLeft = true, 
        userRoleChange = true, 
        verificationReminder = true, 
    ), 
)
*/
MailDescriptions.toggleEmailSettings.call(
    bulkRequestOf(EmailSettingsItem(
        settings = EmailSettings(
            applicationStatusChange = true, 
            applicationTransfer = true, 
            grantApplicationApproved = true, 
            grantApplicationRejected = true, 
            grantApplicationUpdated = true, 
            grantApplicationWithdrawn = true, 
            jobStarted = false, 
            jobStopped = false, 
            lowFunds = true, 
            newCommentOnApplication = true, 
            newGrantApplication = true, 
            projectUserInvite = true, 
            projectUserRemoved = true, 
            userLeft = true, 
            userRoleChange = true, 
            verificationReminder = false, 
        ), 
        username = null, 
    )),
    user
).orThrow()

/*
Unit
*/
MailDescriptions.retrieveEmailSettings.call(
    RetrieveEmailSettingsRequest(
        username = null, 
    ),
    user
).orThrow()

/*
RetrieveEmailSettingsResponse(
    settings = EmailSettings(
        applicationStatusChange = true, 
        applicationTransfer = true, 
        grantApplicationApproved = true, 
        grantApplicationRejected = true, 
        grantApplicationUpdated = true, 
        grantApplicationWithdrawn = true, 
        jobStarted = false, 
        jobStopped = false, 
        lowFunds = true, 
        newCommentOnApplication = true, 
        newGrantApplication = true, 
        projectUserInvite = true, 
        projectUserRemoved = true, 
        userLeft = true, 
        userRoleChange = true, 
        verificationReminder = false, 
    ), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/mail/retrieveEmailSettings?" 

# {
#     "settings": {
#         "newGrantApplication": true,
#         "grantApplicationUpdated": true,
#         "grantApplicationApproved": true,
#         "grantApplicationRejected": true,
#         "grantApplicationWithdrawn": true,
#         "newCommentOnApplication": true,
#         "applicationTransfer": true,
#         "applicationStatusChange": true,
#         "projectUserInvite": true,
#         "projectUserRemoved": true,
#         "verificationReminder": true,
#         "userRoleChange": true,
#         "userLeft": true,
#         "lowFunds": true,
#         "jobStarted": false,
#         "jobStopped": false
#     }
# }

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/mail/toggleEmailSettings" -d '{
    "items": [
        {
            "username": null,
            "settings": {
                "newGrantApplication": true,
                "grantApplicationUpdated": true,
                "grantApplicationApproved": true,
                "grantApplicationRejected": true,
                "grantApplicationWithdrawn": true,
                "newCommentOnApplication": true,
                "applicationTransfer": true,
                "applicationStatusChange": true,
                "projectUserInvite": true,
                "projectUserRemoved": true,
                "verificationReminder": false,
                "userRoleChange": true,
                "userLeft": true,
                "lowFunds": true,
                "jobStarted": false,
                "jobStopped": false
            }
        }
    ]
}'


# {
# }

curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/mail/retrieveEmailSettings?" 

# {
#     "settings": {
#         "newGrantApplication": true,
#         "grantApplicationUpdated": true,
#         "grantApplicationApproved": true,
#         "grantApplicationRejected": true,
#         "grantApplicationWithdrawn": true,
#         "newCommentOnApplication": true,
#         "applicationTransfer": true,
#         "applicationStatusChange": true,
#         "projectUserInvite": true,
#         "projectUserRemoved": true,
#         "verificationReminder": false,
#         "userRoleChange": true,
#         "userLeft": true,
#         "lowFunds": true,
#         "jobStarted": false,
#         "jobStopped": false
#     }
# }

Communication Flow: Visual

Remote Procedure Calls¶

`retrieveEmailSettings`¶

Changes an end-user’s e-mail preferences

Request	Response	Error
`RetrieveEmailSettingsRequest`	`RetrieveEmailSettingsResponse`	`CommonErrorMessage`

`sendDirect`¶

Request	Response	Error
`BulkRequest<SendDirectMandatoryEmailRequest>`	`Unit`	`CommonErrorMessage`

`sendSupport`¶

Forwards a support ticket into Jira

Request	Response	Error
`SendSupportEmailRequest`	`Unit`	`CommonErrorMessage`

NOTE: This endpoint is meant only for use by SDU and might not work well with other deployments.

`sendToUser`¶

Sends an email to an end-user based on a pre-defined template

Request	Response	Error
`BulkRequest<SendRequestItem>`	`Unit`	`CommonErrorMessage`

`toggleEmailSettings`¶

Retrieves an end-user’s e-mail preferences

Request	Response	Error
`BulkRequest<EmailSettingsItem>`	`Unit`	`CommonErrorMessage`

Data Models¶

`EmailSettings`¶

data class EmailSettings(
    val newGrantApplication: Boolean?,
    val grantApplicationUpdated: Boolean?,
    val grantApplicationApproved: Boolean?,
    val grantApplicationRejected: Boolean?,
    val grantApplicationWithdrawn: Boolean?,
    val newCommentOnApplication: Boolean?,
    val applicationTransfer: Boolean?,
    val applicationStatusChange: Boolean?,
    val projectUserInvite: Boolean?,
    val projectUserRemoved: Boolean?,
    val verificationReminder: Boolean?,
    val userRoleChange: Boolean?,
    val userLeft: Boolean?,
    val lowFunds: Boolean?,
    val jobStarted: Boolean?,
    val jobStopped: Boolean?,
)

Properties

newGrantApplication: Boolean?

grantApplicationUpdated: Boolean?

grantApplicationApproved: Boolean?

grantApplicationRejected: Boolean?

grantApplicationWithdrawn: Boolean?

newCommentOnApplication: Boolean?

applicationTransfer: Boolean?

applicationStatusChange: Boolean?

projectUserInvite: Boolean?

projectUserRemoved: Boolean?

verificationReminder: Boolean?

userRoleChange: Boolean?

userLeft: Boolean?

lowFunds: Boolean?

jobStarted: Boolean?

jobStopped: Boolean?

`EmailSettingsItem`¶

data class EmailSettingsItem(
    val username: String?,
    val settings: EmailSettings,
)

Properties

username: String?

settings: EmailSettings

`Mail`¶

sealed class Mail {
    abstract val subject: String

    class GrantApplicationApproveMail : Mail()
    class GrantApplicationApproveMailToAdmins : Mail()
    class GrantApplicationRejectedMail : Mail()
    class GrantApplicationStatusChangedToAdmin : Mail()
    class GrantApplicationUpdatedMail : Mail()
    class GrantApplicationUpdatedMailToAdmins : Mail()
    class GrantApplicationWithdrawnMail : Mail()
    class JobEvents : Mail()
    class LowFundsMail : Mail()
    class NewCommentOnApplicationMail : Mail()
    class NewGrantApplicationMail : Mail()
    class ProjectInviteMail : Mail()
    class ResetPasswordMail : Mail()
    class StillLowFundsMail : Mail()
    class TransferApplicationMail : Mail()
    class UserLeftMail : Mail()
    class UserRemovedMail : Mail()
    class UserRemovedMailToUser : Mail()
    class UserRoleChangeMail : Mail()
    class VerificationReminderMail : Mail()
    class VerifyEmailAddress : Mail()
}

Properties

subject: String

`Mail.GrantApplicationApproveMail`¶

data class GrantApplicationApproveMail(
    val projectTitle: String,
    val subject: String?,
    val type: String /* "applicationApproved" */,
)

Properties

projectTitle: String

subject: String?

type: String /* "applicationApproved" */ The type discriminator

`Mail.GrantApplicationApproveMailToAdmins`¶

data class GrantApplicationApproveMailToAdmins(
    val sender: String,
    val projectTitle: String,
    val subject: String?,
    val type: String /* "applicationApprovedToAdmins" */,
)

Properties

sender: String

projectTitle: String

subject: String?

type: String /* "applicationApprovedToAdmins" */ The type discriminator

`Mail.GrantApplicationRejectedMail`¶

data class GrantApplicationRejectedMail(
    val projectTitle: String,
    val subject: String?,
    val type: String /* "applicationRejected" */,
)

Properties

projectTitle: String

subject: String?

type: String /* "applicationRejected" */ The type discriminator

`Mail.GrantApplicationStatusChangedToAdmin`¶

data class GrantApplicationStatusChangedToAdmin(
    val status: String,
    val projectTitle: String,
    val sender: String,
    val receivingProjectTitle: String,
    val subject: String?,
    val type: String /* "applicationStatusChangedToAdmins" */,
)

Properties

status: String

projectTitle: String

sender: String

receivingProjectTitle: String

subject: String?

type: String /* "applicationStatusChangedToAdmins" */ The type discriminator

`Mail.GrantApplicationUpdatedMail`¶

data class GrantApplicationUpdatedMail(
    val projectTitle: String,
    val sender: String,
    val subject: String?,
    val type: String /* "applicationUpdated" */,
)

Properties

projectTitle: String

sender: String

subject: String?

type: String /* "applicationUpdated" */ The type discriminator

`Mail.GrantApplicationUpdatedMailToAdmins`¶

data class GrantApplicationUpdatedMailToAdmins(
    val projectTitle: String,
    val sender: String,
    val receivingProjectTitle: String,
    val subject: String?,
    val type: String /* "applicationUpdatedToAdmins" */,
)

Properties

projectTitle: String

sender: String

receivingProjectTitle: String

subject: String?

type: String /* "applicationUpdatedToAdmins" */ The type discriminator

`Mail.GrantApplicationWithdrawnMail`¶

data class GrantApplicationWithdrawnMail(
    val projectTitle: String,
    val sender: String,
    val subject: String?,
    val type: String /* "applicationWithdrawn" */,
)

Properties

projectTitle: String

sender: String

subject: String?

type: String /* "applicationWithdrawn" */ The type discriminator

`Mail.JobEvents`¶

data class JobEvents(
    val jobIds: List<String>,
    val jobNames: List<String>,
    val appTitles: List<String>,
    val events: List<String>,
    val subject: String?,
    val type: String /* "jobEvents" */,
)

Properties

jobIds: List<String>

jobNames: List<String>

appTitles: List<String>

events: List<String>

subject: String?

type: String /* "jobEvents" */ The type discriminator

`Mail.LowFundsMail`¶

data class LowFundsMail(
    val categories: List<String>,
    val providers: List<String>,
    val projectTitles: List<String>,
    val subject: String?,
    val type: String /* "lowFunds" */,
)

Properties

categories: List<String>

providers: List<String>

projectTitles: List<String>

subject: String?

type: String /* "lowFunds" */ The type discriminator

`Mail.NewCommentOnApplicationMail`¶

data class NewCommentOnApplicationMail(
    val sender: String,
    val projectTitle: String,
    val receivingProjectTitle: String,
    val subject: String?,
    val type: String /* "newComment" */,
)

Properties

sender: String

projectTitle: String

receivingProjectTitle: String

subject: String?

type: String /* "newComment" */ The type discriminator

`Mail.NewGrantApplicationMail`¶

data class NewGrantApplicationMail(
    val sender: String,
    val projectTitle: String,
    val subject: String?,
    val type: String /* "newGrantApplication" */,
)

Properties

sender: String

projectTitle: String

subject: String?

type: String /* "newGrantApplication" */ The type discriminator

`Mail.ProjectInviteMail`¶

data class ProjectInviteMail(
    val projectTitle: String,
    val subject: String?,
    val type: String /* "invitedToProject" */,
)

Properties

projectTitle: String

subject: String?

type: String /* "invitedToProject" */ The type discriminator

`Mail.ResetPasswordMail`¶

data class ResetPasswordMail(
    val token: String,
    val subject: String?,
    val type: String /* "resetPassword" */,
)

Properties

token: String

subject: String?

type: String /* "resetPassword" */ The type discriminator

`Mail.StillLowFundsMail`¶

data class StillLowFundsMail(
    val category: String,
    val provider: String,
    val projectTitle: String,
    val subject: String?,
    val type: String /* "stillLowFunds" */,
)

Properties

category: String

provider: String

projectTitle: String

subject: String?

type: String /* "stillLowFunds" */ The type discriminator

`Mail.TransferApplicationMail`¶

data class TransferApplicationMail(
    val senderProject: String,
    val receiverProject: String,
    val applicationProjectTitle: String,
    val subject: String?,
    val type: String /* "transferApplication" */,
)

Properties

senderProject: String

receiverProject: String

applicationProjectTitle: String

subject: String?

type: String /* "transferApplication" */ The type discriminator

`Mail.UserLeftMail`¶

data class UserLeftMail(
    val leavingUser: String,
    val projectTitle: String,
    val subject: String?,
    val type: String /* "userLeft" */,
)

Properties

leavingUser: String

projectTitle: String

subject: String?

type: String /* "userLeft" */ The type discriminator

`Mail.UserRemovedMail`¶

data class UserRemovedMail(
    val leavingUser: String,
    val projectTitle: String,
    val subject: String?,
    val type: String /* "userRemoved" */,
)

Properties

leavingUser: String

projectTitle: String

subject: String?

type: String /* "userRemoved" */ The type discriminator

`Mail.UserRemovedMailToUser`¶

data class UserRemovedMailToUser(
    val projectTitle: String,
    val subject: String?,
    val type: String /* "userRemovedToUser" */,
)

Properties

projectTitle: String

subject: String?

type: String /* "userRemovedToUser" */ The type discriminator

`Mail.UserRoleChangeMail`¶

data class UserRoleChangeMail(
    val subjectToChange: String,
    val roleChange: String,
    val projectTitle: String,
    val subject: String?,
    val type: String /* "userRoleChange" */,
)

Properties

subjectToChange: String

roleChange: String

projectTitle: String

subject: String?

type: String /* "userRoleChange" */ The type discriminator

`Mail.VerificationReminderMail`¶

data class VerificationReminderMail(
    val projectTitle: String,
    val role: String,
    val subject: String?,
    val type: String /* "verificationReminder" */,
)

Properties

projectTitle: String

role: String

subject: String?

type: String /* "verificationReminder" */ The type discriminator

`Mail.VerifyEmailAddress`¶

data class VerifyEmailAddress(
    val verifyType: String,
    val token: String,
    val subject: String?,
    val username: String?,
    val type: String /* "verifyEmailAddress" */,
)

Properties

verifyType: String

token: String

subject: String?

username: String?

type: String /* "verifyEmailAddress" */ The type discriminator

`RetrieveEmailSettingsRequest`¶

data class RetrieveEmailSettingsRequest(
    val username: String?,
)

Properties

username: String?

`SendDirectMandatoryEmailRequest`¶

data class SendDirectMandatoryEmailRequest(
    val recipientEmail: String,
    val mail: Mail,
)

Properties

recipientEmail: String

mail: Mail

`SendRequestItem`¶

data class SendRequestItem(
    val receiver: String,
    val mail: Mail,
    val mandatory: Boolean?,
    val receivingEmail: String?,
    val testMail: Boolean?,
)

Properties

receiver: String

mail: Mail

mandatory: Boolean?

receivingEmail: String?

testMail: Boolean?

`SendSupportEmailRequest`¶

data class SendSupportEmailRequest(
    val fromEmail: String,
    val subject: String,
    val message: String,
)

Properties

fromEmail: String

subject: String

message: String

`RetrieveEmailSettingsResponse`¶

data class RetrieveEmailSettingsResponse(
    val settings: EmailSettings,
)

Properties

settings: EmailSettings

Mail¶

Rationale¶

Table of Contents¶

Example: Sending an email¶

Example: Forwarding a support ticket to Jira¶

Example: Changing e-mail settings¶

Remote Procedure Calls¶

retrieveEmailSettings¶

sendDirect¶

sendSupport¶

sendToUser¶

toggleEmailSettings¶

Data Models¶

EmailSettings¶

EmailSettingsItem¶

Mail¶

Mail.GrantApplicationApproveMail¶

Mail.GrantApplicationApproveMailToAdmins¶

Mail.GrantApplicationRejectedMail¶

Mail.GrantApplicationStatusChangedToAdmin¶

Mail.GrantApplicationUpdatedMail¶

Mail.GrantApplicationUpdatedMailToAdmins¶

Mail.GrantApplicationWithdrawnMail¶

Mail.JobEvents¶

Mail.LowFundsMail¶

Mail.NewCommentOnApplicationMail¶

Mail.NewGrantApplicationMail¶

Mail.ProjectInviteMail¶

Mail.ResetPasswordMail¶

Mail.StillLowFundsMail¶

Mail.TransferApplicationMail¶

Mail.UserLeftMail¶

Mail.UserRemovedMail¶

Mail.UserRemovedMailToUser¶

Mail.UserRoleChangeMail¶

Mail.VerificationReminderMail¶

Mail.VerifyEmailAddress¶

RetrieveEmailSettingsRequest¶

SendDirectMandatoryEmailRequest¶

SendRequestItem¶

SendSupportEmailRequest¶

RetrieveEmailSettingsResponse¶

`retrieveEmailSettings`¶

`sendDirect`¶

`sendSupport`¶

`sendToUser`¶

`toggleEmailSettings`¶

`EmailSettings`¶

`EmailSettingsItem`¶

`Mail`¶

`Mail.GrantApplicationApproveMail`¶

`Mail.GrantApplicationApproveMailToAdmins`¶

`Mail.GrantApplicationRejectedMail`¶

`Mail.GrantApplicationStatusChangedToAdmin`¶

`Mail.GrantApplicationUpdatedMail`¶

`Mail.GrantApplicationUpdatedMailToAdmins`¶

`Mail.GrantApplicationWithdrawnMail`¶

`Mail.JobEvents`¶

`Mail.LowFundsMail`¶

`Mail.NewCommentOnApplicationMail`¶

`Mail.NewGrantApplicationMail`¶

`Mail.ProjectInviteMail`¶

`Mail.ResetPasswordMail`¶

`Mail.StillLowFundsMail`¶

`Mail.TransferApplicationMail`¶

`Mail.UserLeftMail`¶

`Mail.UserRemovedMail`¶

`Mail.UserRemovedMailToUser`¶

`Mail.UserRoleChangeMail`¶

`Mail.VerificationReminderMail`¶

`Mail.VerifyEmailAddress`¶

`RetrieveEmailSettingsRequest`¶

`SendDirectMandatoryEmailRequest`¶

`SendRequestItem`¶

`SendSupportEmailRequest`¶

`RetrieveEmailSettingsResponse`¶