{"id":13483165,"url":"https://github.com/arcage/crystal-email","last_synced_at":"2025-08-13T23:32:34.341Z","repository":{"id":12972306,"uuid":"73264706","full_name":"arcage/crystal-email","owner":"arcage","description":"Simple e-mail sending library","archived":false,"fork":false,"pushed_at":"2024-06-11T04:24:57.000Z","size":396,"stargazers_count":111,"open_issues_count":0,"forks_count":18,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-12-06T23:32:52.965Z","etag":null,"topics":["crystal","email","smtp"],"latest_commit_sha":null,"homepage":"","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arcage.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-09T08:27:20.000Z","updated_at":"2024-06-11T04:21:17.000Z","dependencies_parsed_at":"2024-06-20T10:59:38.049Z","dependency_job_id":"89adc9bf-ff42-45be-a3ec-819ae9debff0","html_url":"https://github.com/arcage/crystal-email","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcage%2Fcrystal-email","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcage%2Fcrystal-email/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcage%2Fcrystal-email/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcage%2Fcrystal-email/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arcage","download_url":"https://codeload.github.com/arcage/crystal-email/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229787060,"owners_count":18124013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crystal","email","smtp"],"created_at":"2024-07-31T17:01:08.737Z","updated_at":"2024-12-15T06:05:07.843Z","avatar_url":"https://github.com/arcage.png","language":"Crystal","funding_links":[],"categories":["Email"],"sub_categories":[],"readme":"# EMail for Crystal\n\n[![Build Status](https://travis-ci.org/arcage/crystal-email.svg?branch=master)](https://travis-ci.org/arcage/crystal-email)\n\nSimple email sending library for the [Crystal programming language](https://crystal-lang.org).\n\nYou can:\n\n- construct an email with a plain text message, a HTML message and/or some attachment files.\n- include resources(e.g. images) used in the HTML message.\n- set multiple recipients to the email.\n- use multibyte characters(only UTF-8) in the email.\n- send the email by using local or remote SMTP server.\n- use TLS connection by **SMTP orver SSL/TLS**(new) or `STARTTLS` command.\n- use SMTP-AUTH by `AUTH PLAIN` or `AUTH LOGIN` when using TLS.\n- send multiple emails concurrently by using multiple smtp connections.\n\nYou can not:\n\n- use ESMTP features except those mentioned above.\n\n## Installation\n\nFirst, add the dependency to your `shard.yml`:\n\n```yaml\ndependencies:\n  email:\n    github: arcage/crystal-email\n```\n\nThen, run `shards install`\n\n### Library requirement\n\nWhen using STARTTLS or SMTPS, this shard require **libssl** and **libcrypto** for TLS handling. \n\nYou may have to install those libraries to your system.\n\n## Usage\n\nTo send a minimal email message:\n\n**NOTE: Since v0.7.0, EMail::Client::Config object require `helo_domain` argument at initializing.**\n\n```crystal\nrequire \"email\"\n\n# Create email message\nemail = EMail::Message.new\nemail.from    \"your_addr@example.com\"\nemail.to      \"to@example.com\"\nemail.subject \"Subject of the mail\"\nemail.message \u003c\u003c-EOM\n  Message body of the mail.\n\n  --\n  Your Signature\n  EOM\n\n# Set SMTP client configuration\nconfig = EMail::Client::Config.new(\"your.mx.example.com\", 25, helo_domain: \"your.host.example.com\")\n\n# Create SMTP client object\nclient = EMail::Client.new(config)\n\nclient.start do\n  # In this block, default receiver is client\n  send(email)\nend\n```\n\nThis code will output log entries to `STDOUT` as follows:\n\n```text\n2018/01/25 20:35:09 [e_mail.client/12347] INFO [EMail_Client] Start TCP session to your.mx.example.com:25\n2018/01/25 20:35:10 [e_mail.client/12347] INFO [EMail_Client] Successfully sent a message from \u003cyour_addr@example.com\u003e to 1 recipient(s)\n2018/01/25 20:35:10 [e_mail.client/12347] INFO [EMail_Client] Close TCP session to your.mx.example.com:25\n```\n\n### Client configs\n\nYou can set some connection settings to `EMail::Client::Config` object.\n\nThat can make SMTP connection to use TLS / SMTP AUTH, or output more detailed log message.\n\nSee [EMail::Client::Config](https://www.denchu.org/crystal-email/EMail/Client/Config.html) for more details.\n\n### Email message\n\nYou can set more email headers to `EMail::Message` object.\n\nAnd, you can also send emails including attachment files, HTML message, and/or resource files related message body(e.g. image file for HTML message).\n\nSee [EMail::Message](https://www.denchu.org/crystal-email/EMail/Message.html) for more details.\n\n### Concurrent sending\n\n**Note: this feature supports the _concurrent_(not parallel) sending with only one thread.**\n\nBy using `EMail::ConcurrentSender` object, you can concurrently send multiple messages by multiple connections.\n\n```crystal\nrcpt_list = [\"a@example.com\", \"b@example.com\", \"c@example.com\", \"d@example.com\"]\n\n# Set SMTP client configuration\nconfig = EMail::Client::Config.new(\"your.mx.example.com\", 25, helo_domain: \"your.host.example.com\")\n\n# Create concurrent sender object\nsender = EMail::ConcurrentSender.new(config)\n\n# Sending emails with concurrently 3 connections.\nsender.number_of_connections = 3\n\n# Sending max 10 emails by 1 connection.\nsender.messages_per_connection = 10\n\n# Start email sending.\nsender.start do\n  # In this block, default receiver is sender\n  rcpts_list.each do |rcpt_to|\n    # Create email message\n    mail = EMail::Message.new\n    mail.from \"your_addr@example.com\"\n    mail.to rcpt_to\n    mail.subject \"Concurrent email sending\"\n    mail.message \"message to #{rcpt_to}\"\n    # Enqueue the email to sender\n    enqueue mail\n  end\nend\n```\n\nSee [EMail::ConcurrentSender](https://www.denchu.org/crystal-email/EMail/ConcurrentSender.html) for more details.\n\n## Logging\n\nThe v0.34.0 of Crystal language has drastic changes in the logging functions. To fit it, the v0.5.0 of this shard also changes the logging behaviour.\n\nYou can use two kinds of logger(`Log` type object), the **default logger** and the **client specific logger**.\n\nThe **default logger** is declered on the `EMail::Client` type. It can be got by `EMail::Client.log`, and change its behavior by `EMail::Client.log_***=` methods.\n\nOn the other hand, the **client specific logger** will be set to `EMail::Client` instance itself by `EMail::Client::Config` setting. With this, you can use your own logger for the `EMail::Client` object.\n\nIf the `EMail::Client` object has the **client specific logger**, the client use it to output the log entries. Otherwise, the client use the **default logger**.\n\nSee [EMail::Client](https://www.denchu.org/crystal-email/EMail/Client.html) and [EMail::Client::Config](https://www.denchu.org/crystal-email/EMail/Client/Config.html) for more details.\n\n### Debug log\n\nWhen you set the log level to `Log::Severity::Debug`, you can see all of the SMTP commands and the resposes in the log entries.\n\n```crystal\nEMail::Client.log_level = Log::Severity::Debug\n```\n\nDebug log are very useful to check how SMTP session works.\n\nBut, in the case of using SMTP AUTH, the debug log includes Base64 encoded user ID and passowrd. You should remenber that anyone can decode the authentication information from the debug log. And, you should use that **very carefully**.\n\n## Owner\n\n- [arcage](https://github.com/arcage) ʕ·ᴥ·ʔAKJ - creator, maintainer\n\n## Contributors\n\nThank you for valuable contributions.\n\n- [Contributors](https://github.com/arcage/crystal-email/graphs/contributors)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcage%2Fcrystal-email","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farcage%2Fcrystal-email","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcage%2Fcrystal-email/lists"}