# Source: https://docs.upsun.com/development/email.md

# Send email

You can configure your Upsun environments to send emails via 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.

**Note**: 

All preview environments are limited to 12,000 email credits per calendar month.

## 1. Turn on outgoing email

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:

To turn on outgoing email, run the following command:

```bash {}
upsun environment:info --environment <ENVIRONMENT_NAME> enable_smtp true
```

To turn off outgoing email, replace ``true`` with ``false``.

Changing the setting rebuilds the environment.

## 2. Recommended: Improve deliverability

Improve deliverability of your email with [Sender Policy Framework (SPF)](https://www.twilio.com/docs/sendgrid/glossary/spf).
If you don't have an SPF record, add the following `TXT` record to your domain's DNS records:

```txt
v=spf1 include:sendgrid.net -all
```

Having several, conflicting `TXT` records isn't supported due to [rfc4408 section 3.1.2](https://datatracker.ietf.org/doc/html/rfc4408#section-3.1.2).

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

## 3. (Optional) Validate your email

You can request for DomainKeys Identified Mail (DKIM) to be enabled on your domain.

DKIM improves your delivery rate as an email sender.
Learn more about [how DKIM works](https://www.twilio.com/docs/sendgrid/glossary/dkim).

To have DKIM enabled for your domain:

1. Open a [support ticket](https://docs.upsun.com/learn/overview/get-support.md) with the domain where you want DKIM.
2. Update your DNS configuration with the `CNAME` and `TXT` records that you get in the ticket.

Checks for the expected DNS records run every 15 minutes before validation.

The `TXT` record looks similar to the following:

```txt
v=spf1 include:u17504801.wl.sendgrid.net -all
```

## 4. Test the email service

To test the email service, use the [CLI](https://docs.upsun.com../administration/cli.md) to connect to your app by running `upsun ssh`.
Run the following command:

```bash
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:

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

In a little while, the test message should arrive at the recipient address.

**Note**: 

When sending emails from your project, **use a mail address that is on the same domain as your project** otherwise it will be flagged as spoofing attempt and not be sent.

Also, **make sure to test with real email addresses**. If you send emails to fake domains (such as ``example.com``), they fail and hurt your sending reputation. Make sure your test emails are deliverable.

## 5. Send email from your app

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 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.
See some examples for given languages.

JavaMail is a Java API used to send and receive email via SMTP, POP3, and IMAP.
JavaMail is built into the [Jakarta EE](https://jakarta.ee/) platform, but also provides an optional package for use in Java SE.
[Jakarta Mail](https://projects.eclipse.org/projects/ee4j.mail) defines a platform-independent and protocol-independent framework to build mail and messaging applications.
The following example sends email using Jakarta Mail:

```java {}
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:

 - [Send email with HTML formatting and attachments](https://mkyong.com/java/java-how-to-send-email/)
 - [JavaMail API](https://javaee.github.io/javamail/)

## Alternative: Use a different email server

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