Troubleshooting Email Delivery

This topic provides troubleshooting solutions for problems you might encounter using Email Delivery.

TLS errors when integrating with Postfix

  • If you are encountering TLS errors when attempting to integrate Postfix with Email Delivery, ensure that the following setting is removed from the Postfix main.cf file, as it has been deprecated:

    smtp_use_tls = yes
  • Use the following setting instead to turn on TLS:

    smtp_tls_security_level = may

    Using this setting, the Postfix SMTP server announces STARTTLS support to remote SMTP clients, but does not require that clients use TLS encryption.

  • If you want to enforce the use of TLS, so that the Postfix SMTP server announces STARTTLS and accepts no mail without TLS encryption, use the following setting:

    smtp_tls_security_level = encrypt

For more information, see Postfix TLS Support.

Connectivity Issues

Note

Email Delivery does not prohibit connectivity from any source IP range. Any IP that attempts to connect to Email Delivery will be accepted.

Refer to Configure SMTP Connection for a list of regional endpoints to establish SMTP connections for sending.

To troubleshoot a problem connecting to endpoint network ports
  • Ensure that you have the correct endpoint DNS name or IP address for the region and that you have been allowlisted to use the endpoint.
  • Test connectivity to the endpoint using port 25 or 587. Use a utility such as Telnet or netcat to attempt to connect to the port manually.
    1. Open a command prompt.
    2. Use the following command to test the network connection.
      telnet <SMTP endpoint> <port>

      For example:

      telnet smtp.email.us-ashburn-1.oci.oraclecloud.com 25

      The port is open and the test is successful if you see a "Connected to" message. If you are unable to connect to the ports using telnet, you are experiencing a network connectivity issue.

To troubleshoot a problem connecting to an external mail transfer agent (MTA)

Use the following steps to determine whether you are able to communicate with an external service on the required ports 25 or 587. If you are unable to connect successfully, you are experiencing a network connectivity issue. If you are able to connect to an external MTA, the network connectivity issue is within Oracle Cloud Infrastructure.

  • Connect to an external MTA such as Google's mail exchangers.
    1. Open a command prompt.
    2. Use the following command to retrieve one of Google's MX server records.
      dig MX google.com
    3. Use the following command to test connectivity to the endpoint port 25 or 587 against Google's MX servers.
      telnet <IP address> <port>

      If you are unable to connect to Google's MX servers, this confirms that you are having issues connecting to mail servers (port 25 or 587). It is possible that your egress rules are filtering traffic at the VCN.

      If you can connect to an external MTA (that is, you are able to communicate with a public SMTP endpoint on the correct ports) but you cannot connect to Email Delivery public SMTP endpoints on those ports, create a service request with My Oracle Support with this information.

Common Errors Returned by Email Delivery

API Errors

For a complete list of common errors returned by all the services for Oracle Cloud Infrastructure, see API Errors.

Common SMTP Errors Returned by Email Delivery

The following table lists the common errors returned by the Email Delivery SMTP service.

SMTP Status Code Error Code Description
254 4.7.1 Suppression for user <user ocid> to <recpt> Message has been accepted but a status code was returned indicating suppression.

Enhanced Status Code 4.7.1 indicated a persistent transient failure (RFC3463).

421 Timeout waiting for data from client
421 4.4.0 Problem attempting to execute commands. Please try again later
421 Too many connections, try again later
421 Too many auth failures, try again later IP based throttle; triggered by repetitive use of invalid SMTP credentials or non-approved sender.
421 4.3.0 Mail system failure, closing transmission channel
451 Server error An unexpected error has occurred during the SMTP conversation.
451 Error in Processing An unexpected error has occurred during the SMTP conversation.
452 System storage error The server is unable to persist the message in its delivery queue.
455 Maximum messages sent per minute reached : limit is <limit> The SMTP send burst rate (of messages accepted per minute period) has been exceeded.
455 Maximum messages sent per day reached : limit is <limit> The SMTP daily send rate (of messages accepted per 24 hour period) has been exceeded.
501 Invalid command argument, not a valid Base64 string

