Developers

Parsing Email Messages

Obindo transforms every inbound email message into a JSON object so that you can work with it. Obindo then goes a step further and parses out key data from each message, extracting data about contacts, files, events, threads, and tags.

The JSON object is available in the script as a global variable message. Here's what a very simple email looks like: 
{
   "from":{"emailAddress":"ron@blainetravel.com","name":"Ron Albertson"},
   "to":[{"emailAddress":"travelquestions@obindo.com"}],
   "cc":[{"emailAddress":"sheila@blainetravel.com","name":"Sheila Albertson"}],
   "inbox":"travelquestions@obindo.com",
   "subject":"Testing this out",
   "text":"This is my text.",
   "fullText":"This is my text.",
   "html":"<div dir=\"ltr\">This is my text.</div>",
   "sentDate":1399143052000,
   "sentDateText":"Sat, 3 May 2014 13:50:47 -0500",
   "sentDateOffset":-500,
   "isReply":false,
   "isForward":false
}
With this email, we could write a simple script: 
var from= message.from.emailAddress;

//forward me the email
sendEmail('ron@blainetravel.com', message.subject, from + ' wrote: ' + message.text);

//send them an email
sendEmail(from, 'Thanks!', 'We will get back to you soon!');
  • Each address comes in an object with name and emailAddress. from is just one address, but to and cc are arrays. The obindo email address is returned in inbox.
  • text differs from fullText when the email contains previous emails (see messages).
  • sentDate, like other dates, returns the milliseconds since January 1, 1970. In Javascript, you can use this to create a date object: var dt= new Date(message.sentDate);
  • sentDateOffset is the timezone offset from GMT time of where the email was sent, gathered from the email's Date header (message.sentDateText). -500 means the email is -5 hours from GMT time.

In addition to parsing basic properties of an email, Obindo also extracts higher-order information from each message as well.
{
   "files",
   "messages",
   "events",
   "dates",
   "contacts",
   "names",
   "tags"
}

message.files

The details of any files attached or embedded to the email. 
"files": [ {  
   "name":"image.png",
   "contentLength":21644,
   "contentType":"image/png",
   "embedId":"ii_145c3bfd786dde61"
},
{  
   "name":"007.JPG",
   "contentLength":703653,
   "contentType":"image/jpeg"
} ]
  • contentLength returns the byte size of the file. You may have to check this if the site you are connecting to has a file size limit.
  • embedId is only set if the file is embedded. The position of the embedded file can be found in message.html, for example:
    "html":"<img src=\"cid:ii_145c3bfd786dde61\" alt=\"Inline image 1\" width=\"273\" height=\"156\">".

message.messages

If your original email is:
How about 3pm?

On Sat, May 3, 2014 at 4:01 PM, Ron Albertson <ron@blainetravel.com> wrote:
What time would you like to meet?
The message object will separate out the texts of the two emails: 
{
   //other message properties
   "text":"How about 3pm?"
   "fullText":"How about 3pm?\r\n\r\nOn Sat, May 3, 2014 at 4:01 PM, Ron Albertson 
<ron@blainetravel.com> wrote:\r\nWhat time would you like to meet?"
   "messages": [ {
          "sentDate":1399132860000,
          "sentDateText":"Sat, May 3, 2014 at 4:01 PM",
          "from":{"emailAddress":"ron@blainetravel.com","name":"Ron Albertson"},
          "text":"What time would you like to meet?"
       } ]
}

message.events

Properties the dates mentioned in the text. Combines any duplicate dates found and aggregates the properties, and adds additional friendly properties. (Use dates if you need more textual details). 
"events":[{
   "start":1399316400000,
   "startDate":"2014-05-05",
   "startTime":"2:00pm",
   "end":1399320000000,
   "endTime":"3:00pm",
   "title":"Coffee",
   "friendlyDate":"May 5, 2014 from 2:00pm to 3:00pm",
   "friendlyFullText":"Coffee on May 5, 2014 from 2:00pm to 3:00pm"
},
{
   "start":1401771600000,
   "startDate":"2014-06-03",
   "end":1402030800000,
   "endDate":"2014-06-6",
   "title":"Conference",
   "friendlyFullText":"Conference from June 3, 2014 to June 6, 2014",
   "friendlyDate":"June 3, 2014 to June 6, 2014",
},
{
   "start":1399908600000,
   "startTime":"10:30am",
   "startDate":"2014-05-12",
   "title":"Meet-up",
   "friendlyFullText":"Meet-up on May 12, 2014 at 10:30am",
   "friendlyDate":"May 12, 2014 at 10:30am"
} ]
  • start and startDate will always be set. The rest are only set if mentioned in the email.
  • start and end return the milliseconds from January 1, 1970 (same as message.sentDate).
  • If an end time is mentioned but no end date (ex. "Meeting from 2-3"), endTime will be returned, but not endDate which will be assumed to be the same as startDate. The end value will reflect the end time on the same day.
  • If the time is not set, start or end will be set to midnight of the day mentioned.
  • title: the derived title of the event.
  • The start and end values reflect the user's time zone, taking into account hairy things like daylight savings. If the app you are connecting to requires a more specific format than the startDate and startTime text, it is strongly recommended you use the start and end values instead of piecing it together yourself.

