Hedwig is a Swift package which supplies a set of high level APIs to allow you sending email to an SMTP server easily. If you are planning to send emails from your next amazing Swift server app, Hedwig might be a good choice.
- Connect to all SMTP servers, through whether plain, SSL or TLS (STARTTLS) port.
- Authentication with
PLAIN
,CRAM-MD5
,LOGIN
orXOAUTH2
. - Send email with HTML body and attachments.
- Customize validation method and mail header, to track your mail campaign.
- Queued mail sending, without blocking your app. You can even send mails concurrently.
- Works with Swift Package Manager, in the latest Swift syntax and cross-platform.
- Fully tested and documented.
Add the url of this repo to your Package.swift:
import PackageDescription
let package = Package(
name: "YourAwesomeSoftware",
dependencies: [
.Package(url: "https://github.com/onevcat/Hedwig.git",
majorVersion: 1)
]
)
Then run swift build
whenever you get prepared. (Also remember to grab a cup of coffee 😄)
You can find more information on how to use Swift Package Manager in Apple's official page.
let hedwig = Hedwig(hostName: "smtp.example.com", user: "foo@bar.com", password: "password")
let mail = Mail(
text: "Across the great wall we can reach every corner in the world.",
from: "onev@onevcat.com",
to: "foo@bar.com",
subject: "Hello World"
)
hedwig.send(mail) { error in
if error != nil { /* Error happened */ }
}
let hedwig = Hedwig(hostName: "smtp.example.com", user: "foo@bar.com", password: "password")
let attachment = Attachment(htmlContent: "<html><body><h1>Title</h1><p>Content</p></body></html>")
let mail = Mail(
text: "Fallback text",
from: "onev@onevcat.com",
to: "foo@bar.com",
subject: "Title",
attachments: [attachment]
)
hedwig.send(mail) { error in
if error != nil { /* Error happened */ }
}
let hedwig = Hedwig(hostName: "smtp.example.com", user: "foo@bar.com", password: "password")
let mail = Mail(
text: "Across the great wall we can reach every corner in the world.",
from: "onev@onevcat.com",
to: "foo@bar.com",
cc: "Wei Wang <onev@onevcat.com>, tom@example.com", // Addresses will be parsed for you
bcc: "My Group: onev@onevcat.com, foo@bar.com;", // Even with group syntax
subject: "Hello World"
)
hedwig.send(mail) { error in
if error != nil { /* Error happened */ }
}
let hedwig = Hedwig(
hostName: "smtp.example.com",
user: "foo@bar.com",
password: "password",
port: 1234, // Determined from secure layer by default
secure: .plain, // .plain (Port 25) | .ssl (Port 465) | .tls (Port 587) (default)
validation: .default, // You can set your own certificate/cipher/protocols
domainName: "onevcat.com", // Used when saying hello to STMP Server
authMethods: [.plain, .login] // Default: [.plain, .cramMD5, .login, .xOauth2]
)
let imagePath = "/tmp/image.png"
// You can create an attachment from a local file path.
let imageAttachment = Attachment(
filePath: imagePath,
inline: true,
// Add "Content-ID" if you need to embed this image to another attachment.
additionalHeaders: ["Content-ID": "hedwig-image"]
)
let html = Attachment(
htmlContent: "<html><body>A photo <img src=\"cid:hedwig-image\"/></body></html>",
// If imageAttachment only used embeded in HTML, I recommend to set it as related.
related: [imageAttachment]
)
// You can also create attachment from raw data.
let data = "{\"key\": \"hello world\"}".data(using: .utf8)!
let json = Attachment(
data: data,
mime: "application/json",
name: "file.json",
inline: false // Send as standalone attachment.
)
let mail = Mail(
text: "Fallback text",
from: "onev@onevcat.com",
to: "foo@bar.com",
subject: "Check the photo and json file!",
attachments: [html, json]
hedwig.send(mail) { error in
if error != nil { /* Error happened */ }
}
let mail1: Mail = //...
let mail2: Mail = //...
hedwig.send([mail1, mail2],
progress: { (mail, error) in
if error != nil {
print("\(mail) failed. Error: \(error)")
}
},
completion: { (sent, failed) in
for mail in sent {
print("Sent mail: \(mail.messageId)")
}
for (mail, error) in failed {
print("Mail \(mail.messageId) errored: \(error)")
}
}
)
Visit the documentation page for full API reference.
You could also run the tests (swift test
) to see more examples to know how to use Hedwig.
If you have found the framework to be useful, please consider a donation. Your kind contribution will help me afford more time on the project.
Or you are a Bitcoin fan and want to treat me a cup of coffe, here is my wallet address:
1MqwfsxBJ5pJX4Qd2sRVhK3dKTQrWYooG5
Gmail uses an application specific password. You need to create one and use the specified password when auth. See this.
Both
Attachment
accept customizing header fields. Pass your headers asadditionalHeaders
when creating the mail or attachment and Hedwig will handle it.
At this time Swift Package Manager has no support for iOS, watchOS, or tvOS platforms. So the answer is no. But this framework is not using anything only in iOS (like UIKit), so as soon as Swift Package Manager supports iOS, you can use it there too.
Yes, Hedwig (bird) was Harry Potter's pet Snowy Owl. The logo of Hedwig (this framework) is created by myself and it pays reverence to the novels and movies.
Submit an issue if you find something wrong. Pull requests are warmly welcome, but I suggest to discuss first.
You can also follow and contact me on Twitter or Sina Weibo.
Hedwig is released under the MIT license. See LICENSE for details.