api dox

ttavoy

Hello. Couldn't find documentation for the API (analogous to the "WebFaction API Documentation") ... where is it? Thanks.

klynton

Hey,

You can find our API docs here:

~~https://my.opalstack.com/api/v0/redoc/~~
~~https://my.opalstack.com/api/v0/doc/~~

Edit: as of June 2021 the API is at v1. The new docs are:

https://my.opalstack.com/api/v1/doc/
https://my.opalstack.com/api/v1/redoc/

sean

Just to clarify, what Klynton mentioned are the generated API reference docs.

We'll be publishing an API usage guide with examples soon.

ttavoy

Thank you. Meanwhile, I think there is something quick and easy you could do which could be fantastically helpful: if you could give a python script to do just one thing (for example, to create an email address which delivers to one mailbox and forwards to one address) then probably we could work out how to do everything else from that example.

johns

Here is a python example, In the example you are adding a new 'email address' object.

The parameters are:

source: the email address itself
destinations: the UUIDs of the local mail users that the address delivers to
forwards: email addresses that the address forwards to

from requests.auth import AuthBase
import requests
TOKEN = "TOKENHERE"
class TokenAuth(AuthBase):
    """Attaches HTTP Token Authentication to the given Request object."""
    def __init__(self, token):
        # setup any auth-related data here
        self.token = token

    def __call__(self, r):
        # modify and return the request
        r.headers['Authorization'] = f"Token {self.token}"
        r.headers['Content-Type'] = "application/json"
        return r

r = requests.post(f'https://my.opalstack.com/api/v0/mail/add/', 
                   auth=TokenAuth(TOKEN), 
                   json={
                         "source": "email@address.com", 
                         "destinations": ["UUID1", "UUID2"], 
                         "forwards": ["email@address.com", "email2@address.com"] 
                         })

aa11

johns Here is a python example, In the example you are adding a new 'email address' object.

I'm not able to get this to create new email addresses.

What I've done:

Created script.py
- Add API key
- Add source, forward values (I'm just creating forwards to other addresses, not mailboxes, so I comment out destination. Although including destination also doesn't work.)
chmod +x script.py
python3 script.py
- (Running it with anything other than python3 throws errors).

Result

Console output = Nothing (which usually indicates that it worked... But it didn't)
The email list at https://my.opalstack.com/mail/ remains empty.
I try to force an authentication error by removing the API key, but the output is still nothing.

I assume I'm doing something very dumb.

Ultimately I want to use this to add many forwards at one time. So if I can get this running, I can save Sean from having to do it for me ;-)

So any help (to avoid that) would be appreciated.

Thanks.

cornelius

I think I just found an error in the Docs.

For the endpoint: https://my.opalstack.com/api/v0/dns/add/ The data parameter needs to be an array of objects, not just a single object.

sean

cornelius Nice catch!

You'll probably find that same problem in a few other endpoints. Basically anywhere in the dashboard UI where there is a secondary small "add" button above the save button, the underlying API method will be expecting an array.

cornelius

Here's a script I used for quickly adding google MX and SPF records. (The domain ID is not the domain itself, it's the UUID.)

from requests.auth import AuthBase
import requests
import json

TOKEN = "TOKENHERE"
DOMAIN_ID = "DOMAIN-ID-HERE"
SPF_VALUE = "v=spf1 include:_spf.google.com ~all"

DNS_RECORDS = [
    {
        "domain": DOMAIN_ID,
        "type": "TXT",
        "content": SPF_VALUE,
        "priority": 10,
        "ttl": 3600
    },
    {
        "domain": DOMAIN_ID,
        "type": "MX",
        "content": "ASPMX.L.GOOGLE.COM",
        "priority": 1,
        "ttl": 3600
    },
    {
        "domain": DOMAIN_ID,
        "type": "MX",
        "content": "ALT1.ASPMX.L.GOOGLE.COM",
        "priority": 5,
        "ttl": 3600
    },
    {
        "domain": DOMAIN_ID,
        "type": "MX",
        "content": "ALT2.ASPMX.L.GOOGLE.COM",
        "priority": 5,
        "ttl": 3600
    },
    {
        "domain": DOMAIN_ID,
        "type": "MX",
        "content": "ALT3.ASPMX.L.GOOGLE.COM",
        "priority": 10,
        "ttl": 3600
    },
    {
        "domain": DOMAIN_ID,
        "type": "MX",
        "content": "ALT4.ASPMX.L.GOOGLE.COM",
        "priority": 10,
        "ttl": 3600
    }
]


