Receive Emails: Routes

Run Commands

The single entry point for reading and managing a mailbox. Send 1 to 20 commands in one request and get one result per command.

POSThttps://g.sendcorex.com/v1

Every mailbox action (list, read, search, flag, move, send, reply…) is a command sent to this route. The pages below this one document each command and its arguments.

Errors are reported per command. A command that fails does not stop the others, and the HTTP status stays 200.

Body parameters

commandsobject[]required
1 to 20 commands, executed in order.
commands[].commandstringrequired
The command name, for example list_threads.
commands[].argsobjectoptional
The command arguments. Any value can be a $ref to the result of an earlier command.
commands[].idstringoptional
Your own identifier for the result. Defaults to the index ("0", "1"…). Required if you want to use $ref.

Quick start

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1',
  {
    commands: [
      {
        command: "list_folders"
      },
      {
        command: "get_counters"
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_TOKEN } },
);

for (const result of response.data.results) {
  if (result.type !== 'SUCCESS') console.error(result.id, result.code, result.message);
  else console.log(result.id, result.data);
}

Response

{
  "type": "SUCCESS",
  "results": [
    {
      "command": "list_folders",
      "id": "0",
      "type": "SUCCESS",
      "data": {
        "folders": [
          {
            "folder": "INBOX",
            "name": "INBOX",
            "system": true,
            "total": 12,
            "unread": 3
          }
        ]
      }
    },
    {
      "command": "get_counters",
      "id": "1",
      "type": "SUCCESS",
      "data": {
        "total": 12,
        "unread": 3,
        "size_bytes": 482113,
        "folders": {
          "INBOX": {
            "total": 12,
            "unread": 3,
            "size_bytes": 482113
          }
        }
      }
    }
  ]
}

Response fields

type
Always SUCCESS when the request itself was accepted.
results[].command
The command that produced this result.
results[].id
The id you sent, or the index of the command.
results[].type
SUCCESS or ERROR.
results[].data
The command output. Only present when type is SUCCESS.
results[].code
The error code. Only present when type is ERROR.
results[].message
A human-readable error message. Only present when type is ERROR.

Authentication

Every command route needs an access token. The token decides whose mailbox is used: no argument selects another user.

Authorization
Send Authorization: <token> or Authorization: Bearer <token>.
Token format
S.C.G. followed by 100 characters. It identifies the owner (user + sender).
Expiry
Access tokens last 1 hour. When one expires you get TOKEN_EXPIRED: call Refresh Token and repeat the request.

The resolved token is cached for up to 1 hour, so a revoked token can keep working until that cache expires.

Use a previous result with $ref

Any value inside args can be {"$ref": "<id>", "path": "<path>"}. It is replaced by the value found at path in the result of the command with that id. In path, * walks a list and flattens the result. This lets you list and read in a single request.

Request body

{
  "commands": [
    {
      "command": "list_threads",
      "args": {
        "limit": 5
      },
      "id": "a"
    },
    {
      "command": "get_messages",
      "args": {
        "ids": {
          "$ref": "a",
          "path": "threads/*/last_message_uid"
        }
      },
      "id": "b"
    }
  ]
}

$ref
The id of an earlier command in the same request.
path
Slash-separated path into that result. * goes through every item of a list.

Rate limits and cache

Limits apply per IP + user + sender. There is no queue: when you go over, the request is rejected with HTTP 429 and a Retry-After header.

15 requests / second
Peak of 15. Responses served from the cache count too.
15 in flight
At most 15 requests being processed at the same time.
Batch instead of looping
Send up to 20 commands per request instead of one request per action.
Read cache: 1.5 s
The same read (same command and args) within 1.5 seconds returns the same result. It covers list_folders, get_counters, list_threads, list_messages, get_thread, get_messages, search, get_trust and list_trust.
Write de-duplication: 1.5 s
The same write repeated within 1.5 seconds runs only once, so polling that sends the same reply twice does not send two emails.
Cache invalidation
Any write command clears the read cache for that mailbox right away, so the next read sees the new state.

Mail delivered to the mailbox, or changes made in the webmail, show up in reads within 1.5 seconds.

Conventions

These rules are shared by all commands.

System folders
INBOX, Sent, Archive, Trash, Drafts, Spam, Promotions and Snoozed. Aliases like inbox, archived, draft, junk and promotion are accepted. A custom folder is referenced by its slug or by its name.
Pagination
limit goes from 1 to 100 (default 25). The response has has_more and next_cursor: send next_cursor as cursor in the next call.
Batch actions
Action commands accept ids (a list of up to 100) or id (a single one) and answer item by item with items, ok_count and failed_count.
scope
thread applies to the whole conversation in the source folder. message applies only to the given id.

Errors

HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.

400INVALID_JSON
The body is not {"commands":[...]} or has more than 20 commands.
401MISSING_AUTH_HEADER
No Authorization header was sent.
401INVALID_TOKEN
The token is malformed, unknown or revoked.
401TOKEN_EXPIRED
The access token has expired. Call Refresh Token and repeat the request.
429RATE_LIMITED
More than 15 requests/s or 15 in flight for the same IP + mailbox. Wait the number of seconds in Retry-After.
503AUTH_UNAVAILABLE
Authentication is temporarily unavailable. Try again.
CMDUNKNOWN_COMMAND
The command name does not exist.
CMDINVALID_ARGS
A required argument is missing or invalid.
CMDINTERNAL
Server error. The detail is only written to the server log.