Skip to content

LocaleHubOSS/swift-smtp

 
 

Repository files navigation

SwiftSMTP

SwiftSMTP bird

Note

This repository is a fork of Kitura's Swift-SMTP.

Since the project doesn't appear to be maintained anymore, this fork will contain bug fixes and features needed for the development of LocaleHub.

While we don't aim to revive the project, we will welcome any help from external contributors, and will reply to opened issues in pull requests in the best possible delays.

macOS Linux Apache 2 license Swift 5.2 and later Swift Package Manager compatible

Features

Swift client for the SMTP protocol:

  • Connect securely through SSL/TLS when needed
  • Authenticate with CRAM-MD5, LOGIN, PLAIN, or XOAUTH2
  • Send emails with local file, HTML, and raw data attachments
  • Add custom headers

Documentation

Swift Version

macOS & Linux: Swift 5.2 or above.

Installation

To install SwiftSMTP you can follow the tutorial published by Apple using the URL for the SwiftSMTP repo with the current version:

  1. In Xcode, select “File” → “Add Packages...”
  2. Enter https://github.com/LocaleHubOSS/swift-smtp.git

or you can add the following dependency to your Package.swift:

.package(url: "https://github.com/LocaleHubOSS/swift-smtp.git", from: "6.0.1")

Migration Guide

Version 5.0.0 brings breaking changes. See the quick migration guide here.

Usage

Initialize an SMTP instance:

import SwiftSMTP

let smtp = SMTP(
    hostname: "smtp.gmail.com",     // SMTP server address
    email: "user@gmail.com",        // username to login
    password: "password"            // password to login
)

TLS

Additional parameters of SMTP struct:

public init(hostname: String,
            email: String,
            password: String,
            port: Int32 = 587,
            tlsMode: TLSMode = .requireSTARTTLS,
            tlsConfiguration: TLSConfiguration? = nil,
            authMethods: [AuthMethod] = [],
            domainName: String = "localhost",
            timeout: UInt = 10)

By default, the SMTP struct connects on port 587 and sends mail only if a TLS connection can be established. It also uses a TLSConfiguration that uses no backing certificates. View the docs for more configuration options.

Send email

Create a Mail object and use your SMTP handle to send it. To set the sender and receiver of an email, use the User struct:

let drLight = Mail.User(name: "Dr. Light", email: "drlight@gmail.com")
let megaman = Mail.User(name: "Megaman", email: "megaman@gmail.com")

let mail = Mail(
    from: drLight,
    to: [megaman],
    subject: "Humans and robots living together in harmony and equality.",
    text: "That was my ultimate wish."
)

smtp.send(mail) { (error) in
    if let error = error {
        print(error)
    }
}

Add Cc and Bcc:

let roll = Mail.User(name: "Roll", email: "roll@gmail.com")
let zero = Mail.User(name: "Zero", email: "zero@gmail.com")

let mail = Mail(
    from: drLight,
    to: [megaman],
    cc: [roll],
    bcc: [zero],
    subject: "Robots should be used for the betterment of mankind.",
    text: "Any other use would be...unethical."
)

smtp.send(mail)

Send attachments

Create an Attachment, attach it to your Mail, and send it through the SMTP handle. Here's an example of how you can send the three supported types of attachments--a local file, HTML, and raw data:

// Create a file `Attachment`
let fileAttachment = Attachment(
    filePath: "~/img.png",          
    // "CONTENT-ID" lets you reference this in another attachment
    additionalHeaders: ["CONTENT-ID": "img001"]
)

// Create an HTML `Attachment`
let htmlAttachment = Attachment(
    htmlContent: "<html>Here's an image: <img src=\"cid:img001\"/></html>",
    // To reference `fileAttachment`
    related: [fileAttachment]
)

// Create a data `Attachment`
let data = "{\"key\": \"hello world\"}".data(using: .utf8)!
let dataAttachment = Attachment(
    data: data,
    mime: "application/json",
    name: "file.json",
    // send as a standalone attachment
    inline: false   
)

// Create a `Mail` and include the `Attachment`s
let mail = Mail(
    from: from,
    to: [to],
    subject: "Check out this image and JSON file!",
    // The attachments we created earlier
    attachments: [htmlAttachment, dataAttachment]
)

// Send the mail
smtp.send(mail)

/* Each type of attachment has additional parameters for further customization */

Send multiple mails

let mail1: Mail = //...
let mail2: Mail = //...

smtp.send([mail1, mail2],
    // This optional callback gets called after each `Mail` is sent.
    // `mail` is the attempted `Mail`, `error` is the error if one occured.
    progress: { (mail, error) in
    },

    // This optional callback gets called after all the mails have been sent.
    // `sent` is an array of the successfully sent `Mail`s.
    // `failed` is an array of (Mail, Error)--the failed `Mail`s and their corresponding errors.
    completion: { (sent, failed) in
    }
)

Acknowledgements

Inspired by Hedwig and Perfect-SMTP.

License

Apache v2.0

About

Swift SMTP client (forked from Kitura)

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Swift 100.0%