Shortmail HTTP API

API Endpoints

Request api_key

User information

Inbox status

Inbox messages

Inbox changes feed

Send a Shortmail

Reply to a Shortmail, update attributes

Mark a single message as read, update attributes

Search the archive

All API endpoints use standard REST-style HTTP requests and methods. Tell the API what format you would like by passing an Accept: header. We support application/json as well as application/xml. If Accept: is not passed, or if it is set to */*, json is returned. Examples here use curl and application/json. You are encouraged to set a custom USER_AGENT string when interacting with the api; this will allow us to better diagnose usage and help you with any issues.

Authentication

All requests need to be authenticated. There are two ways to authenticate:

API KEY - make one initial request for the user's api_key, and then store it. With every subsequent request, pass the key in the HTTP header Shortmail-Api-Key. There is no need to ever re-request another key for that user.
Basic Auth - if the account being accessed has a password (shortmail.com accounts only have a password if the user signs into shortmail and sets one), then any request can be authenticated using HTTP Basic Auth. There is no need for an API KEY.

We recommend using the API KEY approach, since a client app can be built to handle any number of users simply by storing each's api_key. This allows for an app to service multiple users at a time, and never require the user to re-authenticate (no more password prompts!). The Basic Auth approach might be simpler if you are building a tool that only one Shortmail user will use at time, such as a utility that will download a single user's Shortmail to their computer. The drawback is that the user is required to have a password set.

Sign in to Shortmail, getting an api_key to access the rest of the API on behalf of this user. Pass credentials as either Shortmail email and password, or Shortmail email and Twitter access token/secret. Store the api_key for use between sessions - authenticating more than once per email address is not necessary, and is not suggested.

Parameters

For accounts connected to Twitter:

email: A shortmail.com email address
twitter_access_token: Twitter OAuth access token
twitter_access_secret: Twitter OAuth access token secret

For accounts with a password:

email: A shortmail email address
password: account password as set in the user's settings

Accounts with a password can also request a key using Basic Auth.

Returns

200 success, 401 or 422 if authentication fails

Example

# pass creds as params
curl -d 'email=jonathanjulian@shortmail.com&password=mypassword' -H "Accept: application/json" http://api.shortmail.com/home/api/login

# pass creds in Basic Auth
curl -X POST -u jonathanjulian@shortmail.com:mypassword -H "Accept: application/json" http://api.shortmail.com/home/api/login

{
  "address": {
    "name": "Jonathan Julian",
    "avatar_url": "http://a2.twimg.com/profile_images/1410547810/c1975-500_normal.png",
    "id": 1,
    "email": "jonathanjulian@shortmail.com"
    },
  "api_key": "JONATHAN'S API KEY"
}

User

GET /home/api/user

Returns information for the current user

Parameters

none

Returns

200 success

Example

# pass api_key in the HTTP header
curl -H "Shortmail-Api-Key: USER API KEY" -H "Accept: application/json" http://api.shortmail.com/home/api/user

# pass creds in Basic Auth
curl -u jonathanjulian@shortmail.com:mypassword -H "Accept: application/json" http://api.shortmail.com/home/api/user

{
  "id": 1234,
  "contact_email_address": {
    "email": "jonathanjulian@example.com",
    "name": "Jonathan Julian",
    "full": "\"Jonathan Julian\" <jonathanjulian@example.com>"
  },
  "accounts": [{
    "name": "Jonathan Julian",
    "unseen_inbox_count": 5,
    "total_inbox_count": 23,
    "id": "jonathanjulian@shortmail.com",
    "email_address": "jonathanjulian@shortmail.com",
    },{
    "name": "Jonathan Julian",
    "unseen_inbox_count": 0,
    "total_inbox_count": 11,
    "id": "jonathanjulian@shortmail.me",
    "email_address": "jonathanjulian@shortmail.me"
  }],
  "evernote": {
    "id": 4567,
    "shard_id": "s7",
    "username": "jonathanjulian"
  },
  "connected_to": [{
    "id": 984
    "enabled": true
    "local_email": "jonathanjulian@shortmail.com",
    "remote_email": "jonathanjulian@example.com",
    "move_messages": true,
    "only_contacts": false
  }]

}

Status

GET /home/api/accounts

Returns an array of accounts with inbox counts and unread counts

Parameters

none

Returns

200 success

Example

# pass api_key in the HTTP header
curl -H "Shortmail-Api-Key: USER API KEY" -H "Accept: application/json" http://api.shortmail.com/home/api/accounts

# pass creds in Basic Auth
curl -u jonathanjulian@shortmail.com:mypassword -H "Accept: application/json" http://api.shortmail.com/home/api/accounts

[
  {
    "name": "Jonathan Julian",
    "unseen_inbox_count": 5,
    "total_inbox_count": 23,
    "id": "jonathanjulian@shortmail.com",
    "email_address": "jonathanjulian@shortmail.com"
  },{
    "name": "Jonathan Julian",
    "unseen_inbox_count": 0,
    "total_inbox_count": 11,
    "id": "jonathanjulian@shortmail.me",
    "email_address": "jonathanjulian@shortmail.me"
  }
]

Messages

GET /home/api/conversations

Get the contents of the inbox for a given account. The posts array contains each message in the conversation, along with the details about the sender. The addresses array contains all the participants in the conversation, including yourself.

Parameters

aid: The Shortmail email address to check

Returns

200 success

Example

# pass api_key in the HTTP header
curl -H "Shortmail-Api-Key: USER API KEY" -H "Accept: application/json" http://api.shortmail.com/home/api/conversations?aid=jonathanjulian@shortmail.com

# pass creds in Basic Auth
curl -u jonathanjulian@shortmail.com:mypassword -H "Accept: application/json" http://api.shortmail.com/home/api/conversations?aid=jonathanjulian@shortmail.com

[
  {
    "id": 164996,
    "subject": "test message zebra",
    "is_public": false,
    "is_open": false,
    "public_url": null,
    "is_silenced": false,
    "addresses": [{
      "id": 3028982,
      "email": "jonathanjulian@shortmail.com",
      "name": "Jonathan Julian",
      "avatar_url": "http://www.gravatar.com/avatar/fc661b3e9c498fe417a8b20c7a35c704.png?d=mm&s=64",
      "profile_url": "http://shortmail.com/jonathanjulian",
      "new": false,
      "internal": true
    }],
    "posts": [{
      "text": "<p>test message zebra</p>",
      "plain_text": "test message zebra",
      "id": 134652,
      "share_id": 325307,
      "conversation_id": 164996,
      "flags": null,
      "posted_at": "2011-11-10 17:07:11.663164"
      "human_posted_at": "Nov 10 at 05:07 PM",
      "updated_at": "2011-11-10 17:07:12.017098",
      "seen_at": "2011-11-10 17:07:12.015383",
      "message_updated_at": "2011-11-10 17:07:12.017098",
      "archived_at": "2011-11-10 17:07:12.015301",
      "short_links": {},
      "sender": {
        "id": 3028982,
        "email": "jonathanjulian@shortmail.com",
        "name": "Jonathan Julian",
        "avatar_url": "http://www.gravatar.com/avatar/fc661b3e9c498fe417a8b20c7a35c704.png?d=mm&s=64",
        "profile_url": "http://shortmail.com/jonathanjulian",
        "internal": true
      }
    }]
  }
]

GET /home/api/conversations/changes

Get changes to your inbox since a certain time, in the same format as the inbox query. If the client keeps track of the last time the server was queried, then this call can quickly return only changes. NOTE: "changes" includes message removal and participant additions. Consider this a "diff" between your stored view and the server. Removed conversations are returned here with an empty posts array.

Parameters

since: YYYY-MM-DD HH:MM:SS

Returns

200 success. An empty array means no changes.

Example

# pass api_key in the HTTP header
curl -H "Shortmail-Api-Key: USER API KEY" -H "Accept: application/json" http://api.shortmail.com/home/api/conversations/changes?aid=jonathanjulian@shortmail.com&since=2012-02-21+12:34:55

# pass creds in Basic Auth
curl -u jonathanjulian@shortmail.com:mypassword -H "Accept: application/json" http://api.shortmail.com/home/api/conversations/changes?aid=jonathanjulian@shortmail.com&since=2012-02-21+12:34:55

[]

Sending a Shortmail

POST /home/api/conversations

Send a Shortmail.

Parameters

aid: the email account to send as
recipients: comma-separated list of email addresses to deliver the message to
subject: subject of the message
text: the body of the message. limit of 500 characters!
visibility: private, public, open (defaults to private)

Returns

200 success, with the message, in the format above

422 if sending the message fails, along with errors

Example

curl -H "Shortmail-Api-Key: USER API KEY" -H "Accept: application/json" -d 'aid=jonathanjulian@shortmail.com&subject=The Shortmail API=Welcome to the API!&recipients=you@example.com' 'http://api.shortmail.com/home/api/conversations'

Example error message

{ 
  "errors": {
    "text": [
      "should be short - keep messages less than 500 chars please"
    ]
  }
}

PUT /home/api/conversations/:id

Send a reply to a message, or set attributes on a conversation. Pass any combination of params.

Parameters

aid: the email account to send as
reply: the text of the reply to this conversation
archive: pass true to archive this conversation, false to move this conversation to the inbox
seen: pass anything to mark this conversation as "seen"
silence: pass anything to "silence" this conversation - all subsequent incoming messages will be auto-archived
unsilence: pass anything to "unsilence" this conversation
mark_as_deleted: pass anything to "delete" this conversation. See last_posted_at
report_abuse: pass anything to report this conversation to administrators as abuse or spam. See last_posted_at
last_posted_at: In conjunction with report_abuse or mark_as_deleted, pass the date of the latest post in the conversation

Returns

200 success, with the message, in the format above

If the conversation was deleted, 200 success with just the conversation id

422 if sending the message or anything else fails, along with errors

Example

Reply to a conversation, also archiving it:

curl -X PUT -H "Shortmail-Api-Key: USER API KEY" -H "Accept: application/json" -d 'aid=jonathanjulian@shortmail.com&reply=I love it!&archive=true' 'http://api.shortmail.com/home/api/conversations/165061'

(returns the same message array as above)

Deleting a conversation:

curl -X PUT -H "Shortmail-Api-Key: USER API KEY" -H "Accept: application/json" -d 'mark_as_deleted=1&last_posted_at=2012-02-24+13:26:44' 'http://api.shortmail.com/home/api/conversations/165061'

{
  "id" :165061,
  "posts": []
}

PUT /home/api/conversations/:conversation_id/posts/:id

Mark a message as seen or unseen.

Parameters

aid: the email account that read the message
seen: pass 'true' to mark this message as "seen", "false" to mark as unseen

Returns

200 success, with no body

422 if anything fails, along with errors

Example

Mark a single message as seen:

curl -X PUT -H "Shortmail-Api-Key: USER API KEY" -H "Accept: application/json" -d 'aid=jonathanjulian@shortmail.com&seen=true' 'http://api.shortmail.com/home/api/conversations/165061/posts/232766'

Search

GET /home/api/conversations/search

Search the archive for matching messages.

Parameters

query

search terms, which will be combined as an AND search. some special queries:

from:(sender name)
people:(person name)
subject:(text of subject)
text:(text of message)

omitting this parameter will return all messages

per_page

maximum rows to return (default 75)

page

page number (1-based)

Returns

200 success, with the matching messages in the format above

Example

curl -H "Shortmail-Api-Key: USER API KEY" -H "Accept: application/json" 'http://api.shortmail.com/home/api/conversations/search?query=cats&per_page=25'

Shortmail HTTP API

API Endpoints

Authentication

POST /home/api/login

Parameters

Returns

Example

User

GET /home/api/user

Parameters

Returns

Example

Status

GET /home/api/accounts

Parameters

Returns

Example

Messages

GET /home/api/conversations

Parameters

Returns

Example

GET /home/api/conversations/changes

Parameters

Returns

Example

Sending a Shortmail

POST /home/api/conversations

Parameters

Returns

Example

PUT /home/api/conversations/:id

Parameters

Returns

Example

PUT /home/api/conversations/:conversation_id/posts/:id

Parameters

Returns

Example

Search

GET /home/api/conversations/search

Parameters

Returns

Example