Trouble with XML API2 Email::storefilter

[jSeeDev]

I'm developing a PHP script that needs to automatically add an account level filter. The API always throws this error when I call the Email::storefilter function:

<cpanelresult>
<apiversion>2</apiversion>
<error>You must supply a rule name to create a new filter</error>
−
<event>
<result>1</result>
</event>
<func>storefilter</func>
<module>Email</module>
</cpanelresult>

Here is my XML Input:

<cpanelaction>
	<module>Email</module>
	<func>storefilter</func>
	<args>
		<action>save</action>
		<dest>/dev/null</dest>
		<filtername>Rule 1</filtername>
		<match>equals</match>
		<part>$header_to:</part>
		<value>trash@example.com</value>
	</args>
</cpanelaction>

Any idea's would be greatly appreciated.

[cPanelDavidN]

Hi jSeeDev,

You will need to specify which API version you are trying to invoke. In your case, Email::storefilter is an API2 call, so you need to have

<apiversion>2</apiversion>

That said, when I tried to test the call, I too got the error using 'XML mode' input. I will have to investigate why it is not working as expected and re-read the documentation on 'XML mode' input, since I don't immediately see an error with the input parameters (other than what I noted previously). I'll post back with my findings.

If you use 'Fast mode' input, however, the call works just fine. I don't know how you're using the API call, but I would think that it would be easy enough for you to implement 'Fast mode' input in you script. 'Fast mode' is the preferred input method; 'XML Mode' is considered legacy input mode.

// same call as your, but in Fast mode input style
// it's a URL, but I've added line breaks for readability.
https://10.1.1.1:2087/xml-api/cpanel?
cpanel_xmlapi_user=dave&
cpanel_xmlapi_module=Email&
cpanel_xmlapi_func=storefilter&
cpanel_xmlapi_apiversion=2
action=save&
dest=%2Fdev%2Fnull&
filtername=Rule+1&
match=equals&
part=%24header_to%3A&
value=trash%40example.com

Regards,
-DavidN

[jSeeDev]

Thanks for the clear and concise answer, David.

I switched to this FastMode input (again, line breaks for readability):

cpanel_xmlapi_module=Email&
cpanel_xmlapi_func=storefilter&
cpanel_xmlapi_apiversion=2&
action=save&
dest=%2Fdev%2Fnull&
filtername=Rule+1&
match=equals&
part=%24header_to%3A&
val=trash%40example.com

Which does indeed store a new account level filter. However, the values from the 'dest,' 'match,' 'part' and 'val' fields are not stored. The only value that does seem to be stored is the 'filtername'.

[cPanelDavidN]

Okay, reading the documentation, it looks like we've overlooked a requirement of the input parameter keys. Some parameters require an integer following the alpha-name

ApiEmail < ApiDocs/Api2 < TWiki

Since it is possible to have more than one set of conditions, your first set of conditions must have a '1' appended to the parameter names. The second set of conditions with a '2', etc.

Also, I imagine your 'filtername' is for example purposes, but in case it's not: probably need to be changed to something other than 'Rule <number>'. My testing shows that the API call will accept such a name, however in the cPanel UI, that is not permitted (enforced with JS rule). This leads me to believe that the filter may not work as intended if the name is 'Rule <number>'.

So try this:

cpanel_xmlapi_module=Email&
cpanel_xmlapi_func=storefilter&
cpanel_xmlapi_apiversion=2&
action1=save&
dest1=%2Fdev%2Fnull&
filtername=First+Rule&
match1=equals&
part1=%24header_to%3A&
val1=trash%40example.com

Best Regards,
-DavidN

[jSeeDev]

That worked perfectly, David. Yes, 'Rule 1' was for example purposes. As many times as I read over the documentation, seems I would have picked up on that tid-bit. I convinced myself the parameter keys were only required if I wanted more than one condition.

I also noticed the 'match1' field we were filling with the 'equals' value was incorrect as well, and should have been 'is' instead.

Your prompt and clear answers have been extremely helpful. I am thoroughly impressed with your diligence. Thanks again.

Here is the final working FastInput string, for reference:

cpanel_xmlapi_module=Email&
cpanel_xmlapi_func=storefilter&
cpanel_xmlapi_apiversion=2&
action1=save&
dest1=%2Fdev%2Fnull&
filtername=First+Rule&
match1=is&
part1=%24header_to%3A&
val1=trash%40example.com

[cPanelDavidN]

Glad I could help!

Regards,
-DavidN