Platform.sh is now Upsun. Click here to learn more
Upsun Fixed User Documentation

Send email from your Upsun Fixed environment using an SMTP proxy

Back to home

On this page

Try Upsun for 15 days
After that, enjoy the same game-changing Upsun features for less with the First Project Incentive!¹ A monthly $19 perk!
Activate your 15-day trial
¹Terms and conditions apply. Only for Flexible Resource projects.

You can configure your Upsun Fixed environments to send emails through an SMTP proxy.

Emails aren’t guaranteed to be deliverable and you can’t white-label them. The SMTP proxy is intended as a zero-configuration, best-effort service.

1. Turn on outgoing email Anchor to this heading

You can turn on outgoing email for each environment. By default, email is turned on for your Production environment and blocked for other environments.

To turn it on for a specific environment, follow these steps:

  1. Select the project.
  2. Select the environment from the Environment menu.
  3. Click Settings.
  4. On the General tab, select the Enable outgoing emails checkbox.

To turn off outgoing email, clear the Enable outgoing emails checkbox.

To turn on outgoing email, run the following command:

platform environment:info --environment ENVIRONMENT_NAME enable_smtp true

To turn off outgoing email, replace true with false.

Changing the setting rebuilds the environment.

Improve deliverability of your email with Sender Policy Framework (SPF). If you don’t have an SPF record, add the following TXT record to your domain’s DNS records:

v=spf1 include:sendgrid.net -all

Having several, conflicting TXT records isn’t supported due to rfc4408 section 3.1.2.

If you already have an SPF record, add SendGrid to your existing record.

3. (Optional) Validate your email Anchor to this heading

You can request DomainKeys Identified Mail (DKIM) validation for your domain.

DKIM improves your delivery rate as an email sender. Learn more about how DKIM works.

To have DKIM enabled for your domain:

  1. Open a support ticket and request the following, replacing SENDER_EMAIL_ADDRESS with the address you send from:

    subject: DKIM record

Hello,

I'd like to request DKIM records to be generated for project PROJECT_ID. Emails are sent from the address SENDER_EMAIL_ADDRESS.

Kind regards

  2. Add the CNAME and TXT records from the support team’s reply to your domain’s DNS configuration.

    The reply looks similar to the following:

    em1._domainkey.yourdomain.com        CNAME   em1.domainkey.u99999999.wl999.sendgrid.net
em12._domainkey.yourdomain.com       CNAME   em12.domainkey.u99999999.wl999.sendgrid.net
em9999.yourdomain.com        CNAME   u99999999.wl999.sendgrid.net

yourdomain.com       TXT     v=spf1 include:em9999.yourdomain.com

    This TXT record replaces the generic one from step 2 — as part of DKIM setup, SendGrid provides a unique SPF record for your domain instead of the generic one.

    Checks for the expected DNS records run every 15 minutes. After SendGrid detects the records, it confirms them automatically — you don’t need to take any further action.

4. Test the email service Anchor to this heading

To test the email service, use the CLI to connect to your app by running platform ssh. Run the following command:

printf "From: SENDER_EMAIL_ADDRESS\nSubject: Test \nThis is a test message" | /usr/sbin/sendmail RECIPIENT_EMAIL_ADDRESS

Replace the variables with actual email addresses as in the following example:

printf "From: someone@example.com\nSubject: Test \nThis is a test message" | /usr/sbin/sendmail someone@example.net

Check the recipient’s inbox, including the spam folder — the test message should arrive within a few minutes.

5. Send email from your app Anchor to this heading

You can use /usr/sbin/sendmail on your app container to send emails as with the example in the previous step. Or use the PLATFORM_SMTP_HOST environment variable in your SMTP configuration.

When outgoing emails are on, PLATFORM_SMTP_HOST is the address of the SMTP host that should be used. When outgoing emails are off, the variable is empty.

When using PLATFORM_SMTP_HOST, send email through port 25 (often the default). Your emails are proxied through the Upsun Fixed SMTP host and encrypted over port 465 before being sent to the outside world.

The precise way to send email depends on the language and framework you use. The following examples show PHP and Java.

To send email in PHP, you can use the built-in mail() function. The PHP runtime is configured to send email automatically with the correct configuration. This works even for libraries such as PHPMailer, which uses the mail() function by default.

The From header is required. Your email isn’t sent if the header is missing.

Beware of potential security problems when using the mail() function. If you use any input from users in the $additional_headers or $additional_params parameters, be sure to sanitize it first.

JavaMail is a Java API used to send and receive email through SMTP, POP3, and IMAP. JavaMail is built into the Jakarta EE platform, but also provides an optional package for use in Java SE.

Jakarta Mail defines a platform-independent and protocol-independent framework to build mail and messaging applications.

The following example sends email using Jakarta Mail:

import sh.platform.config.Config;

import javax.mail.Message;
import javax.mail.MessagingException;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;
import java.util.Properties;
import java.util.logging.Level;
import java.util.logging.Logger;

public class JavaEmailSender {

    private static final Logger LOGGER = Logger.getLogger(JavaEmailSender.class.getName());

    public void send() {
        Config config = new Config();
        String to = "";//change accordingly
        String from = "";//change accordingly
        String host = config.getSmtpHost();
        //or IP address
        //Get the session object
        Properties properties = System.getProperties();
        properties.setProperty("mail.smtp.host", host);
        Session session = Session.getDefaultInstance(properties);

        //compose the message
        try {
            MimeMessage message = new MimeMessage(session);
            message.setFrom(new InternetAddress(from));
            message.addRecipient(Message.RecipientType.TO, new InternetAddress(to));
            message.setSubject("Ping");
            message.setText("Hello, this is example of sending email  ");

            // Send message
            Transport.send(message);
            System.out.println("message sent successfully....");

        } catch (MessagingException exp) {
            exp.printStackTrace();
            LOGGER.log(Level.SEVERE, "there is an error to send an message", exp);
        }
    }
}

Guides on using JavaMail:

Alternative: Use a different email server Anchor to this heading

If you need more options, use your own SMTP server or email delivery service provider. Remember that TCP port 25 is blocked for security reasons. Use port 465 or 587 instead to send email to your own external email server.