The base64 encoded AUTH (PLAIN) secret is invalid.

501 Invalid command argument, does not contain NUL The base64 encoded AUTH (PLAIN) secret does not contain NUL field separator(s).
501 Invalid command argument, does not contain the second NUL The base64 encoded AUTH (PLAIN) secret does not contain second NUL field separator(s).
503 Need RCPT command The SMTP client tried to start sending the body of an email message without identifying any email recipients through the required SMTP RCPT command (RFC 5321).
504 Method not supported The client has attempted to use an unsupported AUTH mechanism with our service.
504 AUTH mechanism mismatch The client has sent an invalid AUTH command to our service.
552 Exceeds byte limit The message has exceeded the size limit enforced by the service (see server response to EHLO for size restriction).
535 Authentication credentials invalid Authentication of the SMTP user has failed.
535 Authentication required The client has sent commands that require SMTP authentication succeeded before the service is able to process (that is, commands are being sent out of order).
535 Authorization failed: address <address> not authorized

Authorization of the address (either in the envelope or message) has failed for the SMTP user.

The approved sender does not exist, the use email-family policy does not specify the compartment containing the approved sender, or the user with the SMTP credentials is not in a group with the use email-family policy. See Generate SMTP Credentials for a User for more information.

553 <address> Invalid email address The RFC-822 Internet Address sent by the client is invalid.
554 Message parse error The RFC-2822 Internet Message is invalid (and unable to be parsed by the server).

Message without any headers or header is larger than 256 KB.

Troubleshooting Undelivered Emails

The following issues can cause an email to be undelivered:

  • The recipient is on the Suppression List.
  • An authentication failure or an issue with the format of the email message occurred. For example, if the SMTP "From" address is not the same as the "From" address in the email body, the email is rejected. The addresses must match and be an Approved Sender. Refer to your sending application's logs to review any issues.
  • Use of multiple addresses in the email From header is discouraged. If you use multiple addresses, it increases the possibility that your mail is placed in a spam folder or discarded (because of Domain-based Message Authentication, Reporting, and Conformance (DMARC) From alignment rules). The performance of your emails is reduced because all addresses have to be authorized as approved senders. A best practice for the SMTP envelope From address is to match the header From address when you submit mail to Email Delivery. If you use mismatched addresses, it reduces the performance of your emails because both addresses need to be authorized as approved senders. Certain future platform features will not be available if you use mismatched addresses.
  • Lack of DomainKeys Identified Mail (DKIM).
  • View the "dkimSelector" applied to your mail via the Public Logging feature.

DKIM and DMARC can help authenticate your email to help ensure that your emails get delivered to your recipients' inboxes. For more information, see Additional Options to Increase Deliverability.

Refer to Deliverability Best Practices to learn about recommendations that can help lower your email bounce rate, stay off blocklists, lower your complaint rate, and improve your email sender reputation.

If you are unable to resolve the issue, you can go to My Oracle Support and create a service request. See Open a support service request for more information.

Troubleshooting an Inactive DKIM Key

To activate your DKIM key, you must provision a DNS CNAME record at this location in your Email Domain's DNS:

<selector>._domainkey.<email-domain>

However, different DNS providers have different user interfaces to specify the location of a DNS record. Some user interfaces accept the full DNS path by default and these will work well. Some user interfaces are relative to the zone by default, so if you paste in the entire string without the trailing period, the user interface will provision the wrong location and that will leave your DKIM key in a "Needs Attention" state. Avoid entries like this:

<selector>._domainkey.<email-domain>.<zone-name>

If your Email Domain is the same as your DNS zone name and if your provider only accepts a zone-relative name, use this DNS CNAME location:

<selector>._domainkey

If your Email Domain is in a subdomain of your zone and if your provider only accepts a zone-relative name, use this DNS CNAME location:

<selector>._domainkey.<subdomain>