Automating campaign with personalised emails and leads

[MariaT]

We have an external application that prepares highly personalized outbound email campaigns, and we want Marketo to own the actual sending and reporting. We want to use the REST API where it’s supported.

What our external app does

• Builds a campaign:

  • One logical “campaign” in our system.

  • A list of contacts/leads (with identifiers we can map to Marketo).

  • A base email template with placeholders (name, custom text, etc.).

  • Per-recipient personalized values for those placeholders (each contact gets its own content).

• For each campaign:

  • We can create/update leads.

  • We can decide who should be included in this specific blast.

  • We can generate personalised variables  for each lead that could be mapped to Marketo fields / custom objects / My Tokens.

• then, we want to go into the Marketo UI, open the Program/Smart Campaign created for that campaign, review:

  • The audience (who is going to receive the email).

  • The email content (already personalized via tokens / Velocity / custom fields).

• Then manually trigger the send from within Marketo (e.g., run the batch Smart Campaign, schedule it, etc.), so the final send is initiated and controlled from the Marketo UI, not from our app.
  
  
  We are looking for the recommended Marketo API pattern to implement this flow: which assets to prebuild manually, which assets to clone or update via API, and how best to structure personalization (fields vs. custom objects vs. My Tokens/Velocity) so that a Marketo user can still inspect the campaign and trigger the batch send from the UI.
  
  Do you know what is the way to achieve this?

[SanfordWhiteman]

A few important questions:

1. Your app is generating the entire HTML (and presumably text) body of the email?

2. What is the max number of personalization fields you'll be using, say to the nearest 20? (Across all such emails and leads.)

3. What are the datatypes of the fields (Boolean, Number, String w/max length)?

4. Which of those field values will be provided by your app at runtime vs. picked up from the current Marketo db value?

5. How often will new campaigns & emails be generated?

6. What is the max # of such emails a single lead will get in a year?

[MariaT]

---

Thank you for your reply! Answers to your questions below.

@SanfordWhiteman wrote:

A few important questions:

1. Your app is generating the entire HTML (and presumably text) body of the email? Yes, our app generates the entire HTML including any placeholders for lead fields

2. What is the max number of personalization fields you'll be using, say to the nearest 20? (Across all such emails and leads.) It really depends on the campaign, but lets say on average 20 per email/lead

3. What are the datatypes of the fields (Boolean, Number, String w/max length)? The datatypes are almost entirely String data types, the strings may contain html content. We may have some Datetime fields

4. Which of those field values will be provided by your app at runtime vs. picked up from the current Marketo db value? The intent is that all of the field values come from Marketo values that we have updated for the lead.

5. How often will new campaigns & emails be generated?  This will be customer dependent.

6. What is the max # of such emails a single lead will get in a year? Customer dependent on how often they wish to target their leads.

---

[SanfordWhiteman]

OK. Some of those answers are rather open-ended but the general architecture would be like so:

• Create a “shell” Program that you will later clone using the API. This shell program has placeholders for your smart campaigns, assets, and lists but must otherwise be left empty.
• In the shell program, create an Email asset and break it from its template. You will be replacing the entire HTML via the API, so it must not have a template connection. This disconnection itself cannot be done via the API.
• For any client campaign, clone the shell Program using the Clone Program API.
• Use the Email Full Content API to replace the email content.
• Use the Bulk Import API to import leads into the primary list in the cloned Program with their latest values; note you must wait for the import to be successfully completed, not just queued, before proceeding.
• Proceed to run the appropriate smart campaign via the UI (or schedule the program, if you’ve chosen to use an Email type program).

I would not embark on this build unless you have an experienced Marketo developer involved. It’s not for the faint of experience!

[MariaT]

Hi, thank you for your reply. I think the solution you propose is roughly along the lines what I have come up in the end. So I do need a "template" program to clone. 
" create an Email asset and break it from its template" - what do you mean by that? When I tried creating an email without template and then tried this endpoint: 

POST /rest/asset/v1/email/{id}/content/{htmlId}.json

I  got an error (something like "you can only update email based on a template"). Did you mean some other API? I was actually able to replace the only content section in that email based on a template via API. But I may be missing something, what is the downside of this solution? 
"Use the Bulk Import API to import leads into the primary list in the cloned Program with their latest values; note you must wait for the import to be successfully completed, not just queued, before proceeding." - this is super valuable advise, I was trying to use just regular create leads endpoint, bulk import makes much more sense in this case

Thank you again and please let me know about the email templates problem - I'm curious what am I getting wrong here.

[SanfordWhiteman]

---

When I tried creating an email without template and then tried this endpoint: 

POST /rest/asset/v1/email/{id}/content/{htmlId}.json

You want the fullContent.json endpoint.