{"id":20695688,"url":"https://github.com/ibm-cloud/cloudmailer","last_synced_at":"2025-10-16T18:22:53.011Z","repository":{"id":83585858,"uuid":"374951263","full_name":"IBM-Cloud/cloudmailer","owner":"IBM-Cloud","description":"IBM Cloud Functions action to send out email via SMTP","archived":false,"fork":false,"pushed_at":"2021-06-15T06:50:19.000Z","size":52,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-17T18:18:21.051Z","etag":null,"topics":["ibm-cloud","ibm-cloud-functions","nodemailer","openwhisk","serverless","smtp"],"latest_commit_sha":null,"homepage":"https://www.ibm.com/cloud/blog/a-serverless-function-for-sending-emails-on-ibm-cloud","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IBM-Cloud.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":"2021-06-08T09:13:44.000Z","updated_at":"2023-03-17T23:48:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"9d95e54f-ceb9-4e5d-be51-b89af16dcd71","html_url":"https://github.com/IBM-Cloud/cloudmailer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fcloudmailer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fcloudmailer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fcloudmailer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fcloudmailer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IBM-Cloud","download_url":"https://codeload.github.com/IBM-Cloud/cloudmailer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242961754,"owners_count":20213315,"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":["ibm-cloud","ibm-cloud-functions","nodemailer","openwhisk","serverless","smtp"],"created_at":"2024-11-17T00:10:29.363Z","updated_at":"2025-10-16T18:22:52.911Z","avatar_url":"https://github.com/IBM-Cloud.png","language":"JavaScript","readme":"# Send emails using IBM Cloud Functions\nUse a simple [IBM Cloud Functions](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-getting-started) action to send out emails via SMTP. Pass in the SMTP server configuration and the email using JSON objects. \nFor ease of use, bind the server configuration to the action and only pass in the email to send.\n\nThe following screenshot shows an email based on [this sample properties](email.blog.json).\n\n![sample email](images/20210609_Sample_Email.png)\n\nSee the blog post [A Serverless Function for Sending Emails on IBM Cloud](https://www.ibm.com/cloud/blog/a-serverless-function-for-sending-emails-on-ibm-cloud) for some background and more links.\n\n## Deploy\n\n### Using the IBM Cloud CLI\nUse the [IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-getting-started) and the [Cloud Functions plugin](https://cloud.ibm.com/docs/cli?topic=cloud-functions-cli-plugin-functions-cli) to deploy the action. Log in to IBM Cloud, [set the namespace](https://cloud.ibm.com/docs/cli?topic=cloud-functions-cli-plugin-functions-cli#cli_namespace_target) and then run:\n\n```sh\nibmcloud fn deploy -m Cloudmailer.yaml\n```\n\nCopy over [smtp_config.sample.json](smtp_config.sample.json) to, e.g., **smtp_config.sendgrid.json**. Then adapt the file (see [SMTP server configuration](#smtp-server-configuration)) and use it to set the SMTP configuration as default:\n\n```sh\nibmcloud fn action update cloudmailer/sendEmail   -P smtp_config.sendgrid.json\n```\n\nBe aware that typically the port 25 is blocked. Many email providers are using ports like 465 or 587.\n\nInstead of using the IBM Cloud CLI, you can also go to the [IBM Cloud Functions portal](https://cloud.ibm.com/functions/) and create the action there. Use the source from [smtp_email.js](smtp_email.js) for the action.\n\n### Using Terraform\n\nGo into the [tf](tf) directory. You may want to adapt the [provider configuration file](tf/provider.tf) to match your overall environment. Either change [tf/variables.tf](tf/variables.tf) or better override some values in a separate **terraform.tfvars** file. There, you may want to set the IBM Cloud API key to use and change the SMTP server configuration. Set the variable **server_config** similar to shown in the file **variables.tf**, e.g., for SendGrid:\n\n```\nserver_config= \u003c\u003cEOF\n   [ \n      {\n        \"key\":\"server\",\n        \"value\": {\n            \"host\": \"smtp.sendgrid.net\",\n            \"port\" : 465,\n            \"id\": \"apikey\",\n            \"password\": \"your-api-key\"\n        }\n      }\n    ]\n\nEOF\n\n```\n\nThen, initialize Terraform the usual way with `terraform init`, check that everything will be applied ok by `terraform plan`. Finally, to deploy, run:\n```sh\nterraform apply\n```\n\nIt will create a new IAM namespace in IBM Cloud Functions and the action **sendEmail** in the package **cloudmailer**.\n\nTo expose the action as secured web action, see the comments in [tf/variables.tf](tf/variables.tf). See the section on [exposing the sendMail action as web action](#expose-the-sendmail-action-as-web-action) below for further details.\n\n\n## Send emails\n\nTo send an email, invoke the action and pass in the JSON object with the email properties. Use [email.sample.json](email.sample.json) and copy it over to a new file, e.g., [email.blog.json](email.blog.json). Edit it to your needs like shown. The email can include plain text in the **text** property, an HTML version in the **html** property or both.\n\n\n### Send emails using the CLI\n\nOnce you or your app have composed an email object, send the email by [invoking the action](https://cloud.ibm.com/docs/openwhisk?topic=cloud-functions-cli-plugin-functions-cli#cli_action_invoke) using the IBM Cloud CLI:\n\n```sh\nibmcloud fn action invoke cloudmailer/sendEmail -r  -P email.json \n```\n\nTo send out an email using another SMTP server configuration, you can pass in both the server config and the email properties:\n```sh\nibmcloud fn action invoke cloudmailer/sendEmail -r  -P email.json -P smtp_config.myserver.json\n```\n\n### Send emails using the API\n\nYou can [invoke the sendMail action via API](https://cloud.ibm.com/apidocs/functions#invokeaction). For testing, use the tool **curl**. See the documentation for sample code in some programming languages. Calling an API function requires a valid IBM Cloud IAM access token. In the following example, we first obtain the token and assign its value to an environment variable. Thereafter, we use the token for a curl to send a POST request to invoke the action. The email properties are passed in from a file.\n\n```\nexport TOKEN=$(ibmcloud iam oauth-tokens --output json | jq -r .iam_token)\n\ncurl -X POST --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/04a49bd4-xxxx-xxxx-xxxx-07be0c9b732b/actions/cloudmailer/sendEmail?blocking=true\u0026result=true' -H 'Accept: application/json' -H \"Authorization: $TOKEN\"  -H 'content-type: application/json' -d @email.json\n```\n### Expose the sendMail action as web action\n\nAnother option is to turn the action into a web action. See the [IBM Cloud Functions documentation on web actions](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-actions_web) for details. You should secure the web action with one of the offered methods, so that only authorized users can send emails.\n\nOnce deployed, you can test the REST API using **curl**. A call would look like this with the email read from a file again:\n\n```sh\ncurl -X POST https://us-south.functions.appdomain.cloud/api/v1/web/d1ee1c70-xxxx-yyyy-zzzz5-000a41115d3e/cloudmailer/sendEmail.json -H  \"X-Require-Whisk-Auth: your-web-secret\"  -H \"Content-Type: application/json\" --data @email_to_send.json\n```\n\n\n## SMTP server configuration\nSome notes on common scenarios.\n\n### Use with your custom domain and SMTP server\n\nSMTP / email setup differs depending on your provider. If your provider allows API keys instead of username / password, go with API keys. You may also create a dedicated email account to send out emails. The typical structure for your smtp_config.json looks like this:\n\n```\n{\n    \"server\": {\n        \"host\": \"smtp.example.com\",\n        \"port\" : 465,\n        \"id\": \"yourname@example.com\",\n        \"password\": \"your-password\"\n    }\n}\n```\n\n\n### Use with SendGrid\n\n[IBM Cloud integrates with SendGrid for email delivery](https://cloud.ibm.com/catalog/infrastructure/email-delivery). You can sign up for SendGrid, then use its [SMTP service](https://sendgrid.com/docs/for-developers/sending-email/getting-started-smtp/) with the action from this repository. See the SendGrid documentation or the [IBM Cloud Email Delivery](https://cloud.ibm.com/docs/email-delivery?topic=email-delivery-about-email-delivery) documentation for details.\n\nTo send emails, create an API key with at least **Mail Send** privileges. The SMTP configuration, e.g., **smtp_config.sendgrid.json** would then look similar to this:\n```\n{\n    \"server\": {\n        \"host\": \"smtp.sendgrid.net\",\n        \"port\" : 465,\n        \"id\": \"apikey\",\n        \"password\": \"your-api-key\"\n    }\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud%2Fcloudmailer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibm-cloud%2Fcloudmailer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud%2Fcloudmailer/lists"}