class TokenAuth(AuthBase):
    """Attaches HTTP Token Authentication to the given Request object."""

    def __init__(self, token):
        # setup any auth-related data here
        self.token = token

    def __call__(self, r):
        # modify and return the request
        r.headers['Authorization'] = f"Token {self.token}"
        r.headers['Content-Type'] = "application/json"
        return r


r = requests.post(f'https://my.opalstack.com/api/v0/dnsrecord/add/',
                  auth=TokenAuth(TOKEN),
                  data=json.dumps(DNS_RECORDS))

aa11

sean I've updated the original example to use json= instead of data= in the API call.

That did it!

I saw cornelius use data=json.dumps() but couldn't get that to work either. Switching from data= to json= did the trick.

Also, having that debugging output (viar.status_code and r.text) is helpful.

Note that all of the addresses must have valid domain names so if you're actually trying to use "MY_DOMAIN.com" that won't work (since underscores aren't allowed in domain names).

Of course. But good thing to mention.

Thanks!!

sean

aa11

If you have no destination mail users then pass that arg as "destinations": [],.

If that does not work then please either post your code here with credentials etc redacted, or send it to support so that we can have a look.

aa11

sean

Sure.

It's basically a copy/paste of what's above and then run through a prettifier to fix any spacing errors introduced by this forum's code formatter.

from requests.auth import AuthBase
import requests

TOKEN = "API_KEY_HERE"

class TokenAuth(AuthBase):
    """Attaches HTTP Token Authentication to the given Request object."""

    def __init__(self, token):
        # setup any auth-related data here
        self.token = token

    def __call__(self, r):
        # modify and return the request
        r.headers["Authorization"] = f"Token {self.token}"
        r.headers["Content-Type"] = "application/json"
        return r


r = requests.post(
    f"https://my.opalstack.com/api/v0/mail/add/",
    auth=TokenAuth(TOKEN),
    data={
        "source": "test@MY_DOMAIN.com",
        "destinations": [],
        "forwards": ["fwd-test-1@MY_DOMAIN.com", "fwd-test-2@MY_DOMAIN.com"],
    },
)

I've tried destination as above, commented out (via #), with literally UUID, and deleted all together.

None of those throw an error.

Thanks.

aa11

sean If you have no destination mail users then pass that arg as "destinations": [],.

Yes. I tried this. Still doesn't work.

sean

aa11 Ok, looking into this.

The lack of an error message is by design - there doesn't seem to be any problem with your code, but if you look at r.status_code and r.text you'll see that there was a server-side error.

aa11

sean but if you look at r.status_code and r.text you'll see that there was a server-side error.

I added the following at the end:

print (r.status_code)
print (r.text)

And then when run, yes, I see a 400:

400
{"detail":"JSON parse error - Expecting value: line 1 column 1 (char 0)"}

sean

aa11 I've updated the original example to use json= instead of data= in the API call.

If you use that example with [] as your destinations and valid addresses in the source and forwards then it should work.

Note that all of the addresses must have valid domain names so if you're actually trying to use "MY_DOMAIN.com" that won't work (since underscores aren't allowed in domain names).

sean

For those of you playing along at home, we've recently pushed an update that changed the various API endpoints for mail users from /mail/user to /mailuser.

The generated API refs will be updated soon.

gelu

Hah! The tool I used to allow my users to change their mailbox passwords after migration from WF was crashing the other day. I tracked down the changes and fixed my code.

The people at Opalstack are really helpful and crazy fast at responding to issues raised both here or through tickets. It would be helpful though if we had some mailing list or RSS feed to keep updated with both changes and new stuff at Opalstack (maybe I don't know about it...). It would a lot of time for both chasing and error introduced by a changes like this and to the good people at Opalstack who answer our questions.

sean

gelu We're not officially publishing changes to the API because the API itself has not been officially released.

Once we've finalized the API and have fully documented everything, then we'll start managing changes publicly.

gelu

sean That's reasonable. What I was suggesting was not necessarily related to the API itself, but rather about building a channel of communication so that we know what's coming and when. This would be for the actual Opalstack users and would preferably lean on the technical side. I can read the blog about new and exiting stuff and I can check the boards for solutions. This channel would serve an entirely different purpose, if it makes sense to you, of course.