Shortmail HTTP API

We hope you love using the Shortmail API! Send all feature requests and bug reports to jonathanjulian@shortmail.com.

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:

  1. 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.
  2. 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.

POST /home/api/login

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

Search the archive for matching messages.

Parameters

query
search terms, which will be combined as an AND search. some special queries: 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'