Skip to main content

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>

Send emails using your SMTP server​

To use your own SMTP server for sending emails, adjust the SMTP configuration key directly in the Ory Identities (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.