{"id":17277856,"url":"https://github.com/zen-juen/autoremind","last_synced_at":"2025-04-14T09:20:23.106Z","repository":{"id":54886035,"uuid":"286810584","full_name":"zen-juen/AutoRemind","owner":"zen-juen","description":"A Python email automation system :e-mail: for sending customizable reminders to participants at different timepoints throughout a study","archived":false,"fork":false,"pushed_at":"2020-10-26T05:32:32.000Z","size":221,"stargazers_count":17,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T09:19:52.433Z","etag":null,"topics":["automatic-email-sender","automation","csv-format","email-notification","email-sender","mailing-address-formatter","python","research-tool","smtp","smtplib"],"latest_commit_sha":null,"homepage":"","language":"Python","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/zen-juen.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}},"created_at":"2020-08-11T17:46:16.000Z","updated_at":"2024-07-03T02:19:28.000Z","dependencies_parsed_at":"2022-08-14T05:50:10.159Z","dependency_job_id":null,"html_url":"https://github.com/zen-juen/AutoRemind","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/zen-juen%2FAutoRemind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-juen%2FAutoRemind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-juen%2FAutoRemind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-juen%2FAutoRemind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zen-juen","download_url":"https://codeload.github.com/zen-juen/AutoRemind/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852186,"owners_count":21171843,"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":["automatic-email-sender","automation","csv-format","email-notification","email-sender","mailing-address-formatter","python","research-tool","smtp","smtplib"],"created_at":"2024-10-15T09:10:10.960Z","updated_at":"2025-04-14T09:20:18.095Z","avatar_url":"https://github.com/zen-juen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# :e-mail: Automate Reminder Emails for Research Participants\n\n**AutoRemind** is a Python email automation system for sending customizable reminders to participants at different timepoints throughout a study.\n\nCheck out [AutoCalendar](https://github.com/zen-juen/AutoCalendar/) too!\n\n## :star: Most Ideal For\nThis code was written for a very specific study protocol after a personally exasperating experience of manually emailing participants :smile:\nThis system will be useful if your study is **longitudinal** and comprises of\n- Screening participants for *eligibility*\n- Sending *different reminder emails* for *several sessions* across a period of time\n\n## :bulb: Features\n1) Sends emails to inform participants of their **eligibility**\n2) Sends emails to participants to seek **confirmation of their session slots**\n3) Sends reminder emails to scheduled participants **one day before each session**\n4) Sends reminder emails to scheduled participants on the **day of the session**\n   - The message template in `autoremind.py` has this as an email reminder to complete a health and travel declaration form on the morning of the experiment.\n\n## :tada: Try it Yourself \nThe example csv files in this repository are meant to facilitate trial-and-error with AutoRemind. Simply change the `email` entries in the csv files to your own email address to receive templates of the messages as laid out in `autoremind.py`. You would also need to have a `secret.py` file containing your gmail credentials. If an authentication error occurs, it is most likely because you have to change the [settings](https://myaccount.google.com/u/1/lesssecureapps?pageId=none) in your gmail account to allow access to less secure apps.\n\n### In summary, you should have\n- Two separate files containing information of participants who are eligibile vs. ineligible (`example_eligible.csv` and `example_ineligible.csv` respectively)\n  - Columns required for email customization:\n    - *Name*\n    - *Email*\n \n- One file containing information of scheduled participants:\n  - Columns required for email customization:\n    - *Participant Name*\n    - *Email*\n    - *Phone*\n    - Session 1 Details: *Date_Session1*, *Timeslot_Session1*, *Location_Session1*\n    - Session 2 Details: *Date_Session2*, *Timeslot_Session2*, *Location_Session2*\n    - *Timeslots Confirmed*\n\nIf you have more than two sessions in your experiment, you can customize your own code to include them.\n\n### Code Structure\n\n- **Extract participants**:\n  - `get_new()`: extracts email addresses of unread emails\n  - `get_participants()`: imports csv files for eligible, non-eligible, and scheduled participants\n- **Filter participants**:\n  - `target_eligibility()` identifies participants to be informed for being eligibility or non-eligible, with the ability to exclude participants who were already informed before.\n  - `target_confirmation()` identifies participants who have been scheduled and need to be confirmed of their slots (if the column *Timeslots Confirmed* is *No*)\n  - `target_participants()` identifies participants that need to be sent reminders today or tomorrow.\n- **Execute Sending**\n  - `send_research_info()`: send emails to new email addresses regarding research participation information\n  - `send_inform_eligible()`: send emails to participants based on whether they were eligible or not \n  - `send_session_confirmation()`: send emails to seek confirmation of session slots from participants\n  - `send_session_reminder()`: send reminder email one day before respective sessions (for now, the code accommodates only Session 1 and Session 2)\n  - `send_declaration_form()`: send health and travel (for COVID-19) declaration forms on the day of the session\n \n ### Execute It\n \nThese functions are then wrapped in `autoremind()`, which you can choose to control the sending of a certain type of emails.\nRunning `autoremind.py` will mass send the desired mails to your participants together with ***printed feedback*** on **how many subjects** and **exactly who** were contacted, like so:\n\n- For example, if you only want to send one-day-prior and on-the-day reminders, and eligibility information, set `send_reminders`, `send_eligible` and `send_forms` to `True`. Once you're happy with the customization, you can execute the sending.\n```\nautoremind(participants_list, silent=False, send_research=False, send_eligible=True, send_reminders=True, send_forms=True)\n\n### Printed feedback ###\n2 eligible participants contacted.\n3 ineligible participants contacted.\nSending successful eligibility outcome to: ['Subject11', 'Subject12']\nSending unsuccessful eligibility outcome to: ['Subject19', 'Subject20', 'Subject21']\none day before: No session 1 participants to be contacted.\none day before: 1 participants to be contacted for session 2.\nSending reminder emails to: ['Subject_3'].\nexperiment day: No session 1 participants to be contacted.\nexperiment day: 2 participants to be contacted for session 2.\nSending health and travel declaration forms to: ['Subject_1', 'Subject_2']\n```\n\n- On the other hand, if you only want to send recruitment information to new email addresses (whose emails are still unread), set just `send_research=True`.\n  - IMPORTANT: this is assuming ALL unread emails are indeed seeking recruitment information. Filter your inbox appropriately first e.g., make sure you read and reply to other types of emails.\n\n```\nautoremind(participants_list, silent=False, send_research=True, send_eligible=False, send_reminders=False, send_forms=False)\n\n### Printed feedback ###\nRetrieving unread emails\nSending research recruitment information to: ['insertyouremail1@gmail.com', 'insertyouremail2@e.ntu.edu.sg']\n```  \n\n## :heavy_check_mark: Potential New Features for AutoRemind\n\n- [ ] Participants Scheduling\n  - I have not yet thought of how best to automate the scheduling of participants for multiple sessions, assuming that the interval between these sessions needs to be within a certain range i.e., Session 1 must be a week before Session 2. If anyone has any ideas, feel free to open an issue in this repo!\n- [ ] Sending out Emails at Designated time \n  - Not sure if I can do this with GitHub actions\n- [x] Safety feature\n  - Script to include parameters that allow `True` or `False` to activate only certain types of email actions. Defaults to `False` otherwise.\n## Other Resources\n- [autoemailer.py](https://github.com/colinquirk/autoemailer/) which also greatly inspired this repository!\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzen-juen%2Fautoremind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzen-juen%2Fautoremind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzen-juen%2Fautoremind/lists"}