rtm

The rtm module allows to interact with the data in your Remember The Milk account.

addList(name)

Adds a new list. Throws an error if a list or a Smart List with the given name already exists.

Parameters

name: The name of the new list. Cannot be empty or contain only whitespace. Inbox and Sent are reserved names.

Return value

The newly added List.

Example

// Adds a new list named "Travel Plans".
const list = rtm.addList('Travel Plans');
console.log('Added the list "%s".', list.getName());

addSmartList(name, filter)

Adds a new Smart List. Throws an error if a list or a Smart List with the given name already exists.

Parameters

name: The name of the new Smart List. Cannot be empty or contain only whitespace. Inbox and Sent are reserved names.

filter: The search criteria of the new Smart List.

Return value

The newly added SmartList.

Example

// Adds a new Smart List named "Not Urgent" with "due:never" criteria.
const smartList = rtm.addSmartList('Not Urgent', 'due:never');
console.log('Added the Smart List "%s" with criteria "%s".',
  smartList.getName(), smartList.getFilter());

addTag(name)

Adds a new tag with the given name. Does nothing if the tag already exists.

Parameters

name: The name of the tag. The name is lowercased and stripped of unsupported characters. It cannot be empty or contain only whitespace.

Return value

The newly added or already existing Tag.

Example

// Adds a new tag named 'groceries'.
const tag = rtm.addTag('groceries');
console.log('Added the tag "%s".', tag.getName());

addTask(name, parse)

Adds a new task with the given name.

Parameters

name: The name of the new task. Cannot be empty or contain only whitespace.

parseOptional: true to use Smart Add to process the task name, false otherwise.

Return value

The newly added Task.

Example

// Adds a new task named "Write my first MilkScript".
const task = rtm.addTask('Write my first MilkScript ^today !1 =15min', true);
console.log('Added the task "%s" (due %s, priority %s, estimate %s).',
  task.getName(), task.getDueDate(), task.getPriority(), task.getEstimate());

args

Represents an object accessible inside scripts that contains the values of the arguments passed to that script.

Example

// Creates a new task in the provided list.
const list = rtm.args['My list'];
const taskName = rtm.args['My new task name'];

const task = list.addTask(taskName);

console.log(`Created '${taskName}' in ${list.getName()}.`);

getContacts()

Gets all contacts.

Return value

The list of all Contacts.

Example

// Outputs the number of contacts you have.
const contacts = rtm.getContacts();
console.log('You have %d contact(s)', contacts.length);

getInbox()

Gets your Inbox list.

Return value

The Inbox List.

Example

// Outputs the date the Inbox was created.
const inbox = rtm.getInbox();
console.log('Inbox was created on %s', inbox.getCreatedDate());

getLists()

Gets all lists that you own or have access to.

Return value

All your Lists.

Example

// Outputs the names of all lists.
rtm.getLists().forEach(list => console.log(list.getName()));

getLocations()

Gets all locations.

Return value

The list of all Locations.

Example

// Outputs the addresses of all locations.
rtm.getLocations().forEach(location =>
  console.log("%s - %s", location.getName(), location.getAddress()));

getSelectedTasks()

Gets the list of selected tasks.

Return value

The list of selected Tasks.

Example

// Outputs the total estimate of the selected tasks.
const tasks = rtm.getSelectedTasks();
const zero = rtm.newEstimate(0);
const total = tasks.reduce((estimate, task) =>
  estimate.plus(task.getEstimate() ?? zero), zero);

console.log("%d task(s) - Total %s", tasks.length, total);

getSmartLists()

Gets all Smart Lists.

Return value

The list of all SmartLists.

Example

// Outputs the search criteria of all Smart Lists.
rtm.getSmartLists().forEach(smartList =>
  console.log("%s - %s", smartList.getName(), smartList.getFilter()));

getTags()

Gets all tags.

Return value

The list of all Tags.

Example

// Outputs the list of all tags.
rtm.getTags().forEach(tag => console.log(tag.getName()));

getTasks(filter)

Gets all tasks.

Parameters

filterOptional: If specified, only tasks matching the given criteria are returned.

Return value

The list of Tasks.

Example

// Outputs the number of incomplete tasks that are due today.
const tasks = rtm.getTasks('due:today AND status:incomplete');
console.log('Incomplete tasks due today: %d', tasks.length);

me()

Gets your username, email, and other details.

Return value

The User details.

Example

// Outputs your username.
console.log('Your username is "%s"', rtm.me().getUsername());

MediaType

Represents a list of common media types.

rtm.MediaType.CSV
rtm.MediaType.ICAL
rtm.MediaType.JSON
rtm.MediaType.TEXT

Month

Represents the months of the year:

