Skip to main content

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

Ory Cloud 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>

Send emails using your SMTP server​

To use your own SMTP server for sending emails, adjust the SMTP configuration key directly in the Ory Identity Service (Kratos) config:

URL with the smtp or smtps scheme:

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

Alternatively, you can configure these values using the Ory CLI:

ory patch project {your-project-id} \
  --replace '/services/identity/config/courier/smtp/connection_uri="smtp://username:password@server:port/"' \
  --replace '/services/identity/config/courier/smtp/from_address="hello@example.org' \
  --replace '/services/identity/config/courier/smtp/from_name="My Company"'
note

You can't customize the from_address and from_name fields without also setting your own email sending server (connection_uri).

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 or you experience errors or bugs, reach out to the Ory team directly:

note

We are working on improving the error observability of RPC calls which will help with debugging this feature. The work is tracked in this GitHub issue.