message.dates

Similar to events but includes every date found (no combining duplicates), and includes addition properties for where in the text each mention was found. (Unless you need to know who wrote what date where, we recommend sticking with events). 
"dates": [ { 
   "start":1399316400000,
   "startDate":"2014-05-05",
   "startTime":"2:00pm",
   "end":1399320000000,
   "endTime":"3:00pm",
   "title":"Coffee",
   "text":"coffee from 2-3 tomorrow",
   "context":"Let's meet for coffee from 2-3 tomorrow.",
   "index":15,
   "messageIndex":0
},
{
   "start":1401771600000,
   "startDate":"2014-06-03",
   "end":1402030800000,
   "endDate":"2014-06-06",
   "title":"Conference",
   "text":"Conference June 3-6",
   "context":"Tech Conference June 3-6",
   "index":137,
   "messageIndex":0
},
{
   "start":1399908600000,
   "startDate":"2014-05-12",
   "startTime":"10:30am",
   "title":"Meet-up",
   "text":"meet-up next Monday at 10:30",
   "context":"Let's meet-up next Monday at 10:30am.",
   "index":6,
   "messageIndex":0,
   "source":"subject"
} ]
  • See events for details of the date formats.
  • text: the full text of the date found.
  • context: the full text plus the text before and after.
  • index: The text index in the message text.
  • source: Where in the email the date was found. If empty, found in the main text.
    Possible values: subject.
  • messageIndex: The message index of the text found (0 for the main email, 1 for the first included message. See messages).

message.contacts

The names and contact information of every person mentioned in the email. Combines any repeated names and aggregates any details of each into one result. (For details on who mentioned what name where, see names). 
"contacts": [ {
   "name":"Alan T Pearl",
   "firstName":"Alan",
   "lastName":"Pearl",
   "middle":"T",
   "jobTitle":"owner",
   "companyName":"Pearl Dentistry",
   "emailAddress":"alan@pearldentistry.com",
   "phoneNumbers": [ { "phoneType":"work","number":"5733453456" },
                     { "phoneType":"mobile","number":"5734564567","extension":"222" }],
   "address": { "fullAddress":"123 Main St. Blaine, MO 63777",
                "city":"Blaine",
                "zip":"63777",
                "streetAddress":"123 Main St.",
                "state":"MO" },
   "urls": ["http://pearldentistry.com"]
} ]
  • Possible values for phoneType: work, mobile, home, fax

message.names

Similar to contacts, but returns every name mentioned (no aggregation), and additional text properties. 
"names": [ {
   "name":"Alan T Pearl",
   "firstName":"Alan",
   "lastName":"Pearl",
   "middle":"T",
   "jobTitle":"owner",
   "companyName":"Pearl Dentistry",
   "emailAddress":"alan@pearldentistry.com",
   "phoneNumbers": [ { "phoneType":"work","number":"5733453456","extension":"222" },
                     { "phoneType":"mobile","number":"5734564567" } ],
   "address": { "fullAddress":"123 Main St. Blaine, MO 63777-4863",
                "streetAddress":"123 Main St.",
                "city":"Blaine",
                "state":"MO",
                "zip":"63777",
                "zip4":"48663" },
   "urls": [ "http://pearldentistry.com" ],
   "text":"Alan T Pearl, the owner of Pearl Dentistry. He's at:\r\nhttp://pearldentistry.com\r\no: 573-345-3456 x222\r\nm: 573-456-4567\r\nalan@pearldentistry.com\r\n123 Main St.\r\n\r\nBlaine, MO 63777-4863",
   "context":"I met Alan T Pearl, the owner of Pearl Dentistry. His details:\r\nhttp://pearldentistry.com\r\no: 573-345-3456 x222\r\nm: 573-456-4567\r\nalan@pearldentistry.com\r\n123 Main St.\r\n\r\nBlaine, MO 63777-4863",
   "index":15,
   "messageIndex":0
} ]
  • index and messageIndex return the text index and message index of the name text (similar to dates).

message.tags

A collection of tags found in or derived from the email
"tags" : [ "meeting", "saveforlater", "goodtoknow" ]
  • Includes important words found in the email as well as any use of a hashtag phrase in the email. #goodtoknow

Additional Notes

  • If no data of a certain type is found in an email, the property will not be present on the message object, so be sure to check if exists first. For example, if no dates are found in an email, the dates property will not be set on the message object.
  • For arrays, we recommend you also check the length before referencing array items:
    if (message.dates && message.dates.length > 0) //can now reference message.dates[0]

The possibilities get a lot more interesting once you connect your script to other applications!