{"id":15062852,"url":"https://github.com/ec-nordbund/denomailer","last_synced_at":"2025-07-23T02:34:26.115Z","repository":{"id":37991368,"uuid":"452971196","full_name":"EC-Nordbund/denomailer","owner":"EC-Nordbund","description":"A SMTP-Client implementation for deno (to send mails!)","archived":false,"fork":false,"pushed_at":"2024-09-03T09:25:32.000Z","size":127,"stargazers_count":54,"open_issues_count":22,"forks_count":18,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-10T10:16:30.392Z","etag":null,"topics":["deno","mail","smtp"],"latest_commit_sha":null,"homepage":"https://deno.land/x/denomailer","language":"TypeScript","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/EC-Nordbund.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-28T07:04:55.000Z","updated_at":"2025-03-15T05:06:49.000Z","dependencies_parsed_at":"2023-10-14T19:51:59.942Z","dependency_job_id":"afe537fb-bb01-4c9b-8333-f5ab48a4e2fd","html_url":"https://github.com/EC-Nordbund/denomailer","commit_stats":{"total_commits":126,"total_committers":18,"mean_commits":7.0,"dds":"0.33333333333333337","last_synced_commit":"03e58cea6d9bd41b68bcd542cb6fa45cffa49df3"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/EC-Nordbund/denomailer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EC-Nordbund%2Fdenomailer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EC-Nordbund%2Fdenomailer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EC-Nordbund%2Fdenomailer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EC-Nordbund%2Fdenomailer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EC-Nordbund","download_url":"https://codeload.github.com/EC-Nordbund/denomailer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EC-Nordbund%2Fdenomailer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266606774,"owners_count":23955342,"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","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["deno","mail","smtp"],"created_at":"2024-09-24T23:47:29.400Z","updated_at":"2025-07-23T02:34:26.095Z","avatar_url":"https://github.com/EC-Nordbund.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Denomailer - an SMTP client for Deno\n\n[![deno module](https://shield.deno.dev/x/denomailer)](https://deno.land/x/denomailer)\n\n\u003e This was forked from https://github.com/manyuanrong/deno-smtp but now is much\n\u003e more advanced!\n\n## Deno Deploy\n\nIf your SMTP server uses ports 25, 465, or 587 you can't use denomailer with\nDeno Deploy. See\nhttps://discord.com/channels/684898665143206084/684911491035430919/961964433524031498\nfor more info.\n\n\u003e \"You can not connect to SMTP servers on ports 25, 465, or 587 due to abuse.\"\n\n## Quickstart with a simple example\n\n```ts\nimport { SMTPClient } from \"https://deno.land/x/denomailer/mod.ts\";\n\nconst client = new SMTPClient({\n  connection: {\n    hostname: \"smtp.example.com\",\n    port: 465,\n    tls: true,\n    auth: {\n      username: \"example\",\n      password: \"password\",\n    },\n  },\n});\n\nawait client.send({\n  from: \"me@example.com\",\n  to: \"you@example.com\",\n  subject: \"example\",\n  content: \"...\",\n  html: \"\u003cp\u003e...\u003c/p\u003e\",\n});\n\nawait client.close();\n```\n\n## Client\n\nYou can create a new client with\n`const client = new SMTPClient(/* client options */)`.\n\n### Options\n\nThe only required option is `connection.hostname` but in most cases, you want to\nset `connection.,auth`.\n\nHere are the available options:\n\n```ts\nexport interface ClientOptions {\n  debug?: {\n    /**\n     * USE WITH CAUTION AS THIS WILL LOG YOUR USERDATA AND ALL MAIL CONTENT TO STDOUT!\n     * @default false\n     */\n    log?: boolean;\n    /**\n     * USE WITH CAUTION AS THIS WILL POSSIBLY EXPOSE YOUR USERDATA AND ALL MAIL CONTENT TO ATTACKERS!\n     * @default false\n     */\n    allowUnsecure?: boolean;\n    /**\n     * USE WITH CAUTION AS THIS COULD INTRODUCE BUGS\n     *\n     * This option is mainly to allow debugging to exclude some possible problem surfaces at encoding\n     * @default false\n     */\n    encodeLB?: boolean;\n    /**\n     * Disable starttls\n     */\n    noStartTLS?: boolean;\n  };\n  connection: {\n    hostname: string;\n    /**\n     * For TLS the default port is 465 else 25.\n     * @default 25 or 465\n     */\n    port?: number;\n    /**\n     * authentication data\n     */\n    auth?: {\n      username: string;\n      password: string;\n    };\n    /**\n     * Set this to `true` to connect via SSL / TLS if set to `false` STARTTLS is used.\n     * Only if `allowUnsecure` is used userdata or mail content could be exposed!\n     *\n     * @default false\n     */\n    tls?: boolean;\n  };\n  /**\n   * Create multiple connections so you can send emails faster!\n   */\n  pool?: {\n    /**\n     * Number of Workers\n     * @default 2\n     */\n    size?: number;\n    /**\n     * Time the connection has to be idle to be closed. (in ms)\n     * If a value \u003e 1h is set it will be set to 1h\n     * @default 60000\n     */\n    timeout?: number;\n  } | boolean;\n  client?: {\n    /**\n     * There are some cases where warnings are created. These are logged by default but you can 'ignore' them or all warnings should be considered 'error'.\n     *\n     * @default log\n     */\n    warning?: \"ignore\" | \"log\" | \"error\";\n    /**\n     * List of preprocessors to\n     *\n     * - Filter mail\n     * - BCC emails to someone\n     * - ...\n     */\n    preprocessors?: Preprocessor[];\n  };\n}\n```\n\n#### connection\n\nYou have to set the hostname and in most cases, you need the auth object as\n(near) all SMTP-Server will require a login.\n\n\u003e The only use case where you might not need it is if you connect to a server\n\u003e with IP protection, so for example only local IPs are allowed to a server\n\u003e application that can send mails without login.\n\nDenomailer supports 3 security modes:\n\n1. TLS\n2. STARTTLS\n3. unsecure\n\nYou have to specify which mode to use. With unsecure, you have to set an extra\nconfig option in `debug` as it is not recommended to use unsecure!\n\nFor TLS set `tls: true`, for startTLS set `tls: false` (default).\n\n#### client\n\nThere are some \"problems\" that can be warnings or errors. With the `warning`\noption you can specify if they should `'error'` or you can `'ignore'` them or\n`'log'` them. The default is `'log'`. This includes filtering invalid emails and\ncustom preprocessors\n\nWith the `preprocessors` option, you can add handlers that modify each\nmail-config. For example, you can add a filter so you don't send emails to\nburner addresses, etc.\n\nA preprocessor is of the type:\n\n```ts\ntype Preprocessor = (\n  mail: ResolvedSendConfig,\n  client: ResolvedClientOptions,\n) =\u003e ResolvedSendConfig;\n```\n\nIt takes a preprocessed email config (ResolvedSendConfig) and the preprocessed\nclient options (ResolvedClientOptions) and returns a possibly modified email\nconfig.\n\n#### pool\n\nWith a normal SMTP client, emails are sent one after the other so if you have a\nheavy load you might want to use more clients at once. denomailer provides a\npool feature to help with this.\n\nYou can set the number of clients used (`size`) and a timeout (in ms) after that\nthe connection is closed (`timeout`).\n\nNote that for each connection we create a new worker and the used worker syntax\nrequires (as of Deno 1.21) to use the `--unstable` flag. Because of that, this\nAPI has to be considered unstable, however the rest of the API is considered\nstable. (At least for the public denomailer API internally there might be some\nsmall changes that require specific Deno versions)\n\nWhen you close the connection all workers are killed.\n\n#### debug\n\nSometimes you have specific needs for example we require encrypted connections\nto send emails with authentication. To enable unsecure connections set the\n`allowUnsecure` option to `true`. Depending on your needs you may have to\ndisable startTLS `noStartTLS` to get an unsecure connection.\n\nNote that we only use this in tests where the SMTP server is local and doesn't\nsupport TLS.\n\nIf you want to get a full connection log use the `log` option. If you create an\nissue for a bug please add the full log (but remove your authentication data\nwhich is encoded in base64).\n\nIn some cases you might get problems with linebreaks in emails, before creating\nan issue please try `encodeLB: true` which changes the encoding and might solve\nyour problem.\n\n### Examples\n\n```ts\nconst client = new SMTPClient({\n  connection: {\n    hostname: \"smtp.example.com\",\n    port: 465,\n    tls: true,\n    auth: {\n      username: \"example\",\n      password: \"password\",\n    },\n  },\n  pool: {\n    size: 2,\n    timeout: 60000,\n  },\n  client: {\n    warning: \"log\",\n    preprocessors: [filterBurnerMails],\n  },\n  debug: {\n    log: false,\n    allowUnsecure: false,\n    encodeLB: false,\n    noStartTLS: false,\n  },\n});\n```\n\n## Sending emails\n\n`client.send(/* mail config */)`\n\n### Config\n\nThe config you can set:\n\n```ts\nexport interface SendConfig {\n  to: mailList;\n  cc?: mailList;\n  bcc?: mailList;\n  from: string;\n  date?: string;\n  subject: string;\n  content?: string;\n  mimeContent?: Content[];\n  html?: string;\n  inReplyTo?: string;\n  replyTo?: string;\n  references?: string;\n  priority?: \"high\" | \"normal\" | \"low\";\n  attachments?: Attachment[];\n  /**\n   * type of mail for example `registration` or `newsletter` etc.\n   * allows preprocessors to handle different email types\n   */\n  internalTag?: string | symbol;\n  headers: Record\u003cstring, string\u003e;\n}\n```\n\nAll of it should be clear by name except:\n\n#### headers\n\nAdd custom headers to the email.\n\n#### mimeContent\n\nThere may be instances where you want to use your own encoding. This option\nallows you to specify the content of the mail.\n\n#### content \u0026 html\n\nThe content should be a plain-text version of the HTML content. You can set\n`content` to `'auto'` to generate the content automatically, but we recommend\nthat you do set it yourself.\n\n#### attachments\n\nYou can encode an array of attachments as base64, text, or binary. Note that\nbase64 is converted to binary and is only present for a better API. So don't\nencode your binary files as base64, otherwise denomailer can't convert it back\nto binary.\n\n#### internalTag\n\nThis can be used with preprocessors so you can give mail a type, for example\n`'registration'`, `'newsletter'` etc. supports symbols and strings.\n\n### Allowed Mail Formats\n\nA single address `mail@example.de` with the name `NAME` can be encoded in the\nfollowing ways:\n\n1. `\"name@example.de\"`\n2. `\"\u003cname@example.de\u003e\"`\n3. `\"NAME \u003cname@example.de\u003e\"`\n4. `{mail: \"name@example.de\"}`\n5. `{mail: \"name@example.de\", name: \"NAME\"}`\n\nMultiple Mails can be an Array of the above OR an object that maps names to\nmails for example:\n\n`{\"P1\": \"p1@example.de\", \"P2\": \"p2@example.de\"}` we call this a MailObject.\n\nFor the fields\n\n1. `from`, `replyTo` we only allow a single mail string.\n2. `to`, `cc`, `bcc` we allow a MailObject of an array of single mails (you can\n   mix formats) or a single Mail.\n\n### Examples\n\nExample with near all options:\n\n```ts\nclient.send({\n  to: \"abc@example.com\",\n  cc: [\n    \"abc@example.com\",\n    \"abc \u003cabc@example.com\u003e\",\n    {\n      name: \"abc\",\n      mail: \"abc@example.com\",\n    },\n  ],\n  bcc: {\n    abc: \"abc@example.com\",\n    other: \"abc@example.com\",\n  },\n  from: \"me \u003cabc@example.com\u003e\",\n  replyTo: \"\u003cabc@example.com\u003e\",\n  subject: \"example\",\n  content: \"auto\",\n  html: \"\u003cp\u003eHello World\u003c/p\u003e\",\n  internalTag: \"newsletter\",\n  priority: \"low\",\n});\n```\n\n## Other exports\n\nWe export our implementation of a quotedPrintable encoder. There might be some\nuse cases where you need it. The API of the function is considered stable!\n\n## Stable API\n\nAll of the API exported by `/mod.ts` is considered stable. But since the `pool`\nneeds the `--unstable` flag by Deno, this has to be considered unstable. But we\ndon't expect any breaking changes there - however, it is always possible a new\nDeno release can break it!\n\nChanges to them will only be made if a new major is released.\n\n## Contribute\n\nFeel free to contribute by:\n\n1. creating issues for bugs and feature requests (note that you have to use the\n   bug template to get support)\n2. contribute code but keep in mind\n   - for small changes, you can just create a PR\n   - for bigger changes please create an issue before! This will help to reduce\n     the time creating a PR that is not merged.\n   - if you fix a bug please add a test that fails before your fix\n3. contribute tests, fix typos, ...\n\n## TLS issues\n\nWhen getting TLS errors make sure:\n\n1. you use the correct port (mostly 25, 587, 465)\n2. the server supports STARTTLS when using `connection.tls = false`\n3. the server supports TLS when using `connection.tls = true`\n4. Use the command\n   `openssl s_client -debug -starttls smtp -crlf -connect your-host.de:587` or\n   `openssl s_client -debug -crlf -connect your-host.de:587` and get the used\n   cipher. This should be a cipher with \"forward secrecy\". Check the status of\n   the cipher on https://ciphersuite.info/cs/ . If the cipher is not STRONG this\n   is an issue with your mail provider, so you have to contact them to fix it.\n5. Feel free to create issues and share the port and host so we can properly\n   debug your issue.\n6. We can only support TLS where Deno supports it and Deno uses rustls which\n   explicitly does not implement some \"weak\" ciphers.\n\n## Non-SpecCompliant SMTP server\n\nSome SMTP servers don't follow the spec 100%. This can result in unexpected\nerrors in denomailer. If this happens (for example in\nhttps://github.com/EC-Nordbund/denomailer/blob/03a66a6f9a4b5f349ea35856f5903fb45fd0cc5f/smtp.ts#L376\nthe server sends a 250) please create an issue. We will try and do the\nfollowing:\n\n1. Check if it is not an error in denomailer\n2. Try to fix it at the SMTP server side (create an issue if the server is an\n   open source project etc.)\n3. We will add a _**temporary**_ workaround by changing denomailer. This will\n   include log messages telling the developer (if the workaround is used) that\n   denomailer used the workaround which can be removed at any time.\n\n## Breaking changes\n\n### v0.x -\u003e v1.0\n\n1. Change `SmtpClient` to `SMTPClient`\n2. Change the constructor options (include the options used with\n   `client.connect` or `client.connectTLS` (add `tls = true` in the second\n   case))\n3. Remove `client.connect` and `client.connectTLS` calls\n4. filterMail option was removed in favor of the new preprocessor option\n5. Some internal fields were removed from `SMTPClient`, denomailer only uses\n   `send` and `close`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fec-nordbund%2Fdenomailer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fec-nordbund%2Fdenomailer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fec-nordbund%2Fdenomailer/lists"}