1
What does the API want from me?
Question asked by AWRData - 4/16/2024 at 4:03 PM
Unanswered
I am experiencing consternation with the API documentation.  It looks like not all functions or calls are showing me exactly what the call wants.

For instance, ExportUsers.  I send my access token in the header, as required, but it returns:
{"message":"Failed list users for the domain. The domain not found.","success":false}
The reference page for this function does not tell me what else I should be sending.

Also, so far, none of the API reference pages at which I have looked contain practical examples of queries.  Just a "INPUT DATA HERE" or "INPUT VARIABLES HERE" placeholder.

Documentation critiques aside, what am I supposed to send to ExportUsers??

10 Replies

Reply to Thread
0
Zach Sylvester Replied
Employee Post
Hello, 

Thanks for the question. You shouldn't need to pass anything into it. The main requirement is passing in a domain administrator access token.  Or you can use the impersonation API call and then impersonate a domain admin and pass that token in. 

I hope this helps. 

Thanks, 
Zach Sylvester System/Network Administrator SmarterTools Inc. (877) 357-6278 www.smartertools.com
0
AWRData Replied
I still cannot get ExportUsers to answer, but I did get sysadmin/export-users to answer, and it is exactly what I need.  However, its return is prefixed with odd characters, which results in a key name of "domain".  Can you tell me what might be happening there?
0
AWRData Replied
So, like SearchAliases... calling the function is:

api/v1/settings/domain/aliases/{search?}
What is the {search?} placeholder?

Also, is there a list of API functions so I can avoid browsing each API section to find the function I want?
0
AWRData Replied
The "domain" noted above is a a UTF-8 BOM being sent by the API.  I found a few articles discussing the issue, and it looks like I can filter it out using Substring in PowerShell (Invoke-WebRequest).  I do not see this same problem with curl.
0
Jack. Replied
0
Zach Sylvester Replied
Employee Post
Hello, 

I was able to get it to work using this script. 


import requests

def auth(username, password, two_factor_code, url):
    authurl = url + "/api/v1/auth/authenticate-user"
    myobj = {
        'username': username,
        'password': password
    }
    data = requests.post(authurl, json=myobj)
    refreshToken = data.json().get('refreshToken', None)
    accessToken = data.json().get('accessToken', None)
    access_info = {
        'accessToken': accessToken,
        'refreshToken': refreshToken
    }
    return access_info

def post_to_export_users(username, password, two_factor_code, base_url):
    access_info = auth(username, password, two_factor_code, base_url)
    access_token = access_info.get('accessToken')

    if access_token:
        headers = {
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json'
        }
        response = requests.post(base_url + '/api/v1/settings/domain/export-users', headers=headers)
        return response.status_code, response.text
    else:
        return None, {'error': 'Authentication failed, no access token retrieved'}

username = 'user@domain.com'
password = 'password'
two_factor_code = '' # Leave empty if 2FA is not enabled
base_url = 'https://mail.yourdomain.com';

status_code, response = post_to_export_users(username, password, two_factor_code, base_url)
print(f'Status Code: {status_code}')
print('Response:', response)



Let me know if this helps. 

Thanks, 
Zach Sylvester System/Network Administrator SmarterTools Inc. (877) 357-6278 www.smartertools.com
0
Tony Scholz Replied
Employee Post
Hello, 

For the search parameter this is the "Text" string that you are searching for. This is a user level call, this can be found on the second line of the calls description. In my example I am authenticating as a system admin then impersonating the user. 


Example. 

Currently there is no list of all the calls in on a single page. Using the link above breaks the calls down to there areas. 

I hope this helps. 
~Tony
Tony Scholz System/Network Administrator SmarterTools Inc. (877) 357-6278 www.smartertools.com
0
AWRData Replied
@Jack: I am looking for an index.  This interface is what I was describing when I said I have to browse through every section.

@Zach: I was able to get it working in PowerShell, the problem is the UTF-8 encoding.  I am just stripping it with Substring.  Using curl in the Bash, I do not have to do any special manipulations other than managing differing json and csv returns.

@Tony: Is that your PowerShell script, or is there a SmarterMail PS repository somewhere?  I would love to not reinvent the wheel, if at all possible.  Specific to this example, what if I want to extract all of a domain's aliases: what is the search term for that?

Currently there is no list of all the calls in on a single page. Using the link above breaks the calls down to there areas.
I lament the lack of an index, as well as actual practical examples in the documentation.  I do not want to sit for any period of time fuzzing my own server to determine what parameter syntax are needed for the various functions I want to use.

Ultimately, my intention is to extract a full list of all email addresses in use on the server, be they mailboxes, aliases, or mailing lists.  That list will then be used to populate routing tables in border gateways.  For this task, it looks like I need to do the following.

  1. Authenticate a system admin
  2. Enumerate domains
  3. Iterating through domains
    1. Discover domain admin
    2. Impersonate domain admin
    3. Export list of users
    4. Export list of aliases
This does not touch mailing lists, yet (not as important as I use another system for that functionality at this time.)  Is my flow correct?

The comparable process in Exchange would be a Get-Mailbox command, then parsing of the EmailAddresses field of each record.

PS: I also forgot that I will need any throw-away email addresses set up by users, too.
1
Reto Replied
No need to impersonate domain admin if ou are using the system admin. Just call api/v1/settings/domain/account-list-search with the domain name in the X-Smartermaildomain header field.

I don't like the api documentation it's really basic and some stuff like the header is missing. I was once told that there will be a new documention but that is already a long time ago. If I need a function I just use the smartermail gui with the chrome developer tools to see what I need to call, the parameters and the result.
0
echoDreamz Replied
@Reto - Exactly, using the browser dev tools is the only real way to see what is going on with the API...

Reply to Thread