Creating a staged user with an API call

I already found out, that the correct endpoint is /admin/email/handle_mail (not “handle_email”), but still can’t figure out, what should be in the API request.

1 Like

The only parameter this endpoint takes is a valid email message:

curl -i -sS -X POST "http://localhost:3000/admin/email/handle_mail" \
-H "Api-Key: 852b2d8556777aeb62346e0d8b36ed248a89b03f0261165a685c0aae9c8c2fdd" \
-H "Api-Username: system" \
-F "email=Date: Mon, 24 Feb 2020 13:13:34 -0700
Subject: test email5

This is a sample email message.

You will need to make sure you enable email_in correctly setup your category or group to receive these emails:

Yes, I believe so.

Yes, the topic will be created on behalf of the user.


Thank you, Blake. However, it still doesn’t work for me. I got a response from API “email has been received and is queued for processing”, but nothing appears in Discourse - neither a new topic, nor a staged user.

Here’s the review of the settings:

  • email_in: on
  • email_in_min_trust: 0
  • enable_staged_users: on


  • Custom incoming email address: set as [my_name]
  • Accept emails from anonymous users with no accounts: on

API call:
curl -i -sS -X POST "[my_domain]/admin/email/handle_mail" -H "Content-Type: multipart/form-data;" -H "Api-Key: [...]" -H "Api-Username: system" -F "email=Date: Mon, 24 Feb 2020 13:13:34 -0700 From: [some_name] To: [my_name] Subject: test API email post This is a sample email message."

What could be wrong?

Is your sidekiq running properly?

How can I check that?

You can check if sidekiq is running by browsing to /sidekiq, but I think there is likely an issue with the raw email now that the api request is succeeding. There are several tabs in the admin dashboard you can check for email errors.

  • /admin/email/sent
  • /admin/email/skipped
  • /admin/email/bounced
  • /admin/email/received
  • /admin/email/rejected

See if you can find the emails you are creating via api calls under one of those tabs and you might be able do see an error message associated with it.

1 Like

Yes, sidekiq is running. I checked the /admin/email tabs - looks like my “emails” are actually rejected.
This is what I get:

I inserted the same email text in the “Advanced text” tab, and it seems to be working, if each part (Date, From, To, Subject) starts with a new line, and the body is separated by two line breaks. When inserting the text exactly like in curl, it returns nothing. Could it be the line breaks in the raw email? If yes, what should I do?

I tried, /n, %0A and $'[text/n]', neither works.

I’m not sure. Looks like it doesn’t like any of the fields in your email.

I used ruby to generate the curl command and ruby to read my email text file I wrote, but yes it appears to be a newline issue.

Can you have curl read an email file that has actual newlines in it?

curl -X POST -i -F parametername=@filename host:port/xxx


You were right - that was a newline issue. I tried the same API call from Postman, and it worked - a new staged user was created and a topic on his behalf.

But: no email was sent to this user’s address! I also posted a comment in the topic - no email notification either. Is there a setting that prevents this? I tried to find one, but I couldn’t.

UPD: There was a indeed a setting that prevented sending post notifications :slight_smile: so now I have two different questions:

  1. Why there wasn’t an email informing the staged user that the topic was created and sending him the link to it?
    (I would also add some instructions about how to log in to the forum if I knew, which template to edit.)
  2. Why there’s no link to the topic in the post notification emails? Also no unsubscribe link.
    The template seems to be the same - “user_posted”.

Which setting for anyone following along? I don’t think I had to change anything, so just curious.

I think this is by design and the same happens if you send an email to a Discourse group. It is designed to work just like email as in the user might not even know they are sending an email into a Discourse forum. If I send you a regular email to your email account I don’t get a reply back from your email provider that says you received my email, we just trust that it works.

Here is an example email notification a staged user will receive:


but this is what a non-staged user will receive:

There appears to be a difference between staged users and non-staged users. Likely because the user is staged it is to be just like interacting via regular email.


There actually were several.

  • default email level - default is “only when away”
  • email time window - default is 10 minutes, so the notification email is not sent immediately
  • disable emails - default is “no”, but I had it changed before and forgot about it :man_facepalming:

Well, for me the post notification doesn’t really look like a regular email anyway - e.g. it has a link to the post author’s profile at the forum (twice!), but not to the topic.

Besides, I would like to inform the staged user, that he can actually sign in to the forum.
Is there a way to customize this email template?

By design there are several fields that are omitted for staged users in email templates (like the respond instructions):

I’m not entirely sure of the reasoning, jut stating that in code this is how it is, so you are currently fighting an up hill battle here because you are attempting to do something discourse is designed not to do.

Yes, you can edit the email templates, but you are pretty limited in what you can customize. Like I don’t think you can customize the email template to look one way for staged users and another way for non-staged users, but you can add a message with a link to the bottom of the notification email inviting them to visit your site instead of just interacting via email.

1 Like

Actually, it would be enought if the template looks the same way for regular and staged users :slight_smile:
I’ll think, what I could do. Thank you for the detailed explanation!


One last question (hopefully): how can a staged user unsubscribe from receiving new posts to the topic created on his behalf?

I don’t think they can. They would have to register and update their preferences on that topic or their overall notification preferences.


Are there some docs about this endpoint? I have searched API docs but it is not there.

I am looking for a way how to create topic and assign it to a specific user (by discourse-assign plugin).

And also thinking if API key have to by for user system or I can use some other user with minimal permissions (what are that minimal required?).

Just this post: Creating a staged user with an API call

This is totally doable. Have a look at How to reverse engineer the Discourse API and you will see which endpoint the discourse-assign plugin calls.

Nope does not need to be with the system user. You just need a user with enough trust level to create and assign topics.

Thank you for reply. I understand how to assign specific post, but how to reliably find post just created by the /admin/email/handle_mail endpoint? It also seems to queue received calls, so I will not always find it immediately after the first call.

Correct, that endpoint does not return a topic_id.

Do they HAVE to be staged users? Couldn’t you just create the user via the api and then create a topic? Or are people that don’t have accounts yet going to be emailing that endpoint?

It is for public contact form on different products where each have different merchant. I want to assign topic to the specific merchant and also deny access to topics what does not belong to that merchant.