@@ -6,36 +6,71 @@ Therefore, it is best to use an unimportant email account to send out your email
...
@@ -6,36 +6,71 @@ Therefore, it is best to use an unimportant email account to send out your email
You can use any account as the receiver of emails, e.g. one you check regularly.
You can use any account as the receiver of emails, e.g. one you check regularly.
## 1. Gather information
Whatever email service you decide to use for sending emails, you must be able to connect to its SMTP server and the provider should have a help, FAQ, or Knowledge Base article with this information in it.
Whatever email service you decide to use for sending emails, you must be able to connect to its SMTP server and the provider should have a help, FAQ, or Knowledge Base article with this information in it.
You will need to know your email provider's:
You will need to know your email provider's:
- SMTP Server Address (e.g. `smtp.gmail.com` for Gmail)
- SMTP Server Address (e.g. `smtp.gmail.com` for Gmail)
- SMTP TLS Port (e.g. `587` for Gmail
- SMTP TLS Port (e.g. `587` for Gmail
- SMTP Username (e.g. `youremailaddress@gmail.com` for Gmail)
- SMTP Login Username (e.g. `your_outgoing_email_address@gmail.com` for Gmail)
- SMTP Password (your account's password OR app-specific password OR API-key, depending on what your provider says)
- SMTP Login Password (your account's password OR app-specific password OR API-key, depending on what your provider says)
If you are using Gmail and have enabled 2-factor authentication then you will need to generate an 'app-specific password' to be able to send emails from the account. [See here for more information](https://support.google.com/accounts/answer/185833).
If you are using Gmail and have enabled 2-factor authentication then you will need to generate an 'app-specific password' to be able to send emails from the account. [See here for more information](https://support.google.com/accounts/answer/185833).
## 2. Edit email_secrets.json
Once you have the necessary information, follow these instructions:
Once you have the necessary information, follow these instructions:
1. Go to the CAML folder and open `email_secrets_DIST.json` in a text editor.
1. Go to the CAML folder and open `email_secrets_DIST.json` in a text editor.
2. Save the file as `email_secrets.json` (removing the _DIST part of the original name).
2. Save the file as `email_secrets.json` (removing the _DIST part of the original name).
3. Double-check that you are editing `email_secrets.json` and not the original distributed file.
3. Double-check that you are editing `email_secrets.json` and not the original distributed file.
4. Edit the JSON variables with your information for the email account which will **send** the notification emails.
- If you edit the original distributed file then email notifications will not work.
4. Edit the JSON variables with your information for the email accounts which will send and receive notifications.
- The JSON file contains some example settings; replace them with your own.
- The JSON file contains some example settings; replace them with your own.
- Ensure that you don't accidentally delete important apostrophe or comma characters!
- Ensure that you don't accidentally delete important apostrophe, colon, or comma characters!
-It should look like the example below, except with your settings.
-Refer to the explanation of variables, and the example, shown below.
5. Save the file and exit your text editor.
5. Save the file and exit your text editor.
6. In scripts that support email notifications, edit the variables at the top of the script to enable the notifications and the email address which will **receive** the emails -- the address to send notifications can be any valid email address (so you can put your work email here if you want).
Example `email_secrets.json` file:
### Variables in email_secrets.json
Variables are either to do with the *sender* account (the account the script will use to send emails out from) or the *recipient* (the address that those emails are sent to). To send emails out, you need to login to an email server.
|Variable Name |Example Value |Description |
| ------ | ------ | ------ |
|sender_name |"CAML Notifier" |Emails will come from this name |
|sender_email_addr |"SetecAstronomy@gmail.com" |Emails will come from this email address |
|sender_login |"SetecAstronomy@gmail.com" |The username to login to the email server for sending from the above address. |
|sender_passwd |"Z3r0C00l_1337" |The password for the above login username. |
|sender_host_name |"smtp.gmail.com" |The hostname of the email server. |
|sender_host_port |587 |The TLS port of the email server. |
|recipient_email_addr |"pmkatz2@big.ac.uk" |The email address which will receive the notification emails. |
|recipient_name |"Perini" |The name to use in the notification emails. |
### Example `email_secrets.json` file
Using the above settings, a correctly formatted email_secrets.json file would look like this:
```json
```json
{
{
"host_name":"smtp.gmail.com",
"sender_name":"CAML Notifier",
"host_port":587,
"sender_email_addr":"SetecAstronomy@gmail.com",
"sender_uid":"SetecAstronomy@gmail.com",
"sender_login":"SetecAstronomy@gmail.com",
"sender_pwd":"Z3r0C00l_1337"
"sender_passwd":"Z3r0C00l_1337",
"sender_host_name":"smtp.gmail.com",
"sender_host_port":587,
"recipient_email_addr":"pmkatz2@big.ac.uk",
"recipient_name":"Perini"
}
}
```
```
## 3. Enable (or disable) email notifications in scripts
In scripts for Stage 1, 4, and 5, edit the value of the `EmailUponCompletion` variable to change if notification emails should be sent.
This variable can be one of three values:
-`yes` - Always send email notitications when that script is run.
-`no` - Never send email notitications when that script is run.
-`ask` - The user will asked (via the console) if emails should be sent when the run is complete. The question will be asked again for each new run of the script.
