who has opened a marketing email via API

[juanrobcn11]

I would like to know if it is possible to extract the information of who has opened a marketing email and how many times he has opened it via API

[IsaacTakushi · Accepted solution]

Hi, @juanrobcn11.

Apologies for the delayed response.

Happy to clarify further:

1. Could you share the IDs of some marketing emails showing empty mailingListsIncluded arrays? Besides the Get email events endpoint, I don't know of another way to see recipient emails.
2. Correct. The Get email events endpoint returns all email events and doesn't provide meta data on the count of each event type (SENT, OPEN, CLICK, etc.). To my knowledge, integrations aggregate and count these events.
3. Yes. Per item 2, the raw CLICK events are returned from the Get email events endpoint, but you must count them on your end.

[Mulan · Accepted solution]

Hi, @haseeb,

1. My first step was the same as your "here" link, getting all marketing emails. 

2. Based on the selected marketing email and as Isaac suggested, I identified all the associated campaignIds (an array of email events associated with a particular marketing email - there can be multiple campaignIds (email events), as the same marketing email may be sent at different times to different recipients/recipient lists).  I learned that from Isaac above.

3.  Once I had the campaignIds, I used this link, using the campaignIds I collected in step 2 (see line 33 of the example code).  The response JSON provided me and array of "events" objects including all the "recipients" and their "types" (e.g. DELIVERED, OPEN, etc).

Since you are just looking for those recipients who opened the email, you should be able to filter on "type: OPEN" to get the list of recipients who have opened your marketing email.  This approach might be a little simpler/shorter than the approach you suggested.

Good luck!

Mulan

[haseeb]

Hi, I have a similar question.

I want to list all the marketing emails, which I could get from here and based on selected, marketing email, get the stats for it as well as contacts OPENs.

Then using the "id" I could get the Marketing Email data data and using the "primaryEmailCampaignId" and "portalId" I could get email events filtered with "eventType=OPEN" for the campaign.

And you meantioned that there is no way to get distinct recipients, as it returns all the events for recipients. So I'll have to program myself to filter it further? But is there no other way to get distinct contacts because if I have a lot of contacts and they open emails multiple times, that would increase the limit and I'll have to make multiple api calls.

Is this correct and Is there a better way to do it?

[IsaacTakushi]

Hi, @Mulan.

Happy to help. Responding in order again:

