Use a custom SMTP server to send recovery and verification messages to users

The Ory Network comes with SMTP email sending configured out of the box. Ory emails are sent from this address:

{project.name} via Ory <no-reply@courier-eu.mg.oryapis.com>

info

You must send emails using your SMTP server to change the sender address (from_address) and sender name (from_name).

Send emails using your SMTP server

You can send emails from your server. Follow these steps to configure Ory to use a custom SMTP server:

Ory Console

Sign in to the Ory Console and go to Customize → Email Configuration. Toggle the Advanced Settings switch and provide the configuration for your SMTP server.

Ory CLI

1. Download the Ory Identities config from your project and save it to a file:

   ## List all available projects
   ory list projects
   
   ## Get config
   ory get identity-config {project-id} --format yaml > identity-config.yaml

2. Add the configuration for your custom SMTP server

   config.yml

   courier:
     smtp:
       connection_uri: smtp://username:password@server:port/
       from_address: hello@example.org
       from_name: My Company

3. Update the Ory Identities configuration using the file you worked with:

   ory update identity-config {project-id} --file updated_config.yaml

SMTP security mechanisms

SMTP has six different security mechanisms. Most SMTP services today use Explicit StartTLS with trusted certificates.

1. Recommended: StartTLS with certificate trust verification. This is the most common option today:

   smtp://username:password@server:port/
2. StartTLS without certificate trust verification:

   smtp://username:password@server:port/?skip_ssl_verify=true
3. Cleartext SMTP uses no encryption and is not secure. This option is often used in development environments:

   smtp://username:password@server:port/?disable_starttls=true
4. Implicit TLS with certificate trust verification:

   smtps://username:password@server:port/
5. Implicit TLS without certificate trust verification:

   smtps://username:password@server:port/?skip_ssl_verify=true
6. Implicit TLS with certificate verification which works if the server is hosted on a subdomain and uses a non-wildcard domain certificate:

   smtps://username:password@subdomain.my-mailserver.com:1234/?server_name=my-mailserver.com

Integrations

Reference the sample connection URIs to send emails using different providers.

Mailgun

Use the following connection URI to send emails using Mailgun:

smtp://{smtp-user}:{smtp-password}@smtp.mailgun.org:587

# For example:
# smtp://some-user%40mailgun.example.org:df2a2c4e-5caa-4f04-85b9-72d54a2468ad@smtp.eu.mailgun.org:587

AWS SES SMTP

Use the following connection URI to send emails using AWS SES SMTP:

smtp://{smtp-user}:{smtp-password}@email-smtp.{region}.amazonaws.com:587/

# For example:
# smtp://theuser:the-password@email-smtp.eu-central-1.amazonaws.com:587/

Postmark

Use the following connection URI to send emails using Postmark:

smtp://{YOUR_POSTMARK_SEVER_API_TOKEN}:{YOUR_POSTMARK_SEVER_API_TOKEN}@smtp.postmarkapp.com:587/

# For example:
# smtp://thetoken:thetoken@smtp.postmarkapp.com:587/

Troubleshooting

If you have problems setting up email delivery, you can view outgoing messages on the Monitoring → Email Delivery page in the Ory Console