Configuring email delivery for authentik

The most common cause is that the SMTP connection never reaches the mail server, so start by confirming the host and port. Check which settings the stage uses. The email authenticator stage can use the global email connection settings or its own SMTP host, port, credentials, TLS or SSL option and timeout, so a stage configured separately can behave differently from the connection you tested globally. Next, confirm that the authentik server and worker containers can resolve the host and open the port. Test from inside the container network, not only from your workstation, because firewalls and security groups often allow a mail relay from one subnet and block the container network. Work through authentik's email troubleshooting guide for the checks that match your version.

A rejected login usually shows up as an authentication error in the server or worker logs, and the mail provider's own logs will confirm it. Check these items in order:

• The username format matches what your relay expects, which is often a full address rather than a short account name.
• The password or API key is current, and it was rotated in every place it is stored, including global settings and any stage-specific override.
• The relay accepts authenticated submission from the source address authentik uses.
• Your provider does not require an app-specific credential or a separate sending permission for this account.

If the credentials are correct but the relay still refuses the session, the problem is usually the relay's allow list or sending policy, which your mail administrator can confirm.

Yes. A TLS mismatch makes the SMTP handshake fail before any message is sent, and the logs typically show a connection or handshake error rather than a rejected recipient. Compare the TLS or SSL option in authentik with what the mail server expects on that port. Implicit TLS and STARTTLS are different modes, and selecting the wrong one causes the handshake to fail even when the host and port are correct. If the mail server uses a certificate from an internal certificate authority, confirm that the CA is trusted by the authentik containers, because an untrusted chain looks like a TLS failure. Change one setting at a time and retest after each change so you can see which change fixed the problem.

A timeout means authentik opened a connection or waited for a response and the mail server did not answer within the configured limit. Common causes include slow or failing DNS lookups for the mail host, egress rules or proxies that hold connections open, and a mail server that is overloaded or unreachable from that network segment. Confirm the path to the server first, then review the timeout value on the stage or in global settings. Raising the timeout without fixing connectivity usually delays the failure rather than removing it, so treat a larger timeout as a last step after the network path is confirmed healthy.

Filtering happens on the receiving side, so authentik may have sent the message successfully while the recipient's provider held or moved it. Start by checking the message headers in the recipient's mailbox and the quarantine or spam logs of the receiving provider. The sender side matters as well. Confirm with your mail administrator that the sending domain publishes SPF and DKIM records that cover the relay authentik uses, that a DMARC policy is in place, and that the From address belongs to a domain your relay is authorized to send for. Reverse DNS for the sending IP and the sending domain's reputation also influence filtering decisions. Test with a few recipients on the major providers your users rely on before you roll out a change.

authentik sends recovery, invitation and code messages to the email address stored on the user record, so a user without that attribute receives nothing, even when the SMTP configuration is correct. Open the affected user in the admin interface and confirm the email field is populated. For users created by a directory sync or an upstream identity provider, check the attribute mapping, because the source may use a different attribute name or may not supply email at all. Test with a user whose address you know is set, which separates a per-user data problem from a delivery problem.

Yes. Background tasks, including sending email, run in the worker container, so a worker that is down, restarting or unable to reach PostgreSQL will leave messages unsent even when the server container is healthy. Check the worker's status and recent logs first, and look for restart loops or database connection errors. PostgreSQL stores all configuration and data except uploaded files, and since the 2025.10 release authentik no longer uses Redis, so the worker depends on PostgreSQL for its queue. Confirm that the worker can reach the database and that its connection count is within what your PostgreSQL setup allows. Once the worker recovers, check that the queued messages are processed.

The cost depends mainly on who performs the diagnosis and how many systems are involved. Internal costs come from the time your identity, network and mail administrators spend on connectivity, relay policy and DNS records, which are often owned by different teams. External costs appear when a mail provider charges for a sending plan or when a partner is engaged on a fixed scope. Ask any partner for a written scope that lists the mail systems, DNS zones and authentik environments included, since that scope drives the quote. Also ask whether the work is a one-time fix or includes ongoing monitoring of delivery, because monitoring is a recurring cost.

The effort is driven mostly by how many flows and stages send email and how many distinct mail paths you need. A single global SMTP connection used for recovery and notifications is a small job. Separate sending identities for invitations, email one-time codes and administrative notices, or stage-level SMTP settings that differ from the global ones, add configuration, testing and review work. Your existing mail relay also matters: an internal relay that already allows the authentik server's address is quicker to validate than a relay that needs new allow-listing, a sending domain, SPF, DKIM or DMARC alignment, or approval from another team. Finally, a security review of where SMTP credentials are stored and who can read them adds time, especially if you keep them in a secrets store rather than in plain configuration.

Yes, if you have someone comfortable with authentik flows and stages and someone who controls the mail relay. The core steps are to set the global email connection, confirm the server can reach the relay on the port and TLS mode the relay expects, attach the email authenticator stage where needed, and test each flow end to end. The parts teams most often underestimate are the mail-side settings: sender domain authentication, relay allow-lists, and whether messages land in spam at the receiving provider. If those owners are reachable and the number of flows is small, an internal team can usually finish this alone. If several flows need separate senders, or the mail team is slow to respond, a fixed-scope engagement can take that coordination off your plate.

Plan for a short list of inputs from each team before any configuration begins. From the mail team, you need the relay hostname, the supported ports, whether the relay requires STARTTLS, implicit TLS or neither, the authentication method, and the sending addresses that are permitted. You also need confirmation of which domain messages will come from and whether SPF, DKIM and DMARC are already published for it. From the identity team, you need the list of flows that send email, the users who will receive recovery or invitation messages, the expected volume, and who approves changes to stored credentials. Written answers to these points usually prevent most of the rework later.

The duration depends on your environment, not on authentik alone. A single relay that already accepts messages from the authentik host and a short list of flows can be configured and tested within a short working session. Timelines grow when the mail team must open a new relay path, when a sending domain has to be verified, or when several stages need their own sender and credentials. Ask any provider to base its timeline on a written list of flows, the relay details and the approvals required, and to state which of those steps it expects you to complete.

A fixed-scope engagement covers the work listed in an agreed statement of scope before it starts. For email, that normally includes reviewing the flows and stages that send messages, configuring the global connection or per-stage connections as agreed, setting TLS and timeout options, testing delivery for each message type, and documenting the settings and the owners of each mail path. It should also state what is excluded, such as changes to your mail provider, DNS records owned by another team, or mailbox troubleshooting at the recipient end. Ask for the deliverables and acceptance tests in writing so both sides know when the work is complete.

The one-time costs are the design, configuration, testing and documentation of the email paths. Recurring costs are the mail relay itself, any sending service your organization already pays for, and the time spent when a password reset or code fails and someone must investigate. The relay cost is usually already part of your mail budget and is not created by authentik. When you request a quote, ask the provider to separate the one-time configuration work from any ongoing support, and to state what changes, such as a new flow or a new sender domain, would be charged as additional scope.

Start with the authentik side, then the relay, then the recipient. On the authentik side, confirm that the email connection is enabled for the flow that sends the message, that the host, port and TLS mode match what the relay expects, and that the server can reach the relay on the network. Check the worker and server logs for SMTP errors, since sending happens through background tasks. On the relay side, confirm the sender address is permitted and that the relay accepts the authentication you configured. On the recipient side, check spam folders and whether the receiving provider rejected the message for authentication failures. The authentik email troubleshooting guide lists the common causes and is the best next read before you open a support request.