rtm.Month.January
rtm.Month.February
rtm.Month.March
rtm.Month.April
rtm.Month.May
rtm.Month.June
rtm.Month.July
rtm.Month.August
rtm.Month.September
rtm.Month.October
rtm.Month.November
rtm.Month.December

newDailyRecurrence()

Creates a recurrence rule that causes a task to recur on a daily basis.

Return value

The newly created Recurrence.

Example

// every day
const everyDay = rtm.newDailyRecurrence();

// every 3 days
const every3Days = rtm.newDailyRecurrence().interval(3);

// every 5 days for 10 times
const every5DaysFor10Times =
  rtm.newDailyRecurrence().interval(5).times(10);

// every 24 days until Mon 27 Jan 25
const every24DaysUntil27Jan25 =
  rtm.newDailyRecurrence().interval(24).until(new Date('27 Jan 25'));

// after 1 day
const afterOneDay = rtm.newDailyRecurrence().onlyAfterCompletion();

// after 2 days
const after2Days = rtm.newDailyRecurrence().interval(2).onlyAfterCompletion();

newEstimate(hours, minutes)

Creates an estimate from the given hours and minutes.

Parameters

hours: The number of hours; cannot be negative.

minutesOptional: The optional number of minutes; cannot be negative.

Return value

The newly created Estimate.

Example

// 10 minutes
const estimate10minutes = rtm.newEstimate(0, 10);

// 1 hour
const estimate1hour = rtm.newEstimate(1);

// 2 hours 3 minutes
const estimate2hours30minutes = rtm.newEstimate(2, 30);

newFile(data, mediaType, name)

Creates a File that can be served from a script.

Parameters

data: The bytes for the file or a string in UTF-8 encoding.

mediaTypeOptional: The optional media type of the file. Defaults to text/plain if not specified.

nameOptional: The optional name of the file.

Return value

The newly created File.

Example

// Returns a JSON file with all Smart Lists.
const entries = rtm.getSmartLists()
  .map(smartList => [smartList.getName(), smartList.getFilter()]);

const jsonString = JSON.stringify(Object.fromEntries(entries));

rtm.newFile(jsonString, rtm.MediaType.JSON, 'SmartLists.json');

newMessage(title, text)

Creates a text Message that can be served from a script.

Parameters

title: The title of the message. Cannot be empty or contain only whitespace.

text: The text of the message. Cannot be empty or contain only whitespace.

Return value

The newly created text Message.

Example

// Shows a message box with the total estimate of the selected tasks.
const tasks = rtm.getSelectedTasks();
const zero = rtm.newEstimate(0);
const total = tasks.reduce((estimate, task) =>
  estimate.plus(task.getEstimate() ?? zero), zero);

const minutes = total.getMinutes() % 60;
const hours = Math.floor(total.getMinutes() / 60);

const title = `${tasks.length} ${tasks.length === 1 ? 'task' : 'tasks'}`;
const text = `Total Estimate: ${hours} ${hours === 1 ? 'hour' : 'hours'}, ${minutes} ${minutes === 1 ? 'minute' : 'minutes'}`;

rtm.newMessage(title, text);

newMonthlyRecurrence(weekday, week)

Creates a recurrence rule that causes a task to recur on a monthly basis. The rule applies only to the given week and day of the week.

Parameters

weekday: The Weekday the rule applies to.

week: The WeekOfMonth the rule applies to.

Return value

The newly created Recurrence.

Example

// every month on the 1st Wednesday
const everyMonthOn1stWednesday =
  rtm.newMonthlyRecurrence(rtm.Weekday.Wednesday, rtm.WeekOfMonth.First);

// every 2 months on the last Thursday
const every2MonthsOnLastThursday = rtm.newMonthlyRecurrence(
  rtm.Weekday.Thursday, rtm.WeekOfMonth.Last).interval(2);

newMonthlyRecurrence(...days)

Creates a recurrence rule that causes a task to recur on a monthly basis.

Parameters

...daysOptional: If specified, makes the rule apply only to specific days of the month.

Return value

The newly created Recurrence.

Example

// every month
const everyMonth = rtm.newMonthlyRecurrence();

// every 2 months
const every2Months = rtm.newMonthlyRecurrence().interval(2);

// every 3 months on 22nd day
const every3MonthsOn22ndDay = rtm.newMonthlyRecurrence(22).interval(3);

// every 4 months on 1st, 10th, and 20th days
const every4MonthsOnDays = rtm.newMonthlyRecurrence(1, 10, 20).interval(4);

// every 5 months
const every5MonthsFor2Times =
  rtm.newMonthlyRecurrence().interval(5).times(2);

// every 6 months until Thu 17 Nov 22
const every6MonthsUntil17Nov22 =
  rtm.newMonthlyRecurrence().interval(6).until(new Date('17 Nov 22'));

// after one month
const after1Month = rtm.newMonthlyRecurrence().onlyAfterCompletion();

