Swiftpack.co - Package - Kitura/Swift-SMTP

Swift-SMTP

Swift-SMTP bird

Swift SMTP client.

Build Status macOS Linux Apache 2

Features

  • 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 4.0.3, Swift 4.1 and Swift 4.1.2

Installation

You can add SwiftSMTP to your project using Swift Package Manager. If your project does not have a Package.swift file, create one by running swift package init in the root directory of your project. Then open Package.swift and add SwiftSMTP as a dependency. Be sure to add it to your desired targets as well:

// swift-tools-version:4.0

import PackageDescription

let package = Package(
    name: "MyProject",
    products: [
        .library(
            name: "MyProject",
            targets: ["MyProject"]),
    ],
    dependencies: [
        .package(url: "https://github.com/IBM-Swift/Swift-SMTP", .upToNextMinor(from: "5.1.0")),    // add the dependency
    ],
    targets: [
        .target(
            name: "MyProject",
            dependencies: ["SwiftSMTP"]),                                                           // add targets
        .testTarget(                                                                                // note "SwiftSMTP" (NO HYPHEN)
            name: "MyProjectTests",
            dependencies: ["MyProject"]),
    ]
)

After adding the dependency and saving, run swift package generate-xcodeproj in the root directory of your project. This will fetch dependencies and create an Xcode project which you can open and begin editing.

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

Github

link
Stars: 140

Used By

Total: 0

Releases

5.1.2 - 2019-10-04 09:00:42

  • Resolve compilation warnings with Swift 5 and later

Swift 5 support - 2019-04-12 12:25:08

Swift 4.1.2 support - 2018-07-03 15:38:31

Thanks @pushkarnk

Add TLSMode - 2018-06-26 17:16:14

Thanks to @trametheka for the great work.

migration guide

Update dependencies - 2018-05-01 13:56:30

Fixes #74. Thanks @davidde94

4.0.0 - 2018-04-30 18:52:55

Adds Swift 4.1 support and more. See all changes in migration guide.

Thanks for contributions from @hanskroner & @rafiki270.

Specify TLS support - 2018-04-06 01:52:59

Use 'text/plain' for plain text content - 2018-03-27 18:19:29

Thanks @hanskroner

Only support Swift 4.0.3 - 2018-02-16 07:14:33

Thanks to @Davidde94.

Add Swift 4 Support - 2017-10-04 22:13:29

Fix message-id, revert previous breaking API changes - 2017-08-31 14:03:09

Many thanks to @leanne63 for her work on this!

  • Mail structs no longer require a hostname for initialization
  • removed makeMail() function in SMTP struct

Improve connect with timeout - 2017-08-22 16:32:29

NOTE: The timeout parameter in initializing an SMTP handle is now a UInt.

Attempting to connect to a server should now correctly timeout and return an error when appropriate.

Mail objects require a hostname to init - 2017-08-22 02:21:45

[See #41]

Breaking API change for initializing a Mail object:

  • Initializing a Mail object now requires a hostname to be provided.

New API for the SMTP struct:

  • makeMail(): create a Mail object. It's hostname will be set to the SMTP struct's hostname.

SSL and additional headers changes - 2017-07-17 16:19:25

  • SSL
    • If an SSL connection is required, Swift-SMTP will automatically attempt to upgrade the connection without a need for the user to specify an SSL configuration
    • With this default configuration, no backing certificates are used for the client's side of the SSL handshake with the SMTP server
    • View docs on the SSL struct for more configuration options, like adding a certificate chain, etc.
  • Additional headers:
    • CONTENT-TYPE, CONTENT-DISPOSITION, CONTENT-TRANSFER-ENCODING headers added in additionalHeaders will now be ignored. Allowing them to be overwritten causes errors for some SMTP servers and mail content to render incorrectly.
      • CONTENT-TYPE will be set by Swift-SMTP--plaintext/html should render correctly in the body of emails. Attachments will also have their CONTENT-TYPE correctly set by Swift-SMTP.
      • For CONTENT-DISPOSITION, set the inline flag in the initialization of an Attachment if you need to customize this
      • Users should not need to change CONTENT-TRANSFER-ENCODING

Default headers for plain text mail content - 2017-07-10 21:44:39

  • For plain text content of an email, these default headers are added:
    • CONTENT-TYPE: text/html; charset=utf-8
    • CONTENT-TRANSFER-ENCODING: 7bit
    • CONTENT-DISPOSITION: inline
  • These headers can be overwritten by the user with the additionalHeaders dictionary
    • This is usually not recommended as any headers in additionalHeaders are applied to the entire email, so multi content-type emails will be rendered incorrectly. This will be noted in the docs.
  • Additional changes to the other content types (mixed, alternative, related) will also be made so that the default CONTENT-TYPE header can be overwritten as well (but again, not recommended)

Dependency graph issue, plain text header issues - 2017-07-10 15:04:55

  • added .git. to BlueCryptor url in Package.swift
  • removed hard coded header in plain text content of emails

Change logging levels, headers can now be overwritten - 2017-07-05 21:25:39

  • SMTPSocket logging level is now at debug level (you will no longer see the logs on verbose level)
  • A Mail's or Attachment's additionalHeaders is now a dictionary. This means headers can be overwritten. Note that all header keys are capitalized.

Add Swift 4 support - 2017-06-15 13:06:58

swift-4.0-DEVELOPMENT-SNAPSHOT-2017-06-11-a

Code Improvements - 2017-06-07 21:39:09

Remove testing credentials - 2017-06-03 18:29:22

  • Default testing credentials have been moved to a private repo.
  • If you would like to run the tests yourself, please enter the necessary login info to your own SMTP server in /Tests/SwiftSMTPTests/Constant.swift.

Consistency changes - 2017-05-30 19:53:17

Update package.swift and rename some API params for consistency.

1.0.0 - 2017-05-25 17:50:15

We are pleased to release v1.0.0 of Swift-SMTP.

  • macOS and Linux support
  • Swift 3.1.1