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 -> SendEmailMessageResult

    Parameters

    input

    Parameters used to send an email message

    Return Value

  • Delete multiple email messages using a list of identifiers.

    Email Messages can only be deleted in batches of 100 or less. Anything greater will throw a LimitExceededError.

    Declaration

    Swift

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

    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 results of the delete operation:

    • status:
      • Success - All draft email messages succeeded to delete.
      • Partial - Only a partial amount of draft messages succeeded to delete. Result includes two lists; one containing success results and the other containing failure results.
      • Failure - All draft email messages failed to delete. Result contains a list of identifiers of draft email messages that failed to delete.
    • successItems - A list of the result items containing identifiers of the draft email messages that were successfully deleted.
    • failureItems - A list of the id and errorType of each draft email message that failed to be deleted.

  • Delete an email message.

    Declaration

    Swift

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

    Parameters

    id

    Identifier of the email message to be deleted.

    Return Value

    • Success: Result containing the identifier of the email message that was deleted.
    • Failure: SudoEmailError.

  • Update multiple email messages using a list of identifiers.

    Email Messages can only be updated in batches of 100 or less. Anything greater will throw a LimitExceededError.

    Declaration

    Swift

    func updateEmailMessages(
    withInput input: UpdateEmailMessagesInput
) async throws -> BatchOperationResult<UpdatedEmailMessageSuccess, EmailMessageOperationFailureResult>

    Parameters

    input

    Parameters used to update a list of email messages.

    Return Value

    The results of the updates:

    • status:
      • Success - All email messages succeeded to update.
      • Partial - Only a partial amount of messages succeeded to update. Result includes a list of the identifiers of the email messages that failed and succeeded to update.
      • Failure - All email messages failed to update. Result contains a list of identifiers of email messages that failed to update.
    • successItems - A list of the id, createdAt and updatedAt of each message that successfully updated
    • failureItems - A list of the id, and errorType of each message that failed to be updated

  • 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. 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<DeleteEmailMessageSuccessResult, EmailMessageOperationFailureResult>

    Parameters

    input

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

    Return Value

    The results of the delete operation:

    • status:
      • Success - All email messages succeeded to delete.
      • Partial - Only a partial amount of draft messages succeeded to delete. Result includes two lists; one containing success results and the other containing failure results.
      • Failure - All email messages failed to delete. Result contains a list of identifiers of email messages that failed to delete.
    • successItems - A list of result items containing the identifiers of the email messages that were successfully deleted.
    • failureItems - A list of the id and errorType of each email message that failed to be deleted.

  • Create a custom EmailFolder

    Declaration

    Swift

    func createCustomEmailFolder(
    withInput input: CreateCustomEmailFolderInput
) async throws -> EmailFolder

    Parameters

    input

    Input parameters used to create a custom EmailFolder.

    Return Value

    • The newly created EmailFolder

  • 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. Primarily intended to be used to perform a domain search which occurs prior to provisioning an email address.

    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 list of all of the configured domains. Primarily intended to be used as part of performing an email send operation in order to fetch all domains configured for the service so that appropriate encryption decisions can be made.

    Declaration

    Swift

    func getConfiguredEmailDomains(_ 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 identical API calls. 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

    @available(*, deprecated, message: "Use getEmailMessageWithBody instead to retrieve email message data")
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.

  • Lists the metadata and content of all draft email messages for the user.

    Declaration

    Swift

    func listDraftEmailMessages() async throws -> [DraftEmailMessage]

    Return Value

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

  • Lists the metadata and content of all draft email messages for the specified email address identifier.

    Declaration

    Swift

    func listDraftEmailMessagesForEmailAddressId(emailAddressId: String) async throws -> [DraftEmailMessage]

    Parameters

    emailAddressId

    The identifier of the email address associated with the draft email messages.

    Return Value

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

  • Lists the metadata of all draft messages for the user.

    Declaration

    Swift

    func listDraftEmailMessageMetadata() 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.

  • Lists the metadata of all draft messages for the user.

    Declaration

    Swift

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

    Parameters

    emailAddressId

    The identifier of the email address associated with the draft email messages.

    Return Value

    • An array of draft email message metadata or an empty array if no matching draft email messages can 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.

  • 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, 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, 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, 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.

  • Subscribe to email message updated events.

    Throws

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

    Declaration

    Swift

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

    Parameters

    id

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

    Email message update 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()