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.
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
macOS & Linux: Swift 5.2 or above.
To install SwiftSMTP you can follow the tutorial published by Apple using the URL for the SwiftSMTP repo with the current version:
- In Xcode, select “File” → “Add Packages...”
- 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")Version 5.0.0 brings breaking changes. See the quick migration guide here.
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
)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.
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)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 */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
}
)Inspired by Hedwig and Perfect-SMTP.
Apache v2.0