// after 2 months
const after2Months = rtm.newMonthlyRecurrence().onlyAfterCompletion().interval(2);

newWeeklyRecurrence(...weekdays)

Creates a recurrence rule that causes a task to recur on a weekly basis.

Parameters

...weekdaysOptional: If specified, makes the rule apply only to specific days of the week.

Return value

The newly created Recurrence.

Example

// every week
const everyWeek = rtm.newWeeklyRecurrence();

// every 3 weeks
const every3Weeks =
  rtm.newWeeklyRecurrence().interval(3);

// every 4 weeks on Monday
const every4WeeksOnMonday =
  rtm.newWeeklyRecurrence(rtm.Weekday.Monday).interval(4);

// every 5 weeks on Monday, Tuesday and Saturday
const every5WeeksOnWeekdays = rtm.newWeeklyRecurrence(
  rtm.Weekday.Monday, rtm.Weekday.Tuesday, rtm.Weekday.Saturday).interval(5);

// every 6 weeks for 3 times
const every4WeeksFor3Times = rtm.newWeeklyRecurrence().interval(6).times(3);

// every week until Fri 28 Mar 25
const everyWeekUntil28Mar25 =
  rtm.newWeeklyRecurrence().until(new Date('28 Mar 25'));

// after one week
const after1week = rtm.newWeeklyRecurrence().onlyAfterCompletion();

// after 3 weeks
const after3weeks =
  rtm.newWeeklyRecurrence().interval(3).onlyAfterCompletion();

newYearlyRecurrence(month, week, weekday)

Creates a recurrence rule that causes a task to recur on a yearly basis. The rule applies only to the given month, week, and day of the week.

Parameters

month: The Month the rule applies to.

week: The WeekOfMonth the rule applies to.

weekday: The Weekday the rule applies to.

Return value

The newly created Recurrence.

Example

// every year on the 1st Thursday in January
const everyYearOn1stThursdayInJanuary = rtm.newYearlyRecurrence(
  rtm.Month.January, rtm.WeekOfMonth.First, rtm.Weekday.Thursday);

// every 2 years on the last Monday in March
const every2YearsOnTheLastMondayInMarch = rtm.newYearlyRecurrence(
  rtm.Month.March, rtm.WeekOfMonth.Last, rtm.Weekday.Monday);

newYearlyRecurrence(month, day)

Creates a recurrence rule that causes a task to recur on a yearly basis. The rule applies only to the given month and day of the month.

Parameters

month: The Month the rule applies to.

day: The day of the month.

Return value

The newly created Recurrence.

Example

// every year on March 3
const everyYearOnMarch3 = rtm.newYearlyRecurrence(rtm.Month.March, 3);

// every 5 years on April 22
const every5YearsOnApril22 =
  rtm.newYearlyRecurrence(rtm.Month.April, 22).interval(5);

// every 2 years on January 1 for 3 times
const every2YearsOnJanuary1For3Times =
  rtm.newYearlyRecurrence(rtm.Month.January, 1).interval(2).times(3);

newYearlyRecurrence()

Creates a recurrence rule that causes a task to recur on a yearly basis.

Return value

The newly created Recurrence.

Example

// every year
const everyYear = rtm.newYearlyRecurrence();

// every 2 years
const every2Years = rtm.newYearlyRecurrence().interval(2);

// every 3 years for 9 times
const every3YearsFor9Times = rtm.newYearlyRecurrence().interval(3).times(9);

// every 4 years until Sat 17 Jan 32
const every4YearsUntil17Jan32 =
  rtm.newYearlyRecurrence().interval(4).until(new Date('17 Jan 32'));

// after one year
const after1Year = rtm.newYearlyRecurrence().onlyAfterCompletion();

// after 5 years
const after5Years =
  rtm.newYearlyRecurrence().onlyAfterCompletion().interval(5);

Priority

Represents task priority values:

rtm.Priority.High
rtm.Priority.Medium
rtm.Priority.Low
rtm.Priority.NoPriority

Example

// Searches tasks due today, then sets their priority to `High`.
const tasks = rtm.getTasks('due:today');

tasks.forEach(task => task.setPriority(rtm.Priority.High));

console.log('Updated priority of %d task(s).', tasks.length);

Weekday

Represents the days of the week:

rtm.Weekday.Sunday
rtm.Weekday.Monday
rtm.Weekday.Tuesday
rtm.Weekday.Wednesday
rtm.Weekday.Thursday
rtm.Weekday.Friday
rtm.Weekday.Saturday

WeekOfMonth

Represents the weeks of the month:

rtm.WeekOfMonth.First
rtm.WeekOfMonth.Second
rtm.WeekOfMonth.Third
rtm.WeekOfMonth.Fourth
rtm.WeekOfMonth.Last