Email Sending

Control who may email students, how many at a time, from which addresses, and what files may be attached.

Administration → Email Sending (/admin/email-sending), gated on ADMIN.EMAIL_SENDING (migration 268). Anyone holding the node can read the settings; every change requires an acting superuser, whatever the grants say.

How staff email works

Staff write to students from Communications → Compose Email. A message can be addressed to any mix of four kinds of recipient, and each is allowed by its own permission, checked against the role the sender is acting as:

Recipients	Permission	Limit
A section the sender teaches	COMMUNICATIONS.EMAIL_CLASS	Never limited
The sender's current advisees	COMMUNICATIONS.EMAIL_ADVISEES	Never limited
A Student List	COMMUNICATIONS.EMAIL_LISTS	The role's recipient limit
A Cohort	COMMUNICATIONS.EMAIL_LISTS	The role's recipient limit

Migration 268 granted FACULTY the compose screen, the Sent Email screen and EMAIL_CLASS, and ADVISOR the same with EMAIL_ADVISEES. Nobody was granted EMAIL_LISTS: you choose which roles may email lists and cohorts.

"Current advisees" are students with an open advising link to the sender's active advisor record; ended links are history and are not included. Superusers may email any section, and are never limited.

Mail is queued, not sent while the sender waits. Each student receives their own copy, addressed only to them, so no student sees another's address. A student is reached at their current institutional (SCHOOL) address where they have one, else their primary address, else any current address; students with no address on file are listed as skipped before sending. Where several students share one address — siblings on a family address, for instance — that address receives one message. Delivery status for each recipient is on the sender's Sent Email page.

Email cannot be sent while impersonating: it would leave under the impersonated person's name, from their address, to real students.

Both the compose editor and the email template editor have a table toolbar: insert a 3 × 3 table, add a row below or a column to the right, delete a row, column or table. A staff message keeps paragraphs, emphasis, lists, links, h2/h3 headings and tables; everything else — scripts, styles, colors, any other attribute — is stripped, except that table cells keep colspan/rowspan values from 1 to 20. Because mail clients ignore style sheets, tables in staff messages and in templates are given fixed inline borders and padding when the mail is built, so they arrive ruled in every client. Styling a template already carries on a table is kept after those defaults, so it still wins.

Role limits

The Role limits tab lists every role with three columns:

Column	Meaning
May email lists	Whether the role holds COMMUNICATIONS.EMAIL_LISTS
Recipient limit	The most students one message may reach through Student Lists and Cohorts, or No limit
May use no-reply	Whether the role may choose the no-reply address as the From

Granting list email is two steps, and both are required:

1. Grant COMMUNICATIONS.EMAIL_LISTS ("Email Student Lists") to the role on the Permissions screen.
2. Set the role's limit here — a number, or explicitly No limit.

A role with the permission but no limit is refused

Forgetting the limit never means "unlimited". Until a limit (or No limit) is set, the role's list and cohort sends are refused with a message telling the sender to ask a system administrator, and the screen flags the role. Clear removes a role's settings and puts it back in that state.

The limit counts distinct students reached through lists and cohorts in one message, after duplicates are removed. Students reached through the sender's own sections or advisees in the same message do not count toward it. A message over the limit is refused with the count and the limit; the compose screen shows the running total before sending.

The limit follows the role the sender is acting as, like every other permission. A limit set on a role that does not hold EMAIL_LISTS has no effect until it does; the no-reply setting applies to all of that role's email.

Shared sender addresses

By default a sender may send only from their own institutional addresses — the current addresses on their person record that are of type SCHOOL or at a protected institution domain. The Shared sender addresses tab adds institutional mailboxes that several people send from, such as an office address, and says who may use each.

1. Add Address — the email address (it must be at a protected institution domain) and an optional display name, such as Office of the VPAA. The display name is used as the From name.
2. Assign a person — search by name or email. Each assigned person sees the address as a choice in the From list.

Deactivating an address hides it from everyone's From list without removing the assignments; deleting it removes them.

Never give someone a shared mailbox as a person email

A shared mailbox is deliberately not added to the sender's person record. An address at an institution domain on a person record is an identity claim: SSO links a login to whoever holds the matching address, and the nightly import chooses login emails from the same rows. Putting registrar@ on three people's records would make the registrar mailbox's own SSO login resolve to one of them. Use this tab instead.

The no-reply address

Administration → System Settings → No-reply address (setting EMAIL_NOREPLY_ADDRESS, seeded as no-reply@puc.edu). System notifications are sent from it, and senders whose role has May use no-reply (and superusers) may choose it as the From of their own email. A line telling recipients not to reply is added to the end of any message sent from it.

It must be a plain address at a protected institution domain, and cannot be blank; the save is refused otherwise. It should be a mailbox that does not accept mail. While it is unset, system notifications fall back to SMTP_FROM and nobody is offered a no-reply From. An edit reaches senders within about 30 seconds.

Attachments

The Attachments tab decides what files may be attached to email (migration 305). Like the rest of this screen it is readable by anyone holding ADMIN.EMAIL_SENDING, and only an acting superuser may change it. Limits come in layers, and a file must pass every layer that applies:

1. Organization limit — the ceiling: allowed file types, the largest single file, the most files, and the most in all. No kind of sending can allow more than this.
2. By kind of sending — one policy per surface, each switched on or off, with its own types and numbers inside the organization limit.
3. Per template — for email templates only, each template's own allowance inside the Email templates surface (see below).

Surface	Sending to	As seeded
COMPOSE.SECTION	A class — a teacher emailing a section they teach	Off; pdf, docx, xlsx, pptx, csv, txt, png, jpg, jpeg; 5 MB a file, 5 files, 15 MB in all
COMPOSE.ADVISEES	Advisees — an advisor emailing their advisees	Off; same as a class
COMPOSE.LISTS	Student lists and cohorts	Off; pdf, png, jpg, jpeg; 2 MB, 2 files, 4 MB
TEMPLATE	Email templates — the most any one template may allow	Off; pdf only; 2 MB, 2 files, 4 MB
NOTES	Student notes — files attached to a note on a student record (migration 308)	On; same types as a class; 5 MB, 5 files, 10 MB

The organization limit was seeded with the same nine types, 5 MB a file, 5 files and 15 MB in all. Nothing can be attached to email until a superuser switches a surface on; student notes, which are an internal record rather than mail, are the one surface seeded on. The surface list is fixed by the code; there is no way to add one.

The numbers allowed anywhere are 1–25 MB a file, 1–20 files and 1–25 MB in all, and the total may not be smaller than the per-file limit. Mail is larger in transit than its files — 15 MB of attachments is about 20 MB on the wire — so keep totals inside what the mail relay and recipients' mailboxes accept.

How the layers combine. What actually applies is the intersection: only types every layer allows, and the smallest of each number. Saving a surface policy that exceeds the organization limit is refused. Lowering the organization limit later does not rewrite the surfaces; their effective limits simply shrink, and the screen flags a surface whose own setting is above the organization limit. A message that mixes sources — a class and a cohort, say — gets the strictest of the surfaces it uses. Superusers are held to these limits too.

Types that can never be allowed. Whatever is entered, these are refused, and the screen lists them: executables and scripts (exe, dll, msi, bat, cmd, ps1, js, vbs, sh, jar, lnk, hta, reg, disk images and installer packages, and the like), macro-enabled Office files (docm, xlsm, pptm and their template and add-in forms), markup a mail client or browser would render (html, htm, xhtml, svg, xml, mht, mhtml), and archives (zip, 7z, rar, gz, tar, and the like), which could carry any of the others past the type check.

