Sunday, July 17, 2011

How to use the SendTransactionalEmailRaw API method

Overview:

The SendTransactionalEmailRaw method is a special API method that allows you to send a transactional email, but requires you to assemble a MIME compliant message body on your own. By contrast, the more common method, SendTransactionalEmail, need only an HTML body, a Plain Text body, and optional attachments, and then the API will assemble the MIME-formatted message automatically for transmission to the recipient.

SendTransactionalEmailRaw is the method that is used behind-the-scenes by our SMTP relay service. Anytime a user relays a message to relay.jangosmtp.net, our code internally calls SendTransactionalEmailRaw. This method was originally developed just for our internal use to enable our SMTP relay, but since it appears in our full method listing, our clients have begun inquiring about how they too can use it, and that's why we are publishing this article.

Examples:

In this article, we'll look at examples of manually assembled MIME parts and how to submit the raw message to this method.

First, let's look at the input parameters of the method. Some should be self-explanatory, so we won't include explanations of those here.

Options: This input value represents the same as for the SendTransactionalEmail method, so we won't cover them here. Here you can set options like open tracking, click tracking, a custom reply-to address, and much more. For more info on the Options parameter, see http://api.jangomail.com/help/html/655d20ca-2164-c483-fb21-d3d0ee049155.htm

ToEmailAddress: This is the email address that will receive this message.

ToHeader: This is the email address that will show in the To header of the email message, which technically doesn't have to be the recipient of the message. It is important to distinguish between ToHeader and ToEmailAddress. In most business cases, these will be the same email address and therefore the same value. If I want to send an email to john@company.com, then ToEmailAddress=john@company.com and ToHeader=john@company.com, because I want the To header to show the same email address to which the message was sent.

Scenarios where the To header and the receiving email address differ include situations when CC and BCC are used. If I send an email to john@company.com and BCC attorney@company.com, then in the background, two distinct emails are actually being transmitted:

1. ToHeader=john@company.com and ToEmailAddress=attorney@company.com
2. ToHeader=john@company.com and ToEmailAddress=john@company.com

Content-Type: This is the RFC 2045 Content-Type header of the email message.

Example values are:
  1. text/plain
  2. text/html
  3. multipart/alternative; boundary="----=_NextPart_000_2424_01CA056C.1610FF60"
RawMessage: This is the pre-assembled MIME message and is closely related to the value for Content-Type. If Content-Type is text/plain, then the value for RawMessage could be any plain text message:

Example 1

Content-Type: text/plain
RawMessage:
This is a simple plain text message.

Example 2

Here's an example of a body with both HTML and Plain text message parts.

Content-Type:
multipart/alternative; boundary="------------020009050405090403020909"
RawMessage:




Example 3

Lastly, here's an example of a plain text message with an attachment.

Content-Type: multipart/mixed;
boundary="------------020306090104040909010309"
RawMessage:

Test Form:

You can experiment with the method using the test form at http://api.jangomail.com/SendTransactionalEmailRaw.html. This form has textareas instead of text fields for those input parameters that warrant them, making it easier to test than the API-generated page at http://api.jangomail.com/api.asmx?op=SendTransactionalEmailRaw

Lastly, here is a screenshot of the test form filled out for the third example (plain text message with attachment), so you can see exactly how the method would be called: