The following API calls are currently available for the EmailMessage Sub-Object:
GET LIST - Get a list of all email messages for the specified survey and survey campaign.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/emailmessage
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
Response Example (.debug format):
Array ( [result_ok] => 1 [total_count] => 2 [page] => 1 [total_pages] => 1 [results_per_page] => 2 [data] => Array ( [0] => Array ( [id] => 128073 [subtype] => message [message_type] => html [medium] => Email [invite_identity] => 94135 [status] => Building [from] => Array ( [email] => surveys@sgizmo.com [name] => Survey Research ) [subject] => Please take a moment to fill out this survey [body] => Array ( [text] => Hi I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes. [invite("survey link")] Thank You! [html] => Hi I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes. [invite("html link"), title="Begin"] Thank You! ) [footer] => This message was sent by [account("physical address")]. To unsubscribe, click below: [invite("unsubscribe link")] [date_created] => 2014-07-29 11:25:54 [date_modified] => 2016-05-24 14:53:33 ) [1] => Array ( [id] => 147089 [subtype] => reminder [message_type] => plaintext [medium] => Email [invite_identity] => 94135 [status] => Building [from] => Array ( [email] => surveys@sgizmo.com [name] => DaveDom ) [subject] => Reminder: Please take a moment to fill out this survey [body] => Array ( [text] => Hi I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes. [invite("survey link")] Thank You! [html] => Hi I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes. [invite("html link"), title="Begin"] Thank You! ) [footer] => This message was sent by [account("physical address")]. To unsubscribe, click below: [invite("unsubscribe link")] [date_created] => 2016-05-31 16:19:38 [date_modified] => 2016-05-31 16:24:08[embed_question] =>[disable_styles] => ) ) )
GET EMAILMESSAGE - Get information about a specific email message within a campaign.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/emailmessage/100000?_method=GET
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
Response Example (.debug format):
Array ( [result_ok] => 1 [data] => Array ( [id] => 128073 [subtype] => message [message_type] => html [medium] => Email [invite_identity] => 94135 [status] => Building [from] => Array ( [email] => surveys@sgizmo.com [name] => Survey Research ) [subject] => Please take our survey [body] => Array ( [text] => Hi I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes. [invite("survey link")] Thank You! [html] => Hi I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes. [invite("html link"), title="Begin"] Thank You! ) [footer] => This message was sent by [account("physical address")]. To unsubscribe, click below: [invite("unsubscribe link")] [date_created] => 2014-07-29 11:25:54 [date_modified] => 2016-05-24 14:53:33[embed_question] =>[disable_styles] =>) )
CREATE EMAILMESSAGE - Create a new email message within a campaign.
When creating campaigns via either the API or the UI, a default message is created. Before creating a message do a quick GET LIST to check for a default Invite Message.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/emailmessage?_method=PUT
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
| subtype | message, reminder | False |
| from[name] | Alchemer | False |
| from[email] | surveys@alchemer.com | False |
| replies | surveys@alchemer.com | False |
| subject | Subject Text | False |
| message_type* | plaintext, html | False |
| body[text] | Body Text | False |
| body[html]† | Body HTML | False |
| send‡ | true | False |
| footer | Footer Text + [account("physical address")] | False |
| embed_question | true/false - Embed first survey question in body of email | False |
| disable_styles | true/false - Disable default email message styles | False |
*All messages created via the API are set to plaintext only. If you use the POST call to change the messagetype to html this will set your email to HTML with plaintext backup.
†Pro tip: If you set the messagetype=html the message will be set to send an html email with a plaintext backup that automatically syncs. This way you only have to specify the HTML body!
‡The send parameter will send the message when the call is made only if set to true. This parameter does not need to be set to false to prevent the message from sending.
Response Example (.debug format):
Array ( [result_ok] => 1 [data] => Array ( [id] => 123456 [type] => EmailMessage [subtype] => reminder [message_type] => plaintext [medium] => Email [invite_identity] => 282478 [status] => Building [from] => Array ( [email] => surveys@sgizmo.com [name] => Survey Research ) [subject] => [Reminder] Help out by taking this survey. [body] => Array ( [text] => Hi I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes. [invite("survey link")] Thank You! [html] => Hi I'm currently running a study. If you don't mind, pelase fill out this survey -- it should only take a few minutes. [invite("html link"), title="Begin"] ) [footer] => This message was sent by [account("physical address")]. To unsubscribe, click below: [invite("unsubscribe link")] [date_created] => 2013-09-01 16:16:58 [date_modified] => 2013-09-01 16:16:58[embed_question] =>[disable_styles] =>) )
UPDATE EMAILMESSAGE - Update a specific email message within a campaign.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/emailmessage/100000?_method=POST
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
| from[name] | Alchemer | False |
| from[email] | surveys@alchemer.com | False |
| replies | surveys@alchemer.com | False |
| subject | Subject Text | False |
| message_type* | plaintext, html | False |
| body[text] | Body Text | False |
| body[html]† | Body HTML | False |
| send‡ | true | False |
| footer | Footer Text + [account("physical address")] | False |
| embed_question | true/false - Embed first survey question in body of email | False |
| disable_styles | true/false - Disable default email message styles | False |
*All messages created via the API are set to plaintext only. If you use the POST call to change the messagetype to html this will set your email to HTML with plaintext backup.
†Pro tip: If you set the messagetype=html the message will be set to send an html email with a plaintext backup that automatically syncs. This way you only have to specify the HTML body!
‡The send parameter will send the message when the call is made only if set to true. This parameter does not need to be set to false to prevent the message from sending.
Response Example (.debug format):
Array ( [result_ok] => 1 [data] => Array ( [id] => 467633 [type] => EmailMessage [subtype] => reminder [message_type] => plaintext [medium] => Email [invite_identity] => 282478 [status] => Building [from] => Array ( [email] => surveys@sgizmo.com [name] => Survey Research ) [subject] => [Reminder] Help out by taking this survey. [body] => Array ( [text] => Hi I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes. [invite("survey link")] Thank You! [html] => ) [footer] => This message was sent by [account("physical address")]. To unsubscribe, click below: [invite("unsubscribe link")] [date_created] => 2013-09-01 16:16:58 [date_modified] => 2013-09-01 16:25:39[embed_question] =>[disable_styles] =>) )
Additional Notes on Reminder and Thank You Emails
Reminder emails
Scheduled reminders: Reminder emails with a defined schedule in the Alchemer UI (e.g., send 1 day after previous email) cannot be triggered via API.
Mixed campaigns: If a campaign includes at least one scheduled reminder email that has not yet been sent, unscheduled reminders in that campaign also cannot be sent via API.
Unscheduled reminders: Reminder emails without a schedule generally work as expected when triggered via API, as long as no scheduled reminders are present.
Thank you emails
Using the Update Campaign Email endpoint (POST surveycampaign/{campaign_id}/emailmessage with send=true) will send Thank You emails to respondents who:
Have completed the survey, and
Have not already received the Thank You email.
Example behavior:
Respondent 1: Completed previously and already received the Thank You → does not receive another.
Respondent 2: Newly added, completed the survey → receives the Thank You as expected.
Respondent 3: Newly added, did not complete the survey → does not receive the Thank You.
DELETE EMAILMESSAGE - Delete a specific email message from a campaign.
https://api.alchemer.com/v5/survey/123456/surveycampaign/100000/emailmessage/100000?_method=DELETE
| Parameters | Example | Required |
|---|---|---|
| Authentication Credentials | api_token=abcd12345&api_token_secret=abcd12345 | True |
Response Example (.debug format):
Array
(
[result_ok] => 1
)