1. The v1 Email Events API has a Get email events endpoint (also discussed above) which returns data on marketing email sends, deliveries, opens, and clicks. This endpoint can be filtered by recipient (a contact's email property value) and campaignId, among other fields. Following your proposed workflow, you could grab the contacts' email property values and use them to filter requests to the Get email events endpoint by recipient.
   
   Alternatively, you might consider grabbing the values this endpoint returns in the allEmailCampaignIds array, filtering requests to the Get email events endpoint by campaignId, and looking up contacts by their email last. I personally recommend the second approach since contacts may have been added or removed from the list since the email was sent while starting with campaign IDs and the Get email events endpoint will accurately reflect which records were actually sent emails.
2. My tests support your hypothesis. When marketing emails are sent to individual contact records with the Send to more feature, these contacts are excluded from the mailingListsIncluded array since they are not considered members of a list. With that said, my tests also show these one-off contacts are appended to the last email campaign and are visible by filtering the Get email events endpoint by campaignId (yet another reason to take the second approach above).
3. You're welcome!

Please let me know if I can clarify further.

[Mulan]

Hi, @IsaacTakushi,

Just wanted to follow up and let you know that I got my code working! I went with a slightly modified version of your recommendation above and still need to build in some filtering logic, but all in all I was able to pretty much reproduce all the data that the EXPORT button provides.  Thanks so much for sticking with me (even more so given you aren't even working in the HubSpot Support world anymore)!  

I really appreciate you!

Mulan

[IsaacTakushi]

That's fantastic news, @Mulan! Thanks so much for following up here.

Happy to help!

[Mulan]

Hi, @IsaacTakushi,

Wow, thank you for the answers! Very much appreciated!

1.  The marketing campaigns vs the email campaigns now makes more sense (I didn't realize an emailCampaign was a "send event" of the same Marketing email within a Marketing Campaign). Based on your answers, my thought on workflow might start:

- use this v1 Marketing Email API endpoint to get all the emails ever sent

- user select a specific email for which he/she wants statistics 

- use this v1 Marketing Email API endpoint to then get the mailingListsIncluded array

- use the mailingListsIncluded array in this ContactList API endpoint to get the contactIDs of the contacts to which the marketing email was sent

- [after this I am stuck... how do I go from the knowing the contactIDs to getting the status of the marketing email sent to that contact? (e.g. delivered, opened, clicked, etc.)]

2.  Regarding the mailingListsIncluded array.  Perhaps this array was empty, because the emails to which the Marketing email was sent were not in a specific mailingList, but rather individual email accounts; can you confirm?  If so, how would I go about capturing emails that were sent ad hoc and not part of a mailingList?

3.  I just subscribed to the developer changelog. Thank you for the recommendation!

Thank you,

Mulan

[IsaacTakushi]

Welcome, @juanrobcn11.

Yes, you can use this endpoint to retrieve marketing email events for a given recipient with the recipientquery parameter.

If you're not sure campaign ID to define as the campaignId value, use this endpoint and this endpoint or locate it in the UI on the email's performance page > See details > Internal HubSpot ID. See the attached screenshot.

[juanrobcn11]

Hi @IsaacTakushi and thanks for your answer.

Sorry, I think I haven't explained correctly my question. I don't know the recipient of the marketing email, so I can't write it in the query as a parameter.

What I want is to make a query to which I pass a marketing email and it returns who has opened it and how many times each person has opened it.

 I hope now I have explained myself better.

[IsaacTakushi]

Hi, @juanrobcn11.

Thank you for clarifying. Unfortunately, there is no single endpoint that will return that data.

Instead, you must use multiple endpoints:

1. Use this endpoint to get the high level analytics data for a marketing email.
2. Reference the mailingListsIncluded array for the list IDs to which you sent the email.
3. Use this endpoint to get the contacts in those lists.
4. Query the Get email events endpoint for those contacts.

[juanrobcn11]

Hi @IsaacTakushi 

1. When I use the first endpoint, the mailingListsIncluded field returns empty for some emails. Is there any other way to know people who received that email?

2. The query get email events doesn't return a field with the number of times that person has opened the email. How do you know the number?

3. Additionaly, I want to know also how many clicks has that person done in that email. Is it possible to know it?

[IsaacTakushi · Accepted solution]

Hi, @juanrobcn11.

Apologies for the delayed response.

Happy to clarify further:

1. Could you share the IDs of some marketing emails showing empty mailingListsIncluded arrays? Besides the Get email events endpoint, I don't know of another way to see recipient emails.
2. Correct. The Get email events endpoint returns all email events and doesn't provide meta data on the count of each event type (SENT, OPEN, CLICK, etc.). To my knowledge, integrations aggregate and count these events.
3. Yes. Per item 2, the raw CLICK events are returned from the Get email events endpoint, but you must count them on your end.

[Mulan]

Hi, @IsaacTakushi,

I'm doing something similar: trying to get all stats for all email recipients of a particular marketing email.  The "Export" button on the email's performance page provides this information. I would like to pass that data via API to my local app without having to export and upload. I have a few questions, hoping you can assist.

1) in one of your answers above, you ref campaignId = Internal Hubspot ID on the email performance page > see details - why do I see different campaignId's for different emails within the same campaign? Does each Internal HubSpot ID = unique identifier for each marketing email regardless of campaign grouping?

2) I was unable to use Internal HubSpot ID for this endpoint: GET /marketing-emails/v1/emails/with-statistics/:email_id -

How would you recommend I get the correct email_id to start this request? I found the email_id via trial and error (in JSON as "id"), but is there an easier way to get this data?

3) To your request to provide some IDs of marketing emails showing empty mailingListsIncluded arrays: HubSpot Internal IDs: 98134766, 98391486

Each of these emails was sent to 3 recipients, but the mailingListIncluded array returns an empty array.  If the array contained the recipients, I think I can follow the steps you recommended 6/26/2019.

4) Do you have any recommendations on how I might be able to GET the information JSON formatted by the Export button on the email performance page?

Thank you!

Mulan  

[IsaacTakushi]

Hi, @Mulan.

I will try to lend some insight here. With that said, I am no longer on Developer Support so my responses may be delayed.

1. Email "campaigns" actually refer to specific send events. A single marketing email may be sent at different times and thus be associated with more than one email campaign. For example, this v1 Marketing Email API endpoint returns a allEmailCampaignIds array. The Internal HubSpot ID field also lists these email campaign IDs while the ID in the URL is the email ID.  These are both distinct from marketing campaigns, which are found under Marketing > Planning and Strategy > Campaigns (It's far too confusing, I know).
2. Building on the explanation above, that endpoint expects an email ID, which can be found in the email tool's URL or programmatically via this v1 Marketing Email API endpoint.
3. HubSpot email IDs are not unique across all accounts. Which account are you querying?
4. At this time, it is still not possible to programmatically fetch the same email data available via the Export button. While I don't have any recommendations beyond what has been discussed above, a newer version of the Marketing Email API is currently in development and may address some of these use cases. When the new API is released to beta, it will be announced via the developer changelog. I recommend subscribing to be notified.