BrandMail API - addMessage

Syntax

int addMessage( string api_key, array message_details );

Parameters

api_key (string): The key required to access the API. See Getting Started for more information.
message_details (array): An associative array of Message details. See remarks below for a description of the values in the message_details array.

Return Value

Returns the ID of the newly added Message on success.

Examples

The following message creates an Email that contains a monthly issue of a newsletter.

$message_details = array(

    'type'          => 'email',

    'email_type'    => 'html',

    'name'          => 'Newsletter 1234: January 2013',

    'subject'       => 'Your January 2013 Newsletter is here...',

    'html_content'  => '<html><body><p>Welcome to newsletter 1234 ....</p></body></html>'

);

$api = new Api($url, 'YOURAPIKEY');

$message_id = $api->invokeMethod('addMessage', $message_details);

{

    "id": 1,

    "method": "addMessage",

    "params": [

        "YOURAPIKEY",

        {

            "type": "email",

            "email_type": "html",

            "name": "Newsletter 1234: January 2013",

            "subject": "Your January 2013 Newsletter is here...",

            "html_content": "<html><body><p>Welcome to newsletter 1234 ....<\/p><\/body><\/html>"

        }

    ]

}

{

    "id": 1,

    "result": 111222,

    "error": null

}

Remarks

The following table shows the structure of the message_details array.

Key	Type	Mandatory	Default	Description
`type`	string	Yes		The type of Message to be added. Must be either `sms` or `email`.
`name`	string	Yes		The name of the Message.
`email_type`	string	No*		Required for `email` Messages. The Email type. Valid values are `html`, `plain-html`, `plain` or `raw_html`.
`subject`	string	No*		Required for `email` Messages. The Email subject.
`html_content`	string	No*		Required for `html` Emails. The HTML content for `html`, `plain-html` and `raw_html` Emails.
`text_content`	string	No*		Required for `plain` Emails. The text content for `plain` and `plain-html` Emails.
`sms_content`	string	No*		Required for `sms` Messages. The content of the SMS message.
`from_address`	string	No	default address for system	For `email` Messages, a valid Email address or an Email wildcard (variable). For `sms` Messages, a valid mobile phone number or a phone number wildcard.
`from_name`	string	No	default name for system	The name of the sender for `email` Messages.
`reply_to`	string	No	default reply_to address for system	An Email address or Email wildcard (variable.) Only used for `email` Messages.
`postal_address`	string	No	default address for system or Company address	The postal address of the sender for `email` Messages.
`authorised_sender`	string	No	default name for system or User's full name	The authorised sender of the Email for `email` Messages.
`show_update_profile_link`	bool	No	false	Whether or not to show an update profile link for `email` Messages.
`show_unsubscribe_link`	bool	No	true	Whether or not to show an unsubscribe link for `email` Messages.
`unsubscribe_list_id`	int	No	None	The ID of the List accessed by unsubscribe links for `email` Messages.
`unsubscribe_webform_id`	int	No	None	The ID of the web form accessed by unsubscribe links for `email` Messages. Ignored if invalid or `unsubscribe_list_id` is set.
`update_profile_list_id`	int	No	None	The ID of the List accessed by update profile links for `email` Messages.
`update_profile_webform_id`	int	No	None	The ID of the web form accessed by update profile links for `email` Messages. Ignored if invalid or `update_profile_list_id` is set.
`folder_id`	int	No	None	The ID of the Folder to contain the Message. If you do not specify a Folder, Message is assigned to the Folder with lowest ID (the earliest Folder created).

Error Codes

This method may return the following error codes in addition to the standard error codes:

Code	Error	Description
`302`	Undefined Method Error	The changes could not be saved.
`310`	Invalid Method Parameters: Invalid message type	`type` is set to anything other than `email` or `sms`.
`310`	Invalid Method Parameters	`type` is `email` and `email_type` is set to something other than `html`, `plain` and `plain-html`.
`317`	Invalid Email Address Specified: from_address	`from_address` value is invalid.
`326`	SMS content too large	`sms_content` exceeds 600 characters.
`310`	Invalid Method Parameters: no html content	`email_type` is `html` or `raw_html` and `html_content` is omitted from the `message_details` array.
`310`	Invalid Method Parameters: no text content	`email_type` is `plain` and `text_content` is omitted from the `message_details` array.
`310`	Invalid Method Parameters: no html/text content	`email_type` is `plain-html` and both `text_content` and `html_content` are omitted from the `message_details` array.
`310`	Invalid unsubscribe_list_id	`unsubscribe_list_id` value is invalid.
`310`	Invalid unsubscribe_webform_id	`unsubscribe_webform_id` value is invalid.
`310`	Invalid update_profile_list_id	`update_profile_list_id` value is invalid.
`310`	Invalid update_profile_webform_id	`update_profile_webform_id` value is invalid.

addMessage