# Email Setup in OutSystems: SMTP Configuration, Templates, and Attachments

- Tool: OutSystems
- Difficulty: Intermediate
- Time required: 30-40 min
- Compatibility: OutSystems 11 and ODC
- Last updated: March 2026

## TL;DR

Configure SMTP in Service Center → Administration → Email → Outgoing Email Settings. Create Email screens in Interface tab with dynamic expressions for content. Call Send_Email from a Server Action, passing the email screen name and input parameters. Attach files by populating the Attachments input with a list of EmailAttachment structures containing Binary Data.

## Email in OutSystems: SMTP to Template to Send

OutSystems treats email as a first-class feature: Email screens are designed like web screens but rendered to HTML email, SMTP is configured once per environment, and sending is a single Server Action call. This tutorial covers the full flow from SMTP setup to a dynamic welcome email with a PDF attachment, tested end-to-end.

## Before you start

- An OutSystems 11 environment with Service Center admin access, or an ODC environment
- SMTP server credentials (host, port, username, password) — use a service like SendGrid, Mailgun, or your corporate email server
- Service Studio with a Reactive Web App open

## Step-by-step guide

### 1. Configure SMTP in Service Center (O11)

Navigate to Service Center (environment-url/ServiceCenter). Login as an administrator.

Path: Administration → Email → Outgoing Email Settings.

Fill in:
- Server name (SMTP host): e.g., smtp.sendgrid.net
- Port: 587 (STARTTLS) or 465 (SSL/TLS)
- Enable TLS/SSL: Yes
- Username: your SMTP username
- Password: your SMTP password
- Test connection → Save

For Gmail SMTP: use smtp.gmail.com, port 587, enable 'Less secure app access' or use App Passwords.

For SendGrid: Server = smtp.sendgrid.net, Port = 587, Username = 'apikey', Password = your SendGrid API key.

After saving, the SMTP settings apply to ALL modules in this environment. Different environments (Dev, QA, Prod) can have different SMTP settings.

**Expected result:** The Test Connection button returns 'Connection successful'. Email sending is now available for all modules in this environment.

### 2. Create an Email screen in the Interface tab

Email screens in OutSystems are specialized screens designed to produce HTML email content. They support Expression widgets with dynamic data and OutSystems UI email layout blocks.

In Service Studio: Interface tab → Email (email-specific UI flow, separate from your regular UI flows). Right-click → 'Add Email'. Name it 'WelcomeEmail'.

Add input parameters to the Email: right-click WelcomeEmail → Add Input Parameter:
- UserName: Text
- ActivationLink: Text

Design the email body in the Screen Editor. Use:
- Text widgets for static content
- Expression widgets for dynamic content: UserName, ActivationLink
- The built-in email layout that provides a basic header/body/footer structure

Example email body:
'Hello [Expression: UserName],' + newline + 'Welcome to our platform. Click here to activate your account: [Link: ActivationLink]'

**Expected result:** WelcomeEmail screen appears in Interface tab → Email with two input parameters and designed content visible in the Screen Editor.

### 3. Send the email from a Server Action

The Send_Email action is a built-in system action in Logic tab → System → Email.

Create or open the Server Action where you want to send the email (e.g., 'RegisterUser' Server Action). After the user registration logic:

Drag Send_Email from Logic tab → System → Email into the action flow.

Send_Email input parameters:
- From: 'noreply@yourapp.com' (or a Site Property: Site.SenderEmail)
- To: UserEmail
- Subject: 'Welcome to Our Platform — Please Activate Your Account'
- Bcc: '' (optional)
- Cc: '' (optional)
- [Email Screen]: WelcomeEmail (select from dropdown)
  - UserName: NewUser.Name
  - ActivationLink: ActivationURL

The email screen input parameters are mapped directly in the Send_Email call node. The platform renders the email screen to HTML and sends it.

```
/* Send_Email action parameters */
From:           "noreply@yourapp.com"
To:             NewUser.Email
Subject:        "Welcome to Our Platform"
CC:             ""
BCC:            ""
Email:          WelcomeEmail
  UserName:     NewUser.Name
  ActivationLink: ActivationURL

/* Full Server Action flow */
Start
  --> CreateUser: (user registration logic)
  --> Assign: ActivationURL = BaseURL + "/activate?token=" + ActivationToken
  --> Send_Email: (parameters above)
  --> End
```

