Use a custom server to send Ory Identity 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>
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
- Ory CLI
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.
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.yamlAdd the configuration for your custom SMTP server
config.ymlcourier:
smtp:
connection_uri: smtp://username:password@server:port/
from_address: hello@example.org
from_name: My CompanyUpdate 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.
- Recommended: StartTLS with certificate trust verification. This is the most common option today:
smtp://username:password@server:port/
- StartTLS without certificate trust verification:
smtp://username:password@server:port/?skip_ssl_verify=true
- 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
- Implicit TLS with certificate trust verification:
smtps://username:password@server:port/
- Implicit TLS without certificate trust verification:
smtps://username:password@server:port/?skip_ssl_verify=true
- 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/
Send emails using an HTTP server
Ory Identities supports sending emails using an HTTP server. This is useful if you want to customize the email content or use a service that doesn't provide an SMTP server.
- Ory CLI
- Ory Console (coming soon)
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.yamlAdd the configuration for your custom HTTP server
config.ymlcourier:
delivery_method: http
http:
request_config:
url: https://mail-sender.example.com
method: POST
body: base64://... # See below for the default payload and available variables
headers:
Content-Type: application/json
auth: # leave out, if your server doesn't require authentication, but note that we don't recommend that
type: basic_auth # or api_key
config:
username: my-username
password: my-password
# if you want to use an API key (type: api_key), use the following config instead:
# name: my-api-name
# value: my-api-key-value
# in: header # or cookieUpdate the Ory Identities configuration using the file you worked with:
ory update identity-config {project-id} --file updated_config.yaml
Payload
The payload of the HTTP request is a JSON object that's generated using a Jsonnet template. By default, the following payload is sent:
function(ctx) {
recipient: ctx.Recipient,
template_type: ctx.TemplateType,
to: if "TemplateData" in ctx && "To" in ctx.TemplateData then ctx.TemplateData.To else null,
recovery_code: if "TemplateData" in ctx && "RecoveryCode" in ctx.TemplateData then ctx.TemplateData.RecoveryCode else null,
recovery_url: if "TemplateData" in ctx && "RecoveryURL" in ctx.TemplateData then ctx.TemplateData.RecoveryURL else null,
verification_url: if "TemplateData" in ctx && "VerificationURL" in ctx.TemplateData then ctx.TemplateData.VerificationURL else null,
verification_code: if "TemplateData" in ctx && "VerificationCode" in ctx.TemplateData then ctx.TemplateData.VerificationCode else null,
login_code: if "TemplateData" in ctx && "LoginCode" in ctx.TemplateData then ctx.TemplateData.LoginCode else null,
registration_code: if "TemplateData" in ctx && "RegistrationCode" in ctx.TemplateData then ctx.TemplateData.RegistrationCode else null,
subject: ctx.Subject,
body: ctx.Body
}
The courier passes the Recipient
, TemplateType
, and TemplateData
variables into the Jsonnet template. These variables are
available through the ctx
object. Recipient
will always be the email address of the user. TemplateType
and the fields in
TemplateData
are linked in the following way with each template type containing the fields listed below:
This will produce a JSON object, that contains all data available in the email. You can customize the payload
The Ory Console doesn't support configuring this yet. Please use the Ory CLI instead.
Troubleshooting
In general, if you have problems setting up email delivery, you can view outgoing messages on the Monitoring → Email Delivery page in the Ory Console.
The Sent
state of an email only indicates whether Ory Identities successfully "handed" off the email to the SMTP server.
Emails do not arrive
The best way to figure out, why an email did not arrive is checking the Email Delivery dashboard in the Ory Console. It will show all emails sent by your project, along with its delivery state. If the Ory Network could not reach your SMTP server or there was an authentication failure, it will be indicated here along with the error message.
If the email's status is Sent
, but it did not arrive, please check the spam folder or the logs of your custom SMTP server (if
configured).
Emails are marked as spam
If you're using a custom domain, but no custom SMTP server, some (or all) emails the Ory Network sends, can be marked as spam or blocked by the email providers of your users, such as Gmail. This is due to the phishing/spam protection these providers have in place to protect their users.
To read more, see Automated Emails but in short: we recommend setting up a custom SMTP server, if you use custom domains.