SudoEmailClient

public protocol SudoEmailClient : AnyObject

Client used to interface with the Sudo Email Platform service.

It is recommended to code to this interface, rather than the implementation class (DefaultSudoEmailClient) as the implementation class is only meant to be used for initializing an instance of the client.

Lifecycle

  • Removes all keys associated with this client, resets any cached data, cleans up subscriptions, and purges any pending operations.

    It is important to note that this will clear ALL cached data related to all sudo services.

    Declaration

    Swift

    func reset() throws

Mutations

  • Provision an email address.

    Declaration

    Swift

    func provisionEmailAddress(withInput input: ProvisionEmailAddressInput) async throws -> EmailAddress

    Parameters

    input

    Parameters used to provision an email address, including:

    Return Value

    • Success: Successfully provisioned email. This address will return in all lower-case.
    • Failure: SudoEmailError.

  • Deprovision an email address.

    Declaration

    Swift

    func deprovisionEmailAddress(_ id: String) async throws -> EmailAddress

    Parameters

    id

    Unique identifier of the email address to be deprovisioned.

    Return Value

  • Update the metadata of an email address.

    Declaration

    Swift

    func updateEmailAddressMetadata(withInput input: UpdateEmailAddressMetadataInput) async throws -> String

    Return Value

    • Success: the id of the updated email address
    • Failure: SudoEmailError.

  • Send an email message using [RFC 6854] supersedes RFC 822 data. Email messages sent to in-network recipients (i.e. email addresses that exist within the Sudo Platform) will be sent end-to-end encrypted.

    Declaration

    Swift

    func sendEmailMessage(withInput input: SendEmailMessageInput) async throws -> String

    Parameters

    input

    Parameters used to send an email message

    Return Value

    • Success: Identifier of the email message that is being sent.
    • Failure: SudoEmailError.

  • Delete the email messages identified by the list of ids.

    Declaration

    Swift

    func deleteEmailMessages(withIds ids: [String]) async throws -> BatchOperationResult<String>

    Parameters

    ids

    A list of one or more identifiers of the email messages to be deleted. There is a limit of 100 email message ids per API request. Exceeding this will cause an error to be thrown.

    Return Value

    The status of the delete: Success - All email messages succeeded to delete. Partial - Only a partial amount of messages succeeded to delete. Includes a list of the identifiers of the email messages that failed and succeeded to delete. Failure - All email messages failed to delete.

  • Delete an email message.

    Declaration

    Swift

    func deleteEmailMessage(withId id: String) async throws -> String?

    Parameters

    id

    Identifier of the email message to be deleted.

    Return Value

    • Success: Identifier of the email message that was deleted.
    • Failure: SudoEmailError.

  • Update the email messages identified by a list of ids.

    Declaration

    Swift

    func updateEmailMessages(withInput input: UpdateEmailMessagesInput) async throws -> BatchOperationResult<String>

    Parameters

    input

    Input parameters used to update a list of email messages

    Return Value

    The status of the updates: Success - All email messages succeeded to update. Partial - Only a partial number of messages succeeded to update. Includes a list of the identifiers of the email messages that failed and succeeded to update. Failure - All email messages failed to update.

  • Create a draft email message in RFC 6854 (supersedes RFC 822)(https://tools.ietf.org/html/rfc6854) format.

    Declaration

    Swift

    func createDraftEmailMessage(
    withInput input: CreateDraftEmailMessageInput
) async throws -> DraftEmailMessageMetadata

    Parameters

    input

    Input parameters used to create a draft email message.

    Return Value

    • The metadata associated with the created draft email message

  • Update a draft email message in RFC 6854 (supersedes RFC 822)(https://tools.ietf.org/html/rfc6854) format.

    Declaration

    Swift

    func updateDraftEmailMessage(
    withInput input: UpdateDraftEmailMessageInput
) async throws -> DraftEmailMessageMetadata

    Parameters

    input

    Input parameters used to update a draft email message.

    Return Value

    • The metadata associated with the updated draft email message

  • Delete the draft email messages identified by the list of ids. Draft email messages can only be deleted in batches of 10. Anything greater will throw a LimitExceededError. Any draft email message ids that do not exist will be marked as success. Any emailAddressId that is not owned or does not exist, will throw an error.

    Declaration

    Swift

    func deleteDraftEmailMessages(
    withInput input: DeleteDraftEmailMessagesInput
) async throws -> BatchOperationResult<String>

    Parameters

    input

    Input parameters used to delete a list of draft email messages.

    Return Value

    The status of the delete: Success - All draft email messages succeeded to delete. Partial - Only a partial number of the draft email messages were deleted successfully. Includes a list of the identifiers of the draft email messages that failed and succeeded to delete. Failure - All draft email messages failed to delete.

  • Imports cryptographic keys from a key archive.

    Declaration

    Swift

    func importKeys(archiveData: Data) throws

    Parameters

    archiveData

    Key archive data to import the keys from.

Queries

  • Check the availability of email address combinations.

    Declaration

    Swift

    func checkEmailAddressAvailability(withInput input: CheckEmailAddressAvailabilityInput) async throws -> [String]

    Parameters

    input

    The local parts and domains of the email addresses to check. All upper-case characters will be normalized and returned as lower-case.

    Return Value

    • Success: Returns the fully qualified email addresses, filtering out used email addresses. Email addresses are returned in all lower-case.
    • Failure: SudoEmailError.

  • Get a list of the supported email domains from the service.

    Declaration

    Swift

    func getSupportedEmailDomains(_ cachePolicy: CachePolicy) async throws -> [String]

    Parameters

    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of similar exact API calls.

    Return Value

  • Get a EmailAddress record using the id parameter. If the email address cannot be found, nil will be returned.

    Declaration

    Swift

    func getEmailAddress(withInput input: GetEmailAddressInput) async throws -> EmailAddress?

    Parameters

    input

    Input object specifying the email address to be retrieved.

    Return Value

    • Success: Email address associated with id, or nil if the email address cannot be found.
    • Failure: SudoEmailError.

  • Get a list of email addresses. If no email addresses can be found, an empty list will be returned.

    Declaration

    Swift

    func listEmailAddresses(withInput input: ListEmailAddressesInput) async throws -> ListOutput<EmailAddress>

    Parameters

    input

    Parameters used to retrieve a list of provisioned email addresses.

    Return Value

    • Success: Email addresses associated with user, or empty list if no email address can be found.
    • Failure: SudoEmailError.

  • Get a list of provisioned email addresses owned by the Sudo identified by sudoId.

    Declaration

    Swift

    func listEmailAddressesForSudoId(
    withInput input: ListEmailAddressesForSudoIdInput
) async throws -> ListOutput<EmailAddress>

    Parameters

    input

    Parameters used to retrieve a list of provisioned email addresses for a sudoId.

    Return Value

    • Success: Email addresses associated with the sudo specified by sudoId, or empty list if no email address can be found.
    • Failure: SudoEmailError.

  • Get a list of public info objects associated with the provided email addresses.

    If no email addresses or public keys can be found, an empty list will be returned.

    Declaration

    Swift

    func lookupEmailAddressesPublicInfo(withInput: LookupEmailAddressesPublicInfoInput) async throws -> [EmailAddressPublicInfo]

    Parameters

    emailAddresses

    A list of email address strings in format ‘local-part@domain’.
    cachePolicy

    Determines how the data will be fetched. Default usage is remoteOnly.

    Return Value

    • An array of public information objects or an empty array if no email addresses or public keys can be found.

  • Get a list of email folders associated with the email address identified by emailAddressId.

    Declaration

    Swift

    func listEmailFoldersForEmailAddressId(
    withInput input: ListEmailFoldersForEmailAddressIdInput
) async throws -> ListOutput<EmailFolder>

    Parameters

    input

    Parameters used to retrieve a list of email folders for an emailAddressId.

    Return Value

    • An array of email folders or an empty array if no matching email folders can be found.

  • Get an email message using the id parameter. If the email message cannot be found, nil will be returned.

    Declaration

    Swift

    func getEmailMessage(withInput input: GetEmailMessageInput) async throws -> EmailMessage?

    Parameters

    id

    Identifier of the email message to be retrieved.
    cachePolicy

    Determines how the data is fetched. When using cacheOnly, please be aware that this will only return cached results of similar exact API calls.

    Return Value

    • Success: Email message associated with id, or nil if the email message cannot be found.
    • Failure: SudoEmailError.

  • Get a list of all email messages for the user. If no email messages can be found, an empty list will be returned.

    Declaration

    Swift

    func listEmailMessages(
    withInput: ListEmailMessagesInput
) async throws -> ListAPIResult<EmailMessage, PartialEmailMessage>

    Parameters

    input

    Parameters used to retrieve a list of email messages.

    Return Value

    • A ListAPIResult.ListSuccessResult or a ListAPIResult.ListPartialResult result containing either a list of EmailMessages or PartialEmailMessages respectively. Returns an empty list if no email messages can be found.

  • Get a list of email messages for the provided email address. If no email messages can be found, an empty list will be returned.

    Declaration

    Swift

    func listEmailMessagesForEmailAddressId(
    withInput: ListEmailMessagesForEmailAddressInput
) async throws -> ListAPIResult<EmailMessage, PartialEmailMessage>

    Parameters

    input

    Parameters used to retrieve a list of email messages.

    Return Value

    • A ListAPIResult.ListSuccessResult or a ListAPIResult.ListPartialResult result containing either a list of EmailMessages or PartialEmailMessages respectively. Returns an empty list if no email messages can be found.

  • Get a list of email messages for the provided email folder. If no email messages can be found, an empty list will be returned.

    Declaration

    Swift

    func listEmailMessagesForEmailFolderId(
    withInput: ListEmailMessagesForEmailFolderIdInput
) async throws -> ListAPIResult<EmailMessage, PartialEmailMessage>

    Parameters

    input

    Parameters used to retrieve a list of email messages.

    Return Value

    • A ListAPIResult.ListSuccessResult or a ListAPIResult.ListPartialResult result containing either a list of EmailMessages or PartialEmailMessages respectively. Returns an empty list if no email messages can be found.

  • Get the raw RFC 6854 (supersedes RFC 822) data of an email message associated with the messageId.

    If no email message exists for messageId, SudoEmailError.noEmailMessageRFC822Available will be returned.

    Declaration

    Swift

    func getEmailMessageRfc822Data(withInput input: GetEmailMessageRfc822DataInput) async throws -> Data

    Parameters

    messageId

    Message identifier associated with the RFC 6854 data attempting to be fetched.

    Return Value

  • Get the body and attachment data of an EmailMessage

    Declaration

    Swift

    func getEmailMessageWithBody(withInput input: GetEmailMessageWithBodyInput) async throws -> EmailMessageWithBody?

    Parameters

    input

    Parameters used to retrieve the data of the email message.

    Return Value

    • The data associated with the EmailMessage or null if the email message cannot be found.

  • Get a draft email message that has been saved previously.

    Declaration

    Swift

    func getDraftEmailMessage(withInput input: GetDraftEmailMessageInput) async throws -> DraftEmailMessage?

    Parameters

    input

    Parameters used to retrieve a draft email message

    Return Value

    • The draft email message identified by id or undefined if not found.

  • Get the list of draft email message metadata for the specified email address.

    Declaration

    Swift

    func listDraftEmailMessageMetadata(emailAddressId: String) async throws -> [DraftEmailMessageMetadata]

    Return Value

    • An array of draft email message metadata or an empty array if no matching draft email messages can be found.

  • getConfigurationData() Asynchronous

    Get the configuration data for the email service.

    Declaration

    Swift

    func getConfigurationData() async throws -> ConfigurationData

  • Export the cryptographic keys to a key archive.

    Declaration

    Swift

    func exportKeys() throws -> Data

    Return Value

    Key archive data.

  • Blocks the addresses given from sending to the user

    Declaration

    Swift

    func blockEmailAddresses(addresses: [String]) async throws -> BatchOperationResult<String>

    Parameters

    addresses

    Array of addresses to block as strings

    Return Value

    The status of the blocking: Success - All addresses were succesfully blocked. Partial - Only a partial number of the addresses were blocked successfully. Includes a list of the addresses that failed and succeeded to be blocked. Failure - All addresses failed to be blocked.

  • Unblocks the addresses given from sending to the user

    Declaration

    Swift

    func unblockEmailAddresses(addresses: [String]) async throws -> BatchOperationResult<String>

    Parameters

    addresses

    Array of addresses to unblock as strings

    Return Value

    The status of the unblocking: Success - All addresses were succesfully unblocked. Partial - Only a partial number of the addresses were unblocked successfully. Includes a list of the addresses that failed and succeeded to be unblocked. Failure - All addresses failed to be unblocked.

  • Unblocks the hashed addresses given from sending to the user

    Declaration

    Swift

    func unblockEmailAddressesByHashedValue(hashedValues: [String]) async throws -> BatchOperationResult<String>

    Parameters

    hashedValues

    Array of addresses to unblock as strings

    Return Value

    The status of the unblocking: Success - All addresses were succesfully unblocked. Partial - Only a partial number of the addresses were unblocked successfully. Includes a list of the addresses that failed and succeeded to be unblocked. Failure - All addresses failed to be unblocked.

  • Get email address blocklist for logged in user

    Declaration

    Swift

    func getEmailAddressBlocklist() async throws -> [UnsealedBlockedAddress]

    Return Value

    The list of blocked email addresses

Subscriptions

  • Subscribe to email message creation events.

    Throws

    SudoEmailError if an error occurs while setting up the initial connection the subscription.

    Declaration

    Swift

    func subscribeToEmailMessageCreated(
    withDirection direction: EmailMessage.Direction?,
    resultHandler: @escaping ClientCompletion<EmailMessage>
) async throws -> SubscriptionToken?

    Parameters

    direction

    Direction of the email message events to watch for. If nil, both directions will be watched.
    resultHandler

    Email message created event.

    Return Value

    SubscriptionToken object to cancel the subscription. On denitialization, the subscription will be cancelled.

  • Subscribe to email message deleted events.

    Throws

    SudoEmailError if an error occurs while setting up the initial connection the subscription.

    Declaration

    Swift

    func subscribeToEmailMessageDeleted(
    withId id: String?,
    resultHandler: @escaping ClientCompletion<EmailMessage>
) async throws -> SubscriptionToken?

    Parameters

    id

    Identifier of a specific deletion event to watch for. If nil, all deletion events will be handled.
    resultHandler

    Email message deleted event.

    Return Value

    SubscriptionToken object to cancel the subscription. On denitialization, the subscription will be cancelled.

  • Unsubscribe all subscribers from receiving sudo email notifications

    Declaration

    Swift

    func unsubscribeAll()