The file must be what its name says. Each file's bytes are checked against its extension: a .pdf must start as a PDF, a .docx/.xlsx/.pptx must be an Office (zip) package, images must be the image type named, and text types must be plain text, not HTML. A renamed executable or web page is refused with "File … is not really a … file". A file with no extension, or an empty file, is refused too. The type a browser declares is ignored; the stored type is derived from the extension.

Where the files go

Files are stored in the database, once per message however many recipients it has (core.email_message_attachments), and the outbox worker attaches them to every recipient's copy. If the files cannot be loaded, that recipient's delivery waits and is retried rather than going out without them. Senders download the files from their Sent Email page, and anyone allowed to read a student's Communications tab can download the files of messages that student received, under the same access rules as the message itself. Downloads are always served as a file to save, never opened in the browser.

Attachments on email templates

System email templates can carry fixed files — a form a drop notice refers to, a policy PDF sent with a probation alert. They are set in the template editor (Administration → Email Templates, ADMIN.EMAIL_TEMPLATES), in an Attachments panel below the body; a superuser is not needed there.

• Allow attachments on this template turns the template on, with its own number of files, size per file and size in all. These must fit inside the Email templates surface; file types always come from that surface and are not set per template. A template that has never been set up takes no attachments.
• Files are added and removed in the same panel. Changes take effect immediately, separately from the template's Save. A new template must be saved first, then reopened, before files can be attached.
• While the Email templates surface is off, the panel says so, and no template can attach anything.

Template files are checked when they are added and again every time an email is sent from the template, against the template's limits as they stand at that moment. Switching off or narrowing any layer — the organization limit, the Email templates surface, or the template's own allowance — takes effect on the next send. If the template's files no longer pass, they are left off and the send is logged; the notification itself still goes. The editor warns when attached files no longer fit the template's settings.

Fixed attachments are included by the notifications that build their mail from a template with files: workflow-engine notifications, course drop notices, program-change notices, the probation threshold alert, and enrollment verification letters. Student note notifications never carry files.

Institutional addresses are superuser-only

The same rule that protects shared mailboxes protects everyone's own institutional address. An email address is institutional when its type is SCHOOL, or when it is at an active, protected institution domain (subdomains included). Both halves count: Colleague files some institutional addresses under personal types.

Only an acting superuser may add, change or retire an institutional address, on a person's record, through a person's own profile, and when setting a person's primary email. Everyone else is refused, and the contact forms warn before saving. The nightly Colleague import writes addresses directly and is unaffected.

Institution domains

Institution domains (Administration → Institution Domains, ADMIN.DOMAINS) define which addresses are institutional, so changing one — in particular unprotecting it — would hand out the power to create institutional addresses. Creating, editing and deleting institution domains is therefore superuser-only too, whatever ADMIN.DOMAINS grants say. Reading them is not.

Not carried by Permission Transfer

Role limits, the no-reply permission, shared sender addresses and attachment limits are institution policy edited in production. They live in their own tables (core.role_email_policies, core.sender_addresses, core.sender_address_grants, core.email_attachment_limits, core.email_attachment_policies, core.email_template_attachment_settings) rather than on the role, and are not part of a Permission Transfer bundle. Every change to them is written to the Audit Trail, so who widened what may be attached is on record. The outbox itself (core.email_messages, core.email_message_recipients) is not audited: it is already the record of what was sent, by whom, to whom. Nor are the attachment files (core.email_message_attachments, core.email_template_attachments): row auditing would copy every file into the audit log.

Delivery

The outbox is drained by a worker inside the API, at most EMAIL_SEND_PER_MINUTE messages a minute (default 120), one message per recipient. A failed delivery is retried after 1, 4, 9 and 16 minutes; after five attempts the recipient is marked Failed. A message's status — Queued, Sending, Sent, Partly sent or Failed — is recomputed from its recipients. Whether mail reaches real mailboxes at all is decided per instance by EMAIL_DELIVERY; see Environment Configuration.

Related

• Emailing Students — the sender's view
• Permissions
• Roles
• Communications API — including the attachment-limit endpoints
• Core API — email templates and their attachments