From 22b9ecd23188be3a02a1c7a50ab8f32843a74f95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicklas=20Av=C3=A9n?= Date: Mon, 13 Nov 2017 21:22:19 +0100 Subject: [PATCH 01/15] Add Date header --- pgMail.sql | 1 + 1 file changed, 1 insertion(+) diff --git a/pgMail.sql b/pgMail.sql index 4c69e51..d961060 100644 --- a/pgMail.sql +++ b/pgMail.sql @@ -34,6 +34,7 @@ puts $mySock "RCPT TO: $toemailaddress" gets $mySock name puts $mySock "DATA" gets $mySock name +puts $mySock "Date: [clock format [clock seconds] -format {%a, %d %b %Y %H:%M:%S +0000} -gmt true]" puts $mySock "From: $mailfrom" puts $mySock "To: $mailto" puts $mySock "Subject: $mailsubject" From 9b515b4ea06de42e76cadb922884ed333e0cc7fd Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Mon, 13 Nov 2017 16:39:55 -0600 Subject: [PATCH 02/15] Added details for 1.3 release. --- CHANGELOG | 4 ++++ README | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index b9080e0..2671737 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,5 +1,9 @@ Change Log. +v1.3 - pgMail will now add a properly formatted Date header. This was + particularly troubling for some Android users. Thanks to + Nicklas Aven for the patch! (me) + v1.2 - pgMail now properly sends UTF-8 encoded emails. Thanks to Balazs Keresztury for the patch! (me) - Fixed an issue whereby some servers would reject emails due to diff --git a/README b/README index 76562e6..e8e7eae 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -pgMail v1.2 (01/07/2012) +pgMail v1.3 (11/13/2017) pgMail is maintained by Branden R. Williams Homepage: http://www.brandolabs.com/pgmail @@ -6,7 +6,7 @@ Homepage: http://www.brandolabs.com/pgmail If you are interested in contributing to the project please email the maintainer directly. ------------------------------------------------------------------ -Copyright 2012 Branden R. Williams. +Copyright 2002-2017 Branden R. Williams. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. From 0afb47d7a3f10e2d278a7c64f0d6855227d0a4e8 Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Wed, 15 Nov 2017 21:33:05 -0600 Subject: [PATCH 03/15] Updated for MIME Multipart Added an additional argument in mailmessage_html. If both are present, we do a multipart message. Otherwise, we just paste the correct message. --- pgMail.sql | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/pgMail.sql b/pgMail.sql index d961060..aa3d06b 100644 --- a/pgMail.sql +++ b/pgMail.sql @@ -1,8 +1,14 @@ -create function pgmail(text, text, text, text) returns int4 as ' +create function pgmail(text, text, text, text default '', text default '') returns int4 as ' set mailfrom $1 set mailto $2 set mailsubject $3 set mailmessage $4 +set mailmessage_html $5 +if {$mailmessage ne "" && $mailmessage_html ne ""} { + set multipart true +} else { + set multipart false +} set myHost "" set myPort 25 set mySock [socket $myHost $myPort] @@ -39,10 +45,22 @@ puts $mySock "From: $mailfrom" puts $mySock "To: $mailto" puts $mySock "Subject: $mailsubject" puts $mySock "MIME-Version: 1.0" -puts $mySock "Content-type: text/plain; charset=UTF-8" -puts $mySock "Content-Transfer-Encoding: 8bit" -puts $mySock "" -puts $mySock "$mailmessage" +if {$multipart} { + puts $mySock {Content-type: multipart/mixed; boundary="just_a_simple_boundary"} +} elseif {$mailmessage ne ""} { + if {$multipart} {puts $mySock "--just_a_simple_boundary"} + puts $mySock "Content-type: text/plain; charset=UTF-8" + puts $mySock "Content-Transfer-Encoding: 8bit" + puts $mySock "" + puts $mySock "$mailmessage" +} elseif {$mailmessage_html ne ""} { + if {$multipart} {puts $mySock "--just_a_simple_boundary"} + puts $mySock "Content-type: text/html; charset=UTF-8" + puts $mySock "Content-Transfer-Encoding: 8bit" + puts $mySock "" + puts $mySock "$mailmessage_html" +} +if {$multipart} {puts $mySock "--just_a_simple_boundary--"} puts $mySock "" puts $mySock "." gets $mySock name From 3d6e0ed6a03836cb092d5c94a71fd4538aeecba0 Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Wed, 15 Nov 2017 21:58:05 -0600 Subject: [PATCH 04/15] Removed default value on 4th arg. --- pgMail.sql | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pgMail.sql b/pgMail.sql index aa3d06b..40c960e 100644 --- a/pgMail.sql +++ b/pgMail.sql @@ -1,4 +1,4 @@ -create function pgmail(text, text, text, text default '', text default '') returns int4 as ' +create function pgmail(text, text, text, text, text default '') returns int4 as ' set mailfrom $1 set mailto $2 set mailsubject $3 From e68cad1a994327979064a04f3b4ad479215aaf64 Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Wed, 15 Nov 2017 21:58:17 -0600 Subject: [PATCH 05/15] Added details on Version 1.4 --- CHANGELOG | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG b/CHANGELOG index 2671737..435f650 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,5 +1,12 @@ Change Log. +v1.4 - pgMail now supports both HTML messaging and MULTIPART MIME + messaging. It's backwards compatible. If you want to ONLY send + HTML, you need to pass an empty string as your 4th argument. + But why not just do both plain text & HTML? Thanks to + Nicklas Aven for the idea and original patch! I changed his + pull request a bit to avoid duplicate code. (me) + v1.3 - pgMail will now add a properly formatted Date header. This was particularly troubling for some Android users. Thanks to Nicklas Aven for the patch! (me) From 7f04060340b2167291bd91dc110e35aa7764ef0f Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Wed, 15 Nov 2017 21:58:55 -0600 Subject: [PATCH 06/15] Added examples of multipart MIME and HTML. --- README | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/README b/README index e8e7eae..bea6484 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -pgMail v1.3 (11/13/2017) +pgMail v1.4 (11/16/2017) pgMail is maintained by Branden R. Williams Homepage: http://www.brandolabs.com/pgmail @@ -71,7 +71,15 @@ Once you have installed the stored function, simply call the procedure as follows. select pgmail('Send From ','Send To ', - 'Subject goes here','Message body here.'); + 'Subject goes here','Plaintext message body here.'); + +select pgmail('Send From ','Send To ', + 'Subject goes here','','HTML message body here.'); + +Or now, multipart MIME! + +select pgmail('Send From ','Send To ', + 'Subject goes here','Plaintext message body here.', 'HTML message body here.'); In both the Send From and Send To fields, you may include either only the email, or the email enclosed in <> with a plaintext name. From 6e74aa53b32e05656804216b42d9236cd9558528 Mon Sep 17 00:00:00 2001 From: Branden Williams Date: Thu, 16 Nov 2017 07:41:05 -0600 Subject: [PATCH 07/15] Fixed logic bug identified by Nicklas. --- pgMail.sql | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pgMail.sql b/pgMail.sql index 40c960e..b93d5cf 100644 --- a/pgMail.sql +++ b/pgMail.sql @@ -47,13 +47,15 @@ puts $mySock "Subject: $mailsubject" puts $mySock "MIME-Version: 1.0" if {$multipart} { puts $mySock {Content-type: multipart/mixed; boundary="just_a_simple_boundary"} -} elseif {$mailmessage ne ""} { +} +if {$mailmessage ne ""} { if {$multipart} {puts $mySock "--just_a_simple_boundary"} puts $mySock "Content-type: text/plain; charset=UTF-8" puts $mySock "Content-Transfer-Encoding: 8bit" puts $mySock "" puts $mySock "$mailmessage" -} elseif {$mailmessage_html ne ""} { +} +if {$mailmessage_html ne ""} { if {$multipart} {puts $mySock "--just_a_simple_boundary"} puts $mySock "Content-type: text/html; charset=UTF-8" puts $mySock "Content-Transfer-Encoding: 8bit" From b29830d9fa9a390cf6fd836594cb833044690544 Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Tue, 28 Jul 2020 20:24:54 -0500 Subject: [PATCH 08/15] Create codeql-analysis.yml --- .github/workflows/codeql-analysis.yml | 54 +++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 .github/workflows/codeql-analysis.yml diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml new file mode 100644 index 0000000..f76b4e0 --- /dev/null +++ b/.github/workflows/codeql-analysis.yml @@ -0,0 +1,54 @@ +name: "CodeQL" + +on: + push: + branches: [master, ] + pull_request: + # The branches below must be a subset of the branches above + branches: [master] + schedule: + - cron: '0 2 * * 2' + +jobs: + analyse: + name: Analyse + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + with: + # We must fetch at least the immediate parents so that if this is + # a pull request then we can checkout the head. + fetch-depth: 2 + + # If this run was triggered by a pull request event, then checkout + # the head of the pull request instead of the merge commit. + - run: git checkout HEAD^2 + if: ${{ github.event_name == 'pull_request' }} + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v1 + # Override language selection by uncommenting this and choosing your languages + # with: + # languages: go, javascript, csharp, python, cpp, java + + # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). + # If this step fails, then you should remove it and run the build manually (see below) + - name: Autobuild + uses: github/codeql-action/autobuild@v1 + + # ℹī¸ Command-line programs to run using the OS shell. + # 📚 https://git.io/JvXDl + + # ✏ī¸ If the Autobuild fails above, remove it and uncomment the following three lines + # and modify them (or add more) to build your code if your project + # uses a compiled language + + #- run: | + # make bootstrap + # make release + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v1 From a6ba705bd07bf7b92b0f51c12767178a6a6cd5b0 Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Tue, 28 Jul 2020 20:30:50 -0500 Subject: [PATCH 09/15] Delete codeql-analysis.yml Was not a good fit for this project. --- .github/workflows/codeql-analysis.yml | 54 --------------------------- 1 file changed, 54 deletions(-) delete mode 100644 .github/workflows/codeql-analysis.yml diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml deleted file mode 100644 index f76b4e0..0000000 --- a/.github/workflows/codeql-analysis.yml +++ /dev/null @@ -1,54 +0,0 @@ -name: "CodeQL" - -on: - push: - branches: [master, ] - pull_request: - # The branches below must be a subset of the branches above - branches: [master] - schedule: - - cron: '0 2 * * 2' - -jobs: - analyse: - name: Analyse - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v2 - with: - # We must fetch at least the immediate parents so that if this is - # a pull request then we can checkout the head. - fetch-depth: 2 - - # If this run was triggered by a pull request event, then checkout - # the head of the pull request instead of the merge commit. - - run: git checkout HEAD^2 - if: ${{ github.event_name == 'pull_request' }} - - # Initializes the CodeQL tools for scanning. - - name: Initialize CodeQL - uses: github/codeql-action/init@v1 - # Override language selection by uncommenting this and choosing your languages - # with: - # languages: go, javascript, csharp, python, cpp, java - - # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). - # If this step fails, then you should remove it and run the build manually (see below) - - name: Autobuild - uses: github/codeql-action/autobuild@v1 - - # ℹī¸ Command-line programs to run using the OS shell. - # 📚 https://git.io/JvXDl - - # ✏ī¸ If the Autobuild fails above, remove it and uncomment the following three lines - # and modify them (or add more) to build your code if your project - # uses a compiled language - - #- run: | - # make bootstrap - # make release - - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v1 From 0874e16f79ccb67a4f399492c3d2c1f83a9e498d Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Thu, 17 Dec 2020 12:04:01 -0600 Subject: [PATCH 10/15] Create FUNDING.yml --- .github/FUNDING.yml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .github/FUNDING.yml diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..b51b39c --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,3 @@ +# These are supported funding model platforms + +github: captbrando From 1e26f6d9bd4ca42aabb1bc0202f913a99b5bf0fa Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Tue, 10 Dec 2024 08:48:13 -0600 Subject: [PATCH 11/15] Fixed deprecated opaque type return. --- example.setup.sql | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/example.setup.sql b/example.setup.sql index 9a4015e..297a864 100644 --- a/example.setup.sql +++ b/example.setup.sql @@ -6,7 +6,7 @@ create table orders ( paystatus varchar(1) default 'n' ); -create function checkordermail() returns opaque as ' +create function checkordermail() returns trigger as ' DECLARE customerRec RECORD; textMessage text; From b9c0b811e0091acca878a607744395a198bf0c8f Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Tue, 10 Dec 2024 08:48:54 -0600 Subject: [PATCH 12/15] Updated README to include the modern way to add pltclu to your database, as well as removing some outdated instructions. Confirmed this is current with PostgreSQL v15+ --- README | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README b/README index bea6484..e28bf7e 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -pgMail v1.4 (11/16/2017) +pgMail v1.5 (12/10/2024) pgMail is maintained by Branden R. Williams Homepage: http://www.brandolabs.com/pgmail @@ -6,7 +6,7 @@ Homepage: http://www.brandolabs.com/pgmail If you are interested in contributing to the project please email the maintainer directly. ------------------------------------------------------------------ -Copyright 2002-2017 Branden R. Williams. +Copyright 2002-2025 Branden R. Williams. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -28,7 +28,7 @@ which takes 4 arguments of type 'text' (Who is it from, who is it to, subject, and body of message), contacts the email server via TCL sockets, and transmits your email (Now UTF-8 Compatible!). -Before you can use pgMail, you must install the TCL/u procedural +Before you can use pgMail, you must enable the TCL/u procedural language. TCL/u is an UNRESTRICTED version of TCL that the database may use in its stored functions. ** Take into account that you must prepare adequate security precautions when adding @@ -38,13 +38,13 @@ to do bad things. To install the TCL/u procedural language, you must have compiled and installed the TCL extensions of PostgreSQL (or in the binary -versions, just make sure you install the TCL RPM). Once you +versions, just make sure you install the pltcl packages). Once you are sure this has been completed, simply type the following at the unix shell prompt as a database administrator. -# createlang pltclu +# psql -c 'CREATE EXTENSION pltclu' -In the place of , put the name of your database that +In the place of , put the name of your database that you will be adding the stored procedure to. If you want it to also be added to all new databases, use "template1" as your database name. @@ -84,14 +84,14 @@ select pgmail('Send From ','Send To ', In both the Send From and Send To fields, you may include either only the email, or the email enclosed in <> with a plaintext name. +The code in this repository is certified against PostgreSQL 15+. + ------------------------------------------------------------------ Testing your install. There are some examples to try which have been included. You MUST FIRST replace the string in the -example.execute.sql script with your real email address, and -install the plpgsql language just like you did the pltclu above. -You can do that by entering a "createlang [YOUR DATABASE] plpgsql". +example.execute.sql script with your real email address. Once that is complete, execute the example.setup.sql. Then execute the example.execute.sql script. You will see 2 emails From 17cedc812011b6c4e8cd79b26d71f74c0da2d11d Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Tue, 10 Dec 2024 08:49:24 -0600 Subject: [PATCH 13/15] Added utf-8 encoding as a pass to TCL so that the extended character set renders correctly. Thanks Glukhov Sergey for this fix. --- pgMail.sql | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pgMail.sql b/pgMail.sql index b93d5cf..85f1569 100644 --- a/pgMail.sql +++ b/pgMail.sql @@ -31,7 +31,7 @@ if {$fromemailaddress_start != -1} { set fromemailaddress $mailfrom } fileevent $mySock writable [list svcHandler $mySock] -fconfigure $mySock -buffering line +fconfigure $mySock -buffering line -encoding utf-8 puts $mySock "HELO " gets $mySock name puts $mySock "MAIL FROM: $fromemailaddress" From e4e36fdda52de0b3adc8a0a921be6c322dd38a35 Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Tue, 10 Dec 2024 08:51:50 -0600 Subject: [PATCH 14/15] Updated CHANGELOG for v1.5 --- CHANGELOG | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG b/CHANGELOG index 435f650..5aaa509 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,5 +1,12 @@ Change Log. +v1.5 - pgMail has been updated to support the utf-8 character set + inside pltclu. (thanks Glukhov Sergey) + - Updated README to reflect modern PostgreSQL implementations + as some commands and suggestions were actually deprecated. (me) + - Updated the example scripts to use modern trigger return + vs opaque data type. (me) + v1.4 - pgMail now supports both HTML messaging and MULTIPART MIME messaging. It's backwards compatible. If you want to ONLY send HTML, you need to pass an empty string as your 4th argument. From 7a01b3bc5c7164d1128c2483bf3e490fd10da208 Mon Sep 17 00:00:00 2001 From: "Branden R. Williams" Date: Mon, 27 Oct 2025 13:55:35 -0500 Subject: [PATCH 15/15] Refactor README.md for clarity and badges Updated README.md to improve formatting and add badges. --- README | 102 ------------------------------------------------------ README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 102 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index e28bf7e..0000000 --- a/README +++ /dev/null @@ -1,102 +0,0 @@ -pgMail v1.5 (12/10/2024) -pgMail is maintained by Branden R. Williams - -Homepage: http://www.brandolabs.com/pgmail - -If you are interested in contributing to the project please email -the maintainer directly. ------------------------------------------------------------------- -Copyright 2002-2025 Branden R. Williams. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. ------------------------------------------------------------------- -Welcome! This README will be short and sweet so you can get to -coding! - -Essentially, pgMail is simply a stored function written in TCL -which takes 4 arguments of type 'text' (Who is it from, who is it -to, subject, and body of message), contacts the email server via -TCL sockets, and transmits your email (Now UTF-8 Compatible!). - -Before you can use pgMail, you must enable the TCL/u procedural -language. TCL/u is an UNRESTRICTED version of TCL that the -database may use in its stored functions. ** Take into account -that you must prepare adequate security precautions when adding -the TCL/u language to your database! ** The author will not be -responsible for misconfigured servers allowing dangerous users -to do bad things. - -To install the TCL/u procedural language, you must have compiled -and installed the TCL extensions of PostgreSQL (or in the binary -versions, just make sure you install the pltcl packages). Once you -are sure this has been completed, simply type the following at -the unix shell prompt as a database administrator. - -# psql -c 'CREATE EXTENSION pltclu' - -In the place of , put the name of your database that -you will be adding the stored procedure to. If you want it to -also be added to all new databases, use "template1" as your -database name. - -*** BEFORE ADDING THE PROCEDURE TO YOUR DATABASE YOU MUST DO THE *** -*** FOLLOWING!!! *** - -Replace the text with the fully -qualified domain name for your mailserver. i.e., mail.server.com. - -Replace the text with the fully -qualified domain name for your database server. i.e., db.server.com. - -*** NOW ON TO LESS DRAMATIC TEXT! *** - -Once you have completed this step, use the psql interface to -add the pgMail function. Just copy the contents of the -pgmail.sql file and paste it into your window. You may also -load it directly from the command line by typing - -# psql -e [database] < pgmail.sql - -Once you have installed the stored function, simply call the -procedure as follows. - -select pgmail('Send From ','Send To ', - 'Subject goes here','Plaintext message body here.'); - -select pgmail('Send From ','Send To ', - 'Subject goes here','','HTML message body here.'); - -Or now, multipart MIME! - -select pgmail('Send From ','Send To ', - 'Subject goes here','Plaintext message body here.', 'HTML message body here.'); - -In both the Send From and Send To fields, you may include either -only the email, or the email enclosed in <> with a plaintext name. - -The code in this repository is certified against PostgreSQL 15+. - ------------------------------------------------------------------- -Testing your install. - -There are some examples to try which have been included. You -MUST FIRST replace the string in the -example.execute.sql script with your real email address. - -Once that is complete, execute the example.setup.sql. Then -execute the example.execute.sql script. You will see 2 emails -in your mailbox. To remove this example, execute the -example.cleanup.sql script. - -If you have any other questions, please visit the homepage at -http://www.brandolabs.com/pgmail/. Thanks. diff --git a/README.md b/README.md new file mode 100644 index 0000000..94f5193 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +# pgMail v1.5 (12/10/2024) +pgMail is maintained by Branden R. Williams + +![Open Issues](https://img.shields.io/github/issues/captbrando/pgMail) ![Open PRs](https://img.shields.io/github/issues-pr/captbrando/pgMail) ![Last Commit](https://img.shields.io/github/last-commit/captbrando/pgMail) + +Visit the homepage at [BrandoLabs](http://www.brandolabs.com/pgmail) + +If you are interested in contributing to the project please email the maintainer directly. + +--- + +Copyright 2002-2025 Branden R. Williams. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +--- + +## Getting Started + +Welcome! This README will be short and sweet so you can get to coding! + +Essentially, pgMail is simply a stored function written in TCL which takes 4 arguments of type 'text' (Who is it from, who is it to, subject, and body of message), contacts the email server via TCL sockets, and transmits your email (Now UTF-8 Compatible!). + +Before you can use pgMail, you must install the TCL/u procedural language. TCL/u is an UNRESTRICTED version of TCL that the database may use in its stored functions. ** Take into account that you must prepare adequate security precautions when adding the TCL/u language to your database! ** The author will not be responsible for misconfigured servers allowing dangerous users to do bad things. + +To install the TCL/u procedural language, you must have compiled and installed the TCL extensions of PostgreSQL (or in the binary versions, just make sure you install the TCL package for your distribution). Once you are sure this has been completed, simply type the following at the unix shell prompt as a database administrator. + +```bash +# psql -c 'CREATE EXTENSION pltclu' +``` + +In the place of , put the name of your database that you will be adding the stored procedure to. If you want it to also be added to all new databases, use "template1" as your database name. + +**BEFORE ADDING THE PROCEDURE TO YOUR DATABASE YOU MUST DO THE FOLLOWING!** + +* Replace the text with the fully qualified domain name for your mailserver. i.e., mail.server.com. +* Replace the text with the fully qualified domain name for your database server. i.e., db.server.com. + +**NOW ON TO LESS DRAMATIC TEXT!** + +Once you have completed this step, use the psql interface to add the pgMail function. Just copy the contents of the pgmail.sql file and paste it into your window. You may also load it directly from the command line by typing: + +```bash +# psql -e [database] < pgmail.sql +``` + +Once you have installed the stored function, simply call the procedure as follows. + +``` +select pgmail('Send From ','Send To ', + 'Subject goes here','Plaintext message body here.'); + +select pgmail('Send From ','Send To ', + 'Subject goes here','','HTML message body here.'); +``` + +Or now, multipart MIME! + +``` +select pgmail('Send From ','Send To ', + 'Subject goes here','Plaintext message body here.', 'HTML message body here.'); +``` + +In both the Send From and Send To fields, you may include either only the email, or the email enclosed in <> with a plaintext name. + +The code in this repository is certified against PostgreSQL 15+. + +## Testing Your Install + +There are some examples to try which have been included. You MUST FIRST replace the string in the example.execute.sql script with your real email address, and install the plpgsql language just like you did the pltclu above. You can do that by entering a "createlang [YOUR DATABASE] plpgsql". + +Once that is complete, execute the example.setup.sql. Then execute the example.execute.sql script. You will see 2 emails in your mailbox. To remove this example, execute the example.cleanup.sql script. + +If you have any other questions, please visit the [homepage](http://www.brandolabs.com/pgmail/) or open an issue at GitHub.