Acoustic Campaign APIs can be used to create an external interface that allows choosing an email template and sending it to a group of contacts from a CRM system.
In order to invoke the following API operations using CRM Ids, the Campaign Organization must be CRM enabled with an actively syncing CRM integration. Additionally, the specified LIST_ID must be the Organization's CRM Database.
Select an email template
The GetemailTemplates
operation ( (see Appendix A) can be used to return a list of templates and allow the user to choose an email Template to send. An email can be sent immediately or scheduled for the future. If you wish to create recurring emails, this must be done as part of your own application.
On the email Settings tab of Create (or Edit) email Template in the Acoustic Campaign, it is possible to select 'Share template with CRM system.' This can be used to limit the templates that you allow for selection within Salesforce. When calling the API, you can pass the optional IS_CRM_ENABLED parameter with a value of 'true' in order to limit the results.
When an email template is marked as a CRM template, the creator can enable a CRM Block (an area in the email body where the sender can add text at send time) that can be inserted into the body of the template. In the Campaign, place %%SP_CRM_BLOCK%% in the spot where the custom text should appear in the body of your email Template. The GetemailTemplates response indicates whether the template contains %%SP_CRM_BLOCK%% based on the ALLOW_CRM_BLOCK element. If 'true' you could allow specifying text in your application's UI and pass it to the Schedule email operation.
Preview the email
The Preview email operation (see Appendix B) can be used to return the HTML markup of the message the Acoustic Campaign will send, including personalization based on the specified contact.
If sending to a single Lead or Contact, you may wish to preview the email, including personalization for the particular contact. Either a recipient's Email Address or a CRM Sync Id may be specified to determine personalization. If CRM_SYNC_ID and EMAIL are both specified, the CRM_SYNC_ID will be used to look up the recipient.
Send email to CRM leads/contacts
The Schedule email operation (see Appendix C) sends a template-based email to a specific database or a batch of recipients.
The attributes crm_sync_id (the ID of the Lead or Contact in Salesforce) and/or recipient_id (the ID of the Recipient in the Campaign) are used to indicate specific recipients.
If sending to a subset of recipients from the CRM system, the number of recipients for a single call is limited to a batch size of 100.
If more than one batch of the recipient is expected, the MORE_RECIPIENTS element must be set to True and subsequent calls to AddRecipientsToScheduleemail (see Appendix D) are required. When MORE_RECIPIENTS is True, a CONTINUATION_TOKEN is returned in the Schedule email API response. The CONTINUATION_TOKEN is used in the AddRecipientsToScheduleemail request to identify the scheduled email.
If sent to less than 100 recipients, the email will be scheduled/sent when the Schedule email request is made. If the MORE_RECIPIENTS parameter is being used, a call to CommitScheduleemail (see Appendix E) is used to trigger the send after all recipients have been added.
If you are leveraging the previously mentioned CRM_BLOCK, it can be specified in the SUBSTITUTIONS section as follows:
<SUBSTITUTIONS> <SUBSTITUTION> <NAME>SP_CRM_BLOCK</NAME> <VALUE>The text that the Salesforce user specified in your custom UI.</VALUE> </SUBSTITUTION> </SUBSTITUTIONS>
Appendices
Appendix A: Get email Templates
This interface extracts a list of Shared or Private email templates for your Organization. The templates returned may be limited by the date they were last modified.
Operation | <GetemailTemplates> | ||||||||||
Elements | VISIBILITY |
Defines the visibility of the email templates to return. 0 – Private 1 – Shared |
|||||||||
IS_CRM_ENABLED | Optional | When set to "true," the API provides a list of only those email templates that are enabled for use within a CRM package. This allows users to create email templates that are built specifically for sending emails from within a CRM product, like Salesforce.com or Microsoft Dynamics. | |||||||||
LAST_MODIFIED_START_ DATE | Optional | Start Date used to filter email templates by the date and time the email template was last modified. | |||||||||
LAST_MODIFIED_END_DATE | Optional | The end Date used to filter email templates by the date and time the email template was last modified. | |||||||||
Example | <Envelope> <Body> <GetemailTemplates> <VISIBILITY>0</VISIBILITY> <IS_CRM_ENABLED>true</IS_CRM_ENABLED> <LAST_MODIFIED_START_DATE>01/01/2011 13:00:00</LAST_MODIFIED_START_DATE> <LAST_MODIFIED_END_DATE>01/31/2011 12:59:59</LAST_MODIFIED_END_DATE> </GetemailTemplates> </Body> </Envelope> | ||||||||||
Response | Result | ||||||||||
Elements | SUCCESS | True if successful | |||||||||
email_TEMPLATE | XML nodes defining the instances of each email template. | ||||||||||
Child Element | email_ID | Returns the ID of the email template. | |||||||||
email_NAME | Returns the name of the email template. | ||||||||||
SUBJECT | The subject line of the email template | ||||||||||
LAST_MODIFIED | Returns the date and time when the email template was last modified. | ||||||||||
VISIBILITY | Returns the visibility of the email template (Shared or Private). | ||||||||||
USER_ID | Returns the User ID for the email template owner. | ||||||||||
ALLOW_CRM_BLOCK | Identifies that a CRM Block has been inserted into the body of the template and is available for use. This element should only be included in the response for a CRM List. | ||||||||||
Example | <Envelope> <Body> <RESULT> <SUCCESS>TRUE</SUCCESS> <email_TEMPLATE> <email_ID>365333</ email_ID> <email_NAME>email One</ email_NAME> <SUBJECT>email One</ SUBJECT> <LAST_MODIFIED>08/23/07 04:18 PM</LAST_MODIFIED> <VISIBILITY>0</VISIBILITY> <USER_ID>8c3747-111fae2b32c21fbca0cb8d6</USER_ID> <ALLOW_CRM_BLOCK>true</ALLOW_CRM_BLOCK> </email_TEMPLATE > <email_TEMPLATE > <email_ID>323543</ email_ID> <email_NAME>email Two</ email_NAME> <SUBJECT>email Two</ SUBJECT> <LAST_MODIFIED>09/26/07 10:31 AM</LAST_MODIFIED> <VISIBILITY>0</VISIBILITY> <USER_ID>8c3747-111fae23972-f520cb8d6</USER_ID> <ALLOW_CRM_BLOCK>false</ALLOW_CRM_BLOCK> </email_TEMPLATE > </RESULT> </Body> </Envelope> |
Appendix B: Preview email
This interface previews an email template.
Note: This interface will pull back the AOL Body element. This element can be ignored.
Request | <Previewemail> | ||
Parameter | XML | ||
Elements | emailId | Numeric identifier for the email template to be exported. | |
RecipientEmail | Optional | Email address of the recipient in the list that should be used to display personalization. | |
CRM_SYNC_ID | Optional | CRM Sync Id of the recipient in the list that should be used to display personalization. If CRM_SYNC_ID and EMAIL are both specified, the CRM_SYNC_ID will be used to look up the recipient. | |
Example | <Envelope> <Body> <Previewemail> <emailId>59294</emailId> <CRM_SYNC_ID>12345678</CRM_SYNC_ID> </Previewemail> </Body> </Envelope> | ||
Response | <RESULT> | ||
Elements | SUCCESS | TRUE if successful | |
HTMLBody | Returns the contents of the HTML body with personalization substituted except for the %%SP_CRM_BLOCK%% variable. If available, this variable should be substituted with the content gathered in CRM UI. The variable will not appear in the content if this feature is not enabled in the email template. | ||
TextBody | Returns the contents of the Text body with personalization substituted except for the %%SP_CRM_BLOCK%% variable. If available, this variable should be substituted with the content gathered in CRM UI. The variable will not appear in the content if this feature is not enabled in the email template. | ||
SPAMScore | Returns the SPAM score based on the contents of the email template. | ||
Example | <Envelope> <Body> <RESULT> <SUCCESS>TRUE</SUCCESS> <HTMLBody> <![CDATA[<html><HEAD><TITLE></TITLE></HEAD> <BODY> <P>Hello World,</P> <br> <P>I am sending this test message with a CRM Block:</P> <br> %%SP_CRM_BLOCK%% <br> </BODY></html>]]> </HTMLBody> </RESULT> </Body> </Envelope> |
Appendix C: Schedule email
This operation sends a template-based email to a specific list or a batch of recipients. The number of recipients for a single call is limited to batch size. The maximum number of recipients allowed in a single batch is 100.
If more than one batch of the recipient is expected, MORE_RECIPIENTS element must be set to True, and a subsequent call, 'AddRecipientsToScheduleemail' is required, which will be followed by 'CommitScheduleemail' API to commit and complete the process.
A Token returned in the response (when MORE_RECIPIENTS is True) is used in subsequent calls to identify a correct Schedule email API. This token is will expire after 15 minutes of inactivity, upon which the user will need to generate a new Token calling this API again. In such cases, recipients from the previous calls will NOT be sent.
Request | <Scheduleemail> | |||
Elements | TEMPLATE_ID | The ID of the template upon which to base email. | ||
LIST_ID | The ID of the list or query to send a template-based email. The LIST_ID must be a parent List Id (NOT a Query) if RECIPIENTS are specified. | |||
email_NAME | Name to assign to generated email. | |||
Optional Child Element | RECIPIENT | The sub-element of that is repeated for each recipient of the email. There can be one recipient or multiple recipients for each email. | ||
Attributes | crm_sync_id | The Acoustic Campaign recipient id that identifies the contact or lead that has already been synced between the Acoustic Campaign and the CRM system. | ||
recipient_id | The Acoustic Campaign recipient id that identifies the contact or lead that has already been synced between the Acoustic Campaign and the CRM system. | |||
CROSS_REFERENCE | Optional | A string (up to 128 characters) used to reference a Campaign ID in a CRM system. Will be stored with the Sent email record in the Acoustic Campaign for future reference. | ||
SENT_FROM_CRM | Optional | If this element is set to true, the Sent email will be flagged as being sent from the CRM system. | ||
MORE_RECIPIENTS | Optional | True if this element is present. By default, it is set to False. | ||
SEND_HTML | Optional | If this element is present, the value is true. Leave blank if you do not want to include the HTML body. | ||
SEND_TEXT | Optional | If this element is present, the value is true. Leave blank if you do not want to include the text body. | ||
SUBJECT | Optional | If you do not include this element, the Acoustic Campaign uses the subject saved with the template. | ||
FROM_NAME | Optional | If you do not include this element, the Acoustic Campaign uses the From Name saved with the template. | ||
FROM_ADDRESS | Optional | If you do not include this element, the Acoustic Campaign uses the From Address saved with the template. | ||
REPLY_TO | Optional | If you do not include this element, the Acoustic Campaign uses the Reply-To Address saved with the template. | ||
VISIBILITY |
The value indicates where to save the sent email. Values are: 0 - Private Folder 1 - Shared Folder |
|||
SCHEDULED | Value specifying the date and time when the email should be scheduled to send. The format must be MM/DD/YYYY HH:MM:SS AMPM. | |||
SCHEDULED_IN_GMT | If True, the Acoustic Campaign will treat the date/time provided in the SCHEDULED element as GMT rather than interpreting it in the calling user's time zone. | |||
SUPPRESSION_LISTS | Optional | XML node containing one or more SUPPRESSION_LIST_ID child elements | ||
Optional Child Elements | SUPPRESSION_LIST_ID | If any suppression lists are specified, they will be utilized as the suppression lists when the email is sent. | ||
SUBSTITUTIONS | Optional | XML node containing child element SUBSTITUTION | ||
Optional Child Elements | SUBSTITUTION | XML nodes define the substitution name and value. This feature allows template-level substitutions separate from the normal recipient-level substitutions performed by personalization. They are not recipient specific. They are also not related to HTML_GENERAL_DISCLAIMER or the TEXT_GENERAL_DISCLAIMER. Note: If used, each node must have a NAME tag and a VALUE tag. | ||
Optional Child Element | NAME | The substitution tag is used in the email template. This substitution name is case-sensitive. For example, if you include %%Sub_Value_1%% in the email template, the value for this child element is Sub_Value_1. | ||
VALUE | The value that you want to include in the email for the substitution tag with the name given above. | |||
Example | <Envelope> <Body> <Scheduleemail> <TEMPLATE_ID>1000</TEMPLATE_ID> <LIST_ID>100</LIST_ID> <email_NAME>New email Name</email_NAME> <RECIPIENTS> <RECIPIENT crm_sync_id="987654321" recipient_id="123456789"/> <RECIPIENT crm_sync_id="456321987"/> </RECIPIENTS> <SENT_FROM_CRM>true</SENT_FROM_CRM> <CROSS_REFERENCE>12345678</CROSS_REFERENCE> <SEND_HTML/> <SEND_TEXT/> <SUBJECT>This is the new subject</SUBJECT> <FROM_NAME>Senders Name</FROM_NAME> <FROM_ADDRESS></FROM_ADDRESS> <REPLY_TO></REPLY_TO> <VISIBILITY>0</VISIBILITY> <SCHEDULED>10/13/2004 12:00:00 AM</SCHEDULED> <SUPPRESSION_LISTS> <SUPPRESSION_LIST_ID>37782</SUPPRESSION_LIST_ID> <SUPPRESSION_LIST_ID>37744</SUPPRESSION_LIST_ID> </SUPPRESSION_LISTS> <SUBSTITUTIONS> <SUBSTITUTION> <NAME>Sub_Value_1</NAME> <VALUE>The value I would like to put in my email.</VALUE> </SUBSTITUTION> <SUBSTITUTION> <NAME>Sub_Value_2</NAME> <VALUE>Another value I would like to put in my email.</VALUE> </SUBSTITUTION> </SUBSTITUTIONS> </Scheduleemail> </Body> </Envelope> | |||
Response | <RESULT> | |||
Elements | SUCCESS | True if successful. | ||
email_ID | If the request was successful, this element contains the ID for the sent email. | |||
CONTINUATION_T OKEN | Optional | Returns a Token when MORE_RECIPIENTS element is set to True | ||
NOT_SENT | Optional | Returns recipients that could not be sent to when the email was initiated by a CRM system. | ||
Child Element | RECIPIENT | The top-level element that designates one or more recipients that could not be sent to. | ||
Attributes | crm_sync_id | The CRM id that identifies the CRM contact or lead that could not be sent to. Note: If the reason is "not_found", only the crm_sync_id will be returned. | ||
recipient_id | The Acoustic Campaign recipient ID identifies the contact or lead that could not be sent to. | |||
reason |
The reason the recipient could not be sent to. Valid values are:
|
|||
Example Success | <Envelope> <Body> <RESULT> <SUCCESS>TRUE</SUCCESS> <email_ID>9700</email_ID> <CONTINUATION_TOKEN>97ADI0ADFE0BLAIDKA</ CONTINUATION _TOKEN> </RESULT> </Body> </Envelope> | |||
Example CRM email | <Envelope> <Body> <RESULT> <SUCCESS>TRUE</SUCCESS> <email_ID>9700</email_ID> <CONTINUATION _TOKEN>97ADI0ADFE0BLAIDKA</ CONTINUATION _TOKEN> <NOT_SENT> <RECIPIENT crm_sync_id="987654321" recipient_id="123456789" reason="undeliverable"/> <RECIPIENT crm_sync_id="456321987" recipient_id="345678912" reason="opt_out"/> <RECIPIENT crm_sync_id="563218734" recipient_id="567895612" reason="not_found"/> </NOT_SENT> </RESULT> </Body> </Envelope> | |||
Error Codes | 100 | You did not provide a required field. | ||
108 | The list ID does not exist. | |||
145 | The user session is invalid or has expired. | |||
181 | The email ID provided does not exist. | |||
182 | email name already exists. | |||
183 | Errors were found when validating the email to send. | |||
350 | Permission denied for the provided list ID. | |||
506 | Permission was denied for the provided template ID. | |||
1103 | Exceeded batch size. | |||
Example Failure | <Envelope> <Body> <RESULT> <SUCCESS>false</SUCCESS> </RESULT> <Fault> <Request/> <FaultCode/> <FaultString>email Name was not provided</FaultString> <detail> <error> <errorid>100</errorid> <module/> <class>SP.API</class> <method/> </error> </detail> </Fault> </Body> </Envelope> |
Appendix D: Add Recipients to Scheduled email
This Operation is called subsequent to Schedule email API when there is more than one batch of the recipient is expected. The number of recipients for a single call is limited to batch size. The maximum number of recipients allowed in a single batch is 100.
The request must provide a valid Token as an identifier to the Schedule email API call made in the preceding step. This token will expire in 15 mins of inactivity, upon which the user will need to generate a new Token calling Schedule email API, basically starting the process from the beginning. In such a case, recipients from the previous call (associated with expired Token) will NOT be sent.
This Token can be acquired from the Schedule email API call response made in the preceding step.
Request | <AddRecipientsToScheduledemail> | |||
Elements | CONTINUATION_TOKEN | A Token to identify the correct Scheduled email. | ||
RECIPIENTS | The top-level element that designates the recipients' section of the XML envelope. | |||
Child Element | RECIPIENT | The sub-element of that is repeated for each recipient of the email. There can be one recipient or multiple recipients for each email. | ||
Attributes | crm_sync_id | The CRM id that identifies the CRM contact or lead. | ||
recipient_id | The Acoustic Campaign recipient id identifies the contact or lead that has already been synced between the Acoustic Campaign and the CRM system. | |||
Example | <Envelope> <Body> <AddRecipientsToScheduledemail> <CONTINUATION_TOKEN>ADI3892FALX9E37329DJG</ CONTINUATION _TOKEN> <RECIPIENTS> <RECIPIENT crm_sync_id="987654321" recipient_id="123456789"/> <RECIPIENT crm_sync_id="456321987"/> </RECIPIENTS> </AddRecipientsToScheduledemail > </Body> </Envelope> | |||
Response | <RESULT> | |||
Elements | SUCCESS | True if successful. | ||
CONTINUATION _TOKEN | This token is used in the subsequent calls if an additional batch of recipients is expected. | |||
NOT_SENT | Optional | Returns recipients that could not be sent to when the email was initiated by a CRM system. | ||
Optional Child Element | RECIPIENT | The top-level element designates one or more recipients that could not be sent to. | ||
Attributes | crm_sync_id |
The CRM ID that identifies the CRM contact or lead that could not be sent to.
Note: Note: If the reason is "not_found", only the crm_sync_id will be returned.
|
||
recipient_id | The Acoustic Campaignrecipient id that identifies the contact or lead that could not be sent to. | |||
reason |
The reason the recipient could not be sent to. Valid values are:
|
|||
Example Success | <Envelope> <Body> <RESULT> <SUCCESS>True</SUCCESS> <CONTINUATION_TOKEN>ADINALD23957LDNE937</ CONTINUATION _TOKEN> </RESULT> </Body> </Envelope> | |||
Example | <Envelope> <Body> <RESULT> <SUCCESS>True</SUCCESS> < CONTINUATION _TOKEN>9700asdfa4534adfa</ CONTINUATION _TOKEN> <NOT_SENT> <RECIPIENT crm_sync_id="9876543" recipient_id="123456789" reason="undeliverable"/> <RECIPIENT crm_sync_id="4563219" recipient_id="345678912" reason="opt_out"/> <RECIPIENT crm_sync_id="5632187" recipient_id="567895612" reason="not_found"/> </NOT_SENT> </RESULT> </Body> </Envelope> | |||
Error Codes | 100 | You did not provide a required field. | ||
1103 | Exceeded Batch Size. | |||
188 | A token is invalid or has expired. | |||
145 | The user session is invalid or has expired. | |||
Example Failure | <Envelope> <Body> <RESULT> <SUCCESS>False</SUCCESS> </RESULT> <Fault> <Request/> <FaultCode/> <FaultString> Exceeded Batch Size</FaultString> <detail> <error> <errorid>1103</errorid> <module/> <class>SP.API</class> <method/> </error> </detail> </Fault> </Body> </Envelope> |
Appendix E: Commit Scheduled email
This operation is called subsequent to AddRecipientsToScheduledemail API as a final step to commit the process of scheduled email when more than one batch of recipients is being scheduled.
The request must provide a valid Token as an identifier to the Scheduleemail and AddRecipientsToScheduledemail API calls made in the preceding steps. This token will expire after 15 minutes of inactivity, upon which the user will need to generate a new Token calling Scheduleemail API, basically starting the process from the beginning. In such case, recipients from previous calls (associated with expired Token) will NOT be sent.
This Token can be acquired from the response of Scheduleemail or AddRecipientsToScheduledemail API calls made in the preceding steps.
Request | <CommitScheduledemail> | |
Elements | CONTINUATION _TOKEN | A token is required to Commit the Scheduled job for this email and finalize the send. |
Example | <Envelope> <Body> <CommitScheduledemail> < CONTINUATION _TOKEN>100jhff0jkiydd90u7h65</ CONTINUATION _TOKEN> </CommitScheduledemail> </Body> </Envelope> | |
Response | <RESULT> | |
Elements | SUCCESS | True if successful. |
email_ID | If the request is successful, this element contains the ID for the sent email. | |
Example Success | <Envelope> <Body> <RESULT> <SUCCESS>True</SUCCESS> <email_ID>9700</email_ID> </RESULT> </Body> </Envelope> | |
Error Codes | 100 | You did not provide a required field. |
188 | A token is invalid or has expired. | |
145 | A user session is invalid or has expired. | |
Example Failure | <Envelope> <Body> <RESULT> <SUCCESS>False</SUCCESS> </RESULT> <Fault> <Request/> <FaultCode/> <FaultString>Token is invalid or has expired</FaultString> <detail> <error> <errorid>xxx</errorid> <module/> <class>SP.API</class> <method/> </error> </detail> </Fault> </Body> </Envelope> |