Data & Connectivity

Email and Calendar

Sending Emails

Emails can be sent from within a 3forge session using the SMTP protocol. To enable and configure 3forge for email, add the following properties in your local.properties file:

email.client.host=smtp-mail.office365.com
email.client.port=587
email.client.username=your.email@outlook.com
email.client.password=your.password

Change the host and port properties accordingly for your email's SMTP server.

More email configuration properties can be found in the relay configuration guide.

Note

3forge only supports SMTP for sending emails. If you require alternative methods, please reach out to us at support@3forge.com to find you another solution.

AmiScript Methods

There are two methods in AmiScript for sending emails which can be called from the web session:

• session.sendEmail(...)

  Sends an email and returns immediately with the email-send-UID.

• session.sendEmailSync(...)

  Sends an email and returns with the email result.

For more detail on these methods, see the documentation here.

Example Email

In some field accepting AmiScript:

session.sendEmailSync("support@3forge.com",new List("recipient@some_host.com"),"Hello Recipient", false, "Hello! How are you?", null, null, null, null);

This sends an email titled "Hello Recipient" with the text contents "Hello! How are you?"

Supported Attachment File Formats

Application

atom, json, jar, js, ogg, ogv, pdf, ps, woff, xhtml, xht, xml, dtd, zip, gz, xlsx

Audio

au, snd, mid, rmi, mp3, aif, aifc, aiff, m3u, ra, ram, wav

Image

bmp, cod, gif, ief, jpe, jpeg, jpg, jfif, png, svg, tif, tiff, ras, cmx, ico, pnm, pbm, pgm, ppm, rgb, xbm, xpm, xwd

Message

mht, mhtml, nws

Text

css, 323, htm, html, stm, uls, bas, c, h, txt, ami, rtx, sct, tsv, htt, htc, etc, vcf, ics

Video

mp2, mpa, mpe, mpeg, mpg, mpv2, mov, qt, lsf, lsx, asf, asr, asx, avi, movie

X-world

flr, vrml, wrl, wrz, xaf, xof

CC and BCC

To CC or BCC someone, prefix the email with "cc:" or "bcc:"

"cc:target_email_address@..."

Note

If using a Google Workspace account, you will need to set up app passwords as Google's long-time Less Secure Apps (LSA) functionality is being deprecated in January 2025.

ICalendar

ICalendar format (.ics) invitations can be created and sent via email directly from 3forge. Ensure that your 3forge instance is configured with a working email as shown in the Sending Emails section to send the invitations from.

Generating an ICalendar can be broken down into three steps, all of which can be done within 3forge:

1. Creating the ICalendar object in 3forge.
2. Populating the ICalendar with organizers, attendees, and the event.
3. Sending the .ics invite via email.

For a full description and list of methods associated to the ICalendar object in AmiScript, see the documentation here.

AmiScript Methods

This is a basic overview of the methods needed to make an ICalendar object and populating it.

• ICalendar calendar = new ICalendar()

  Construct a new ICalendar object called "calendar".

• calendar.addEvent(...)

  Add an event with some parameters (example shown below).

• calendar.addOrganizer(...)

  Add organizer(s) to the event with some parameters, such as their name.

• calendar.addAttendee(...)

  Add attendee(s) to the event with some parameters, such as their role.

• calendar.build()

  Builds a string of the .ics file content of the ICalendar object.

Example ICalendar Event

ICalendar calendar = new ICalendar();
calendar.addEvent(
  "An Important Event", 
  "EST5EDT", 
  parseDate("08 Nov 2024 16:00", "dd MMM yyyy hh:mm", "America/New_York"),
  parseDate("08 Nov 2024 17:00", "dd MMM yyyy hh:mm", "America/New_York"),
  "New York",
  "An important event with 3forge and our guest",
  "English",
  "OPAQUE",
  "PUBLIC"
  ); 
calendar.addOrganizer(0, "support@3forge.com", "3forge Support", "3forge", "", "");
calendar.addAttendee(0, "guest@some_host.com", "", "Guest");

This uses three ICalendar methods to create and populate an event.

The addEvent() method takes the following comma-delimited parameters:

1. Summary

   • Example: "An Important Event"
   • String title for the event

2. Timezone

   • Example: "EST5EDT"
   • String Java TimeZone ID (you can find the full list on the Oracle website)

3. Start time

   • Example: parseDate("08 Nov 2024 16:00", "dd MMM yyyy hh:mm", "America/New_York")
   • Time in UTC the event starts (you can use the AmiScript parseDate() function as in the example)
   • To specify an all-day event, do not supply times
     • E.g, parseDate("08 Nov 2024", "dd MMM yyyy", "America/New_York")

4. End time

   • Example: parseDate("08 Nov 2024 15:00", "dd MMM yyyy hh:mm", "America/New_York")
   • Time in UTC the event ends (you can use the AmiScript parseDate() method as in the example)
   • To specify an all-day event, do not supply times
     • E.g, parseDate("08 Nov 2024", "dd MMM yyyy", "America/New_York")

5. Location

   • Example: "New York"
   • String location of the event

6. Description

   • Example: "An important event with 3forge and our guest"
   • String description of the event

7. Language

   • Example: "English"
   • (Optional) string description of the language of the event. For any optional string parameters, simply pass the empty string.

8. Transparency

   • Example: "OPAQUE"
   • String transparency of the event
   • Can be "OPAQUE" or "TRANSPARENT"

9. Visibility

   • Example: "PUBLIC"
   • String visibility of the event
   • Can be "PUBLIC", "PRIVATE", or "CONFIDENTIAL"

Send Event Invite via Email

In the same AmiScript block, to send a .ics invitation over email of the ICalendar contents:

String calendar_string = calendar.build();

session.sendEmailSync(
  "support@3forge.com", 
  new List("guest@some_host.com"),
  "Event Invitation", false,
  "You are invited to the following event. We hope to see you there.",
  new List("invite.ics"), new List(calendar_string), null, null
  );

This uses the build() method to convert the ICalendar object into a string output which is then passed as the attachment contents of the sendEmailSync() method.