Email Send


The email send service is used to send test emails of all types, and to send live Triggered Emails.

single

bool email_send.single( int emailId, string recipient, array options )

Sends a single test email to the specified recipient.

Parameters

emailId

ID of the email of which to send the single test.

recipient

The email address of the recipient.

options

Specifies some specific options for sending the test email. All are optional.

Name

Type

Description

messagepart

string

auto, html, or text. Default auto

record

string

Use Recipient with this email address to render recipient-specific content

from

string

Specify an email address to use as the from address

Return Values

Returns true on success.



singleByEmailAddress

bool email_send.singleByEmailAddress( string emailAddress, int emailId, string recipient, array options )

Sends a single test email to the specified recipient.

Parameters

emailAddress

Email address of the recipient upon which to base the email content, for any recipient-specific content.

emailId

ID of the email of which to send the single test.

recipient

The email address of the recipient.

options

See #single, except record is ignored.

Return Values

Returns true on success.



singleByRecipientId

bool email_send.singleByRecipientId( int recipientId, int emailId, string recipient, array options )

Sends a single test email to the specified recipient.

Parameters

recipientId

ID of the recipient upon which to base the email content, for any recipient-specific content.

emailId

ID of the email of which to send the single test.

recipient

The email address of the recipient.

options

See #single, except record is ignored.

Return Values

Returns true on success.



seed

array email_send.seed( int emailId, array exclude, array options )

Sends a test email to the assigned seed list.

Parameters

emailId

ID of the email of which to send the seed test.

exclude

An indexed array of email addresses from the seed list which should not receive a test.
Example:

array(
    'user1@example.com',
    'user3@example.com',
    'user5@example.com'
);

options

See #single, except record is ignored.

Return Values

Returns a integer value representing the process status returned.



triggerFolder

array email_send.triggerFolder( int folderId, string emailAddress, array profileData )

Chooses a random live Triggered Email from the given folder, and queues it to the specified recipient for immediate send. The system uses a weighted random choice, so that over the course of many sends, there is even distribution amongst all live Triggered Emails in the folder. Only Triggered Emails directly in the target folder are uses; child folders are not used.

Will fail if no Triggered Emails in the folder have approved status.

Parameters

folderId

ID of the folder containing the triggered emails, from which one will be chosen.

emailAddress

The email address of the recipient. It's also possible to provide a recipientId integer for this parameter.

profileData

Associative array of profile data in the same format used for recipient.insert; a nested array of named profiles and profile fields:

array(
    'Personal' => array(
        'FirstName' => 'Test',
        'Surname' => 'Person',
    ),
    'Address/Home' => array(
        'Street' => 'Example Close',
        'Town' => 'Sample City'
    )
);

Return Values

Returns an associative array with a key success which is always boolean true .


triggerFolderDelay

array email_send.triggerFolderDelay( int folderId, string emailAddress, array profileData, int delay, bool cancelExisting )

Queue a Triggered Email in the same manner as #triggerFolder but send after a defined delay. Optionally cancel any existing queued emails.

The profile data is stored in the queue and is not set to the Recipient until the delay period. This means any other changes that made to the Recipient's profile data within the delay period will be overwritten for any fields contained in the profile data submitted with this method.

Parameters

See the #triggerFolder method above.

delay

A time in seconds to delay the sending of this triggered email.

cancelExisting

If true, will cancel any existing queued/delayed triggered emails. See #cancelTriggerFolder for an explanation of the behaviour.

Return Values

Returns an associative array with a key success which is always boolean true .



cancelTriggerFolder

bool email_send.cancelTriggerFolder( int folderId, string emailAddress )

Cancel any existing queued/delayed triggered emails which match the folderId and recipient. Regardless of sending an email address or recipientId for the emailAddress parameter, it is the actual Recipient that is matched in the queue.

Parameters

See the #triggerFolder method above.

folderId

ID of the folder containing the triggered emails, from which one will be chosen.

Return Values

Returns boolean true on success.



trigger

array email_send.trigger( int emailId, string emailAddress, array profileData )

Queues a live triggered email to the specified recipient for immediate send. Will fail if the triggered email status is not approved.

Rather than trigger a single email, use triggerFolder instead.

When the marketer needs to create a new version of the Triggered Email to update the content, the API call won't need to be updated with a new emailId. The marketer can just drop a new Triggered Email in the existing folder, and move the old version into an archive folder. See Guide to Triggered Emails for more information.

Parameters

emailId

ID of the triggered email to send.

emailAddress

The email address of the recipient. It's also possible to provide a recipientId integer for this parameter.

profileData

Associative array of profile data in the same format used for recipient.insert; a nested array of named profiles and profile fields:

array(
    'Personal' => array(
        'FirstName' => 'Test',
        'Surname' => 'Person',
    ),
    'Address/Home' => array(
        'Street' => 'Example Close',
        'Town' => 'Sample City'
    )
);

Return Values

Returns an associative array with a key success which is always boolean true .



triggerDelay

array email_send.triggerDelay( int emailId, string emailAddress, array profileData, int delay, bool cancelExisting )

Allows a triggered email to be queued for sending to a recipient after a defined delay. Optionally cancel any existing queued emails.

The profile data is stored in the queue and is not set to the recipient until the delay period. This means any other changes that made to the recipient's profile data within the delay period will be overwritten for any fields contained in the profile data submitted with this method.

Rather than trigger a single email, use triggerFolderDelay instead.

When the marketer needs to create a new version of the Triggered Email to update the content, the API call won't need to be updated with a new emailId. The marketer can just drop a new Triggered Email in the existing folder, and move the old version into an archive folder. See Guide to Triggered Emails for more information.

Parameters

See the #trigger method above.

delay

A time in seconds to delay the sending of this triggered email.

cancelExisting

If true, will cancel any existing queued/delayed triggered emails. See #cancelTrigger for an explanation of the behaviour.

Return Values

Returns an associative array with a key success which is always boolean true .



cancelTrigger

bool email_send.cancelTrigger( int emailId, string emailAddress )

Cancel any existing queued/delayed triggered emails which match the emailId and recipient. Regardless of sending an email address or recipientId for the emailAddress parameter, it is the actual recipient that is matched in the queue.

Rather than trigger a single email, use cancelTriggerFolder instead.

When the marketer needs to create a new version of the Triggered Email to update the content, the API call won't need to be updated with a new emailId. The marketer can just drop a new Triggered Email in the existing folder, and move the old version into an archive folder. See Guide to Triggered Emails for more information.

Parameters

See the #trigger method above.

Return Values

Returns boolean true on success.

Service

email_send

Methods