**Expected result:** After completing user registration, the welcome email is sent to the user's email address. Check Service Center → Monitoring → Email for delivery status.

### 4. Add a file attachment to the email

Send_Email accepts an Attachments input parameter — a list of EmailAttachment structures.

EmailAttachment structure (from System library):
- FileContent: Binary Data (the file content)
- FileName: Text (the filename shown in the email)
- MimeType: Text (e.g. 'application/pdf')

To attach a PDF invoice:
1. Create Local Variable 'EmailAttachments' of type EmailAttachment List
2. Create Local Variable 'Attachment' of type EmailAttachment
3. Assign: Attachment.FileContent = InvoicePDF, Attachment.FileName = 'Invoice.pdf', Attachment.MimeType = 'application/pdf'
4. Call ListAppend(EmailAttachments, Attachment) — drag ListAppend from Toolbox → Built-in Functions → List
5. In Send_Email, set Attachments = EmailAttachments

```
/* Building attachments list */
Assign:
  Attachment.FileContent = InvoicePDFContent  /* Binary Data */
  Attachment.FileName    = "Invoice_" + IntegerToText(InvoiceNumber) + ".pdf"
  Attachment.MimeType    = "application/pdf"

ListAppend(EmailAttachments, Attachment)

/* Send_Email with attachments */
Send_Email:
  From:        Site.SenderEmail
  To:          Customer.Email
  Subject:     "Your Invoice #" + IntegerToText(InvoiceNumber)
  Email:       InvoiceEmail (email screen)
  Attachments: EmailAttachments
```

**Expected result:** The recipient receives the email with the PDF invoice attached and visible in their email client.

### 5. Monitor email delivery in Service Center

After sending emails, check delivery status in Service Center.

Path: Monitoring → Email. You see a log of all sent emails with:
- Sent timestamp
- From, To addresses
- Subject
- Status: Sent, Error, Queued
- Error details if delivery failed

Common delivery errors:
- 'Authentication failed' — wrong SMTP username/password, or app passwords required
- 'Connection refused' — wrong port, firewall blocking outgoing SMTP, or STARTTLS/SSL mismatch
- 'Recipient address rejected' — the To address is invalid or the recipient server blocked it
- 'Relay access denied' — your SMTP server requires authentication for the From address

In Service Center: Factory → Modules → [Module] → scroll to find Pending Emails — emails are queued and sent by OutSystems asynchronously. If a module has pending emails that are not being sent, check the SMTP configuration.

**Expected result:** Service Center → Monitoring → Email shows the sent email with Status = Sent. If there is an error, the error message provides diagnostic information.

## Complete code example

File: `SendEmail_withAttachment.txt`

```outsystems-pseudocode
/* ============================================================
   EMAIL SCREEN: WelcomeEmail (Interface tab → Email)
   Input Parameters: UserName (Text), ActivationLink (Text)
   Content: HTML template with Expression widgets
   ============================================================ */

/* ============================================================
   SERVER ACTION: SendWelcomeEmail
   Input:  UserEmail (Text), UserName (Text), ActivationToken (Text)
   ============================================================ */
Start
  --> Assign:
        BaseURL        = Site.AppBaseURL
        ActivationURL  = BaseURL + "/activate?token=" + ActivationToken
  --> Send_Email:
        From:           Site.SenderEmail
        To:             UserEmail
        Subject:        "Welcome to Our Platform — Please Activate Your Account"
        Email:          WelcomeEmail
          UserName:       UserName
          ActivationLink: ActivationURL
  --> End

Exception Handler (AllExceptions)
  --> LogError:
        ModuleName = "AuthModule"
        Source     = "SendWelcomeEmail"
        Message    = "Email send failed to " + UserEmail + ": " + ExceptionMessage
  --> End  /* Don't block registration if email fails */

/* ============================================================
   SERVER ACTION: SendInvoiceEmail (with attachment)
   Input:  CustomerId (Customer Identifier), InvoiceId (Invoice Identifier)
   ============================================================ */
Start
  --> GetCustomer: Id = CustomerId
  --> GenerateInvoicePDF: InvoiceId = InvoiceId  /* See pdf-generation tutorial */
  --> Assign:
        Attachment.FileContent = GenerateInvoicePDF.PDFContent
        Attachment.FileName    = "Invoice_" + IntegerToText(InvoiceId) + ".pdf"
        Attachment.MimeType    = "application/pdf"
  --> ListAppend(EmailAttachments, Attachment)
  --> Send_Email:
        From:        Site.SenderEmail
        To:          GetCustomer.Customer.Email
        Subject:     "Your Invoice #" + IntegerToText(InvoiceId)
        Email:       InvoiceEmail (screen)
        Attachments: EmailAttachments
  --> End
```

## Common mistakes

- **Calling Send_Email from a Client Action** — undefined Fix: Send_Email is a system Server Action — it must be called from a Server Action (or Data Action). Move email sending logic to a Server Action and call it from the Client Action.
- **Not handling the exception when Send_Email fails, causing the entire transaction to roll back** — undefined Fix: Add an exception handler after Send_Email in the Server Action. For critical operations (user registration, order placement), the email failure should be logged but not abort the main transaction.
- **Using CurrDateTime() in the email subject without formatting, which produces the internal DateTime representation** — undefined Fix: Use FormatDate(CurrDate(), 'dd/MM/yyyy') for readable dates in email subjects and bodies. CurrDateTime() without FormatDate() produces a machine-format string.
- **Hardcoding the From address which bounces in production because the SMTP server requires a verified sender domain** — undefined Fix: Use a Site Property for the From address and ensure the address matches a verified domain in your SMTP provider (SendGrid, Mailgun, etc.). Unverified sender addresses cause SPF/DKIM failures and emails go to spam.

## Best practices

- Store the sender email address as a Site Property (Site.SenderEmail) rather than hard-coding it — this lets you change it per environment without redeploying.
- Wrap Send_Email in an exception handler — a failed email should not roll back a successful user registration or order. Log the error and continue.
- Test your email screen with real email clients (Gmail, Outlook, Apple Mail) before going to production. Rendering differs significantly between clients.
- Use BCC to a monitoring address in production to verify email delivery without modifying recipients.
- For bulk emails (newsletters, batch digests), use a Timer to send in batches rather than calling Send_Email thousands of times in a single Server Action.
- Always include a plain-text alternative in the email (OutSystems email screens support this via the AlternativePlainText property) for clients that don't render HTML.

## Frequently asked questions

### How do I send emails in OutSystems without using the platform SMTP configuration?

Use a REST API integration with an email service provider (SendGrid, Mailgun, Postmark). Create a Consume REST API in Logic tab → Integrations → REST and call the provider's send email endpoint from a Server Action. This bypasses the Service Center SMTP settings entirely and gives you more delivery control, bounce tracking, and analytics.

### Why is my email going to spam even though it sends successfully?

Successful delivery to the recipient's mail server does not guarantee inbox placement. Common spam causes: missing SPF record for your From domain, missing DKIM signature (configure in your SMTP provider), sending from a shared IP with poor reputation, or email content containing spam trigger words. Configure SPF and DKIM for your sender domain in your DNS provider.

### Can I send HTML emails without using an Email screen?

Yes. Send_Email has an HTML body parameter where you can pass raw HTML as a Text variable. This is useful for simple templated emails where building a full Email screen is overhead. For dynamic content, build the HTML string in an Assign node using string concatenation. For complex templates, the Email screen approach is more maintainable.

### How does email sending work differently in ODC compared to O11?

In O11, email is configured once in Service Center (shared SMTP for the entire environment) and uses the built-in Send_Email action. In ODC, there is no built-in SMTP panel — you must either configure an SMTP connector as a Secret Setting or use a Forge component (SendGrid Connector, Mailgun Connector) that calls the email provider's API directly. The ODC approach gives more flexibility but requires more initial setup.

---

Source: https://www.rapidevelopers.com/outsystems-tutorial/outsystems-send-email
© RapidDev — https://www.rapidevelopers.com/outsystems-tutorial/outsystems-send-email