Email Registration and Password Reset
Setting passwords by hand for every account does not scale and is not secure. DreamFactory can instead email an invitation and let the person set their own password. The same wiring drives password reset emails.
Neither feature works on a fresh install. Both need an email service and an email template selected. Configuring the service alone is not enough.
What you need
Three things, in order:
- A mail transport DreamFactory can reach.
- An Email service in DreamFactory that uses it.
- That service and a template selected on the account type you care about.
Step 1: Choose a mail transport
The recommended path is a dedicated SMTP service. It stores its own host,
port, credentials, and encryption, so nothing goes in .env. See
SMTP for the fields.
A Local Email Service is also available. When its Local Command field is
empty and MAIL_DRIVER is smtp, it falls back to the Laravel mail settings in
your .env file. MAIL_DRIVER defaults to sendmail, so it must be set
explicitly:
MAIL_DRIVER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=YOUR_PASSWORD
SMTP is one of several delivery options. Mailgun and other providers are available as their own service types. See Email Services Overview.
Step 2: Create the Email service
In the admin console, go to API Generation & Connections > API Types > Utility. Email service types are filed under Utility, alongside Cache, Notification, Log, Source Control and IoT. There is no separate Email entry in the API Types list, which is a common place to get stuck.
Create the service and note its ID; you need it in the next step.
Step 3: Select the service and template
This is the step most installs miss. The settings live on the service that owns the account being invited or reset, and there is no global default.
| Account type | Where the settings live | Fields |
|---|---|---|
| Non-admin users | The user service, Config tab | invite_email_service_id, invite_email_template_id, password_email_service_id, password_email_template_id |
| Admins | The system service, Config tab | The same four fields |
The two are independent. Configuring user invites does not configure admin invites, and configuring invites does not configure password resets.
In the admin console, open the user service and set these on its Config tab:
- Invite Email Service and Invite Email Template
- Password Email Service and Password Email Template
- Open Reg Email Service and Open Reg Email Template, if you allow self-registration
The installer seeds three templates: User Invite Default,
User Registration Default, and Password Reset Default. They are not applied
automatically. You must select one.
By API:
curl -X PATCH "https://<url>/api/v2/system/service/<user_service_id>" \
-H "Content-Type: application/json" \
-H "X-DreamFactory-Session-Token: <sessionToken>" \
-d '{"config":{"invite_email_service_id":12,"invite_email_template_id":1,"password_email_service_id":12,"password_email_template_id":3}}'
Admin accounts use the same request against the system service instead of the
user service. Look up its ID with
GET /api/v2/system/service?filter=type='system'.
Sending an invitation
Create the user with send_invite=true and omit the password. The invited
person sets their own.
curl -X POST "https://<url>/api/v2/system/user?send_invite=true" \
-H "Content-Type: application/json" \
-H "X-DreamFactory-Session-Token: <sessionToken>" \
-d '{"resource":[{"name":"Jane Doe","first_name":"Jane","last_name":"Doe","email":"jane@example.com"}]}'
In the admin console, the account form offers Send Email Invite or Set Password as a pair. Choose Send Email Invite.
See User Management for the full request format.
Password reset
Once the password reset service and template are set, the reset endpoint sends the email:
curl -X POST "https://<url>/api/v2/user/password?reset=true" \
-H "Content-Type: application/json" \
-d '{"email":"jane@example.com"}'
A configured instance returns {"success": true}.
Admin accounts use a different endpoint, and unlike the user endpoint it requires a session token or API key:
curl -X POST "https://<url>/api/v2/system/admin/password?reset=true" \
-H "Content-Type: application/json" \
-H "X-DreamFactory-Session-Token: <sessionToken>" \
-d '{"email":"admin@example.com"}'
That endpoint reads the system service settings, not the user service ones.
Troubleshooting
Both features fail loudly with HTTP 500 rather than failing silently. The message tells you which of the two settings is missing.
| Message | Cause |
|---|---|
No email service configured for user invite. | Invite Email Service is not set |
No default email template for user invite. | Invite Email Template is not set |
No security question found or email confirmation available for this user. Please contact your administrator. | Password Email Service is not set, and the user has no security question |
No data found in default email template for password reset. | Password Email Template is not set |
If the settings look right but mail still does not arrive, the problem is the transport, not DreamFactory. Send a message directly through the Email service itself to confirm it can reach your mail host before looking further.
Fixing this for users and finding that admins still cannot reset is expected.
Set the same four fields on the system service as well.
Next Steps
- SMTP: Configure an SMTP email service
- Email Services Overview: Compare providers and delivery options
- User Management: Create, update, and delete users through the API