API documentation

Inumbo is an anti-spam cloud service, that provides integration and white-labelling by giving full access to the system via a REST API. You need an API key; obtained by pressing the button below.

Generate API key

For security and privilege separation reasons, GET calls are allowed using a read-only API key, but POST, PUT and DELETE requires a read-write key. Errors are indicated by a 500 code, and a JSON encoded error string. We use PUT both for creation (because the ID is always known) and for partial updates. The API's base URL is

https://api.inumbo.com/v1/

and you can interact with it using for example cURL, like curl -u api:your-key https://api.inumbo.com/v1/domains to view all your domains. The API supports parameters as URL-encoded GET query strings, and URL- or JSON-encoded POST/PUT bodies.

If you need more advanced APIs or scripting capabilities, consider deploying your own backend email gateways.

Reference

Users

GET /users

Returns a list of users under your account in JSON. User separation is a way for resellers to delegate access and control to customers.

GET /users/<user>

Same as above, but for a single user.

PUT /users/<user>

Create or update a user.

ArgumentNote
emailThe user name and contact information
passwordThe login credentials for the user, leave empty to disable login

You can add the user argument to any other API call, to switch to that user.

Domains

GET /domains

Returns a list of domains under your account in JSON. See examples below.

GET /domains/<domain>

Same as above, but for a single domain.

PUT /domains/<domain>

Create or update a domain. You can do partial updates; only providing one of the arguments.

ArgumentDefaultNote
destinationHostname or IP address, mandantory when creating a domain
destination_port25Destination servers' TCP port
locationusXLocation of domain's mail cluster, cannot be changed once created
address_lookupfileRecipient address lookup method; use smtp to auto-create addresses using SMTP call-out
address_limit10Limit the number of auto-created addresses, in order to provide predicable costs
statusactiveChanging status to disabled will pause email functions and billing

Domain addresses

GET /domains/<domain>/addresses

Returns a list of addresses (recipient table, mailboxes) under the domain in JSON. See examples below.

PUT /domains/<domain>/addresses/<mbox>

Manually add a new address to the recipient table; only specify the local (mailbox) part; such as john.doe.

ArgumentDefaultNote
commentOptional description, in order to keep track of entries
DELETE /domains/<domain>/addresses/<mbox>

Delete an account from the recipient table.

Black/whitelist

GET /lists

Returns a list of all black/whitelist items in JSON. See examples below.

GET /lists/<type>

Same as above, but returns only black or white list items.

PUT /lists/<type>/<item>

Add an item to the black or white (type) list.

ArgumentDefaultNote
commentOptional description, in order to keep track of entries
DELETE /lists/<type>/<item>

Delete an item from the black or white (type) list.

Message tracking

GET /tracking

Returns a list of message items in JSON, with field naming similar to our email gateway's SOAP API. See examples below.

ArgumentDefaultNote
querySubset of the search filter syntax, optional
limit50Number of items to return, like in SQL, optional
offset0Offset to first item, like in SQL, optional

Examples

curl -u api:your-key https://api.inumbo.com/v1/domains

{
    "total_count": 15,
    "items": [
        {
            "domain": "example.com",
            "status": "active",
            "location": "us1",
            "destination": "mail.example.com",
            "addresses": 6,
            "address_lookup": "smtp",
            "address_limit": 100,
            "expired": "no",
            "created": "2014-02-19 15:41:18",
            "mx1": "example.com.us1.protection.inumbo.com",
            "mx2": "example.com.us1.protection.inumbo.net"
        },
        {
            ...

curl -u api:your-key https://api.inumbo.com/v1/domains/example.net -X PUT -d destination=m.example.net

{
    "message": "Added domain"
}

Once the domain is added, you need to verify it by creating a TXT DNS record named inumbo-verification=CODE where the code can be viewed by running

curl -u api:your-key https://api.inumbo.com/v1/domains/example.net

{
    "domain": "example.net",
    "status": "need_verification",
    "verification": "37b83adbc14860e81f8dd9634bebca8110308e25",
    ...

curl -u api:your-key https://api.inumbo.com/v1/domains/example.net -X PUT -d destination_port=26

{
    "message": "Updated domain"
}

curl -u api:your-key https://api.inumbo.com/v1/domains/example.net/addresses/john -X PUT -d comment=JohnDoe

{
    "message": "Added address to domain"
}

curl -u api:your-key https://api.inumbo.com/v1/domains/example.net/addresses/john -X DELETE

{
    "message": "Deleted address from domain"
}

If you run the same command again (trying to delete an already deleted user) you will receive an error.

curl -u api:your-key https://api.inumbo.com/v1/domains/example.net/addresses/john -X DELETE

{
    "error": "Invalid account"
}

curl -u api:your-key https://api.inumbo.com/v1/list/white/support@inumbo.com -X PUT -d comment=Myself

{
    "message": "Added item to white list"
}

curl -u api:your-key https://api.inumbo.com/v1/list

{
    "total_count": 1,
    "items": [
        {
            "data": "support@inumbo.com",
            "type": "white"
            "comment": "Myself"
            "created": "2014-03-05 16:50:05",
        }
	...

To add a user (customer, if you're a reseller) and then execute API calls as that user, run

curl -u api:your-key https://api.inumbo.com/v1/users -X PUT -d email=info@customer.com -d password=badpassword

{
    "message": "Added user"
}

curl -u api:your-key https://api.inumbo.com/v1/users

{
    "total_count": 1,
    "items": [
        {
            "email": "info@customer.com",
            "created": "2014-03-05 16:50:05",
        }
	...

curl -u api:your-key https://api.inumbo.com/v1/domains/customer.com -X PUT -d user=info@customer.com -d destination=m.customer.com

{
    "message": "Added domain"
}

curl -u api:your-key https://api.inumbo.com/v1/domains?user=info@customer.com

{
    "total_count": 1,
    "items": [
        {
            "domain": "customer.com",
            ...

curl -u api:your-key "https://api.inumbo.com/v1/tracking?query=action=REJECT%20to=support@halon.se&limit=1"

{
    "total_count": 1,
    "items": [
        {
            "owner": "support@halon.se",
            "owner_domain": "halon.se",
            "msgts0": "2014-06-11 01:01:18",
            "msgts": "1402455679",
            "msgid": "e3be9efb-f103-11e3-8f26-0050569a261d",
            "msgaction": "REJECT",
            "msglistener": "mailserver:1",
            "msgtransport": "mailtransport:1245",
            "msgsasl": "",
            "msgfromserver": "120.84.228.88",
            "msgfrom": "fegssow@vomni.com",
            "msgfrom_domain": "vomni.com",
            "msgto": "support@halon.se",
            "msgto_domain": "halon.se",
            "msgsubject": "Chinese Garments Factory For Retail...",
            "score_rpd": "50.00000",
            "score_sa": "7.50000",
            "scores": {
                "sa": {
                    "DEAR_SOMETHING": "1.731",
                    "HTML_MESSAGE": "0.001",
                    "MIME_HTML_ONLY": "1.105",
                    "MISSING_MID": "0.14",
                    "RAZOR2_CF_RANGE_51_100": "0.365",
                    "RAZOR2_CF_RANGE_E8_51_100": "2.43",
                    "RAZOR2_CHECK": "1.729"
                },
                "rpd": "str=0001.0A0C0205.5397AA52.00C4,ss=3,sh...",
                "rpdav": null,
                "kav": null,
                "clam": null
            },
            "msgdescription": "Blocked by spam filter, ..."
        }
    ]
}