From d03d544d1b73474f27ec919ce5e23123545eaaa2 Mon Sep 17 00:00:00 2001 From: dq Date: Tue, 22 Sep 2026 16:10:23 +0100 Subject: [PATCH 1/6] Document email_verified on the contact object The contact object now returns whether its email address has been verified. The field was already accepted on contact create and update. --- descriptions/0/api.intercom.io.yaml | 5 +++++ descriptions/2.16/api.intercom.io.yaml | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 9538d528..53329b26 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31289,6 +31289,11 @@ components: type: string description: The contact's email domain. example: example.com + email_verified: + type: boolean + description: Whether the contact's email address has been verified. This + is false if the contact's email has changed since it was last verified. + example: true phone: type: string nullable: true diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 75272ea0..a8066198 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -25293,6 +25293,11 @@ components: type: string description: The contact's email domain. example: example.com + email_verified: + type: boolean + description: Whether the contact's email address has been verified. This + is false if the contact's email has changed since it was last verified. + example: true phone: type: string nullable: true From 99ccbee5dd9682078787ded0a4e3bb8e35d1220b Mon Sep 17 00:00:00 2001 From: dq Date: Tue, 22 Sep 2026 16:41:41 +0100 Subject: [PATCH 2/6] Show the new field in the full-shape contact response examples Only examples that spell out the whole contact object, and the visitor convert endpoint, which returns a contact rather than a visitor. --- descriptions/0/api.intercom.io.yaml | 7 +++++++ descriptions/2.16/api.intercom.io.yaml | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 53329b26..ec50cca7 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -8878,6 +8878,7 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io + email_verified: false phone: formatted_phone: name: joe bloggs @@ -8967,6 +8968,7 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io + email_verified: false phone: formatted_phone: name: joe bloggs @@ -9161,6 +9163,7 @@ paths: external_id: '70' role: user email: joe@bloggs.com + email_verified: false phone: formatted_phone: name: Joe Bloggs @@ -9375,6 +9378,7 @@ paths: external_id: '70' role: user email: joe@bloggs.com + email_verified: false phone: formatted_phone: name: Joe Bloggs @@ -10014,6 +10018,7 @@ paths: external_id: role: user email: joebloggs@intercom.io + email_verified: false phone: formatted_phone: name: @@ -10175,6 +10180,7 @@ paths: external_id: '70' role: user email: joe@bloggs.com + email_verified: false phone: formatted_phone: name: Joe Bloggs @@ -25808,6 +25814,7 @@ paths: external_id: role: user email: foo@bar.com + email_verified: false phone: formatted_phone: name: diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index a8066198..45614d01 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -8070,6 +8070,7 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io + email_verified: false phone: name: joe bloggs avatar: @@ -8158,6 +8159,7 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io + email_verified: false phone: name: joe bloggs avatar: @@ -8351,6 +8353,7 @@ paths: external_id: '70' role: user email: joe@bloggs.com + email_verified: false phone: name: Joe Bloggs avatar: @@ -8558,6 +8561,7 @@ paths: external_id: '70' role: user email: joe@bloggs.com + email_verified: false phone: name: Joe Bloggs avatar: @@ -8983,6 +8987,7 @@ paths: external_id: role: user email: joebloggs@intercom.io + email_verified: false phone: name: avatar: @@ -9143,6 +9148,7 @@ paths: external_id: '70' role: user email: joe@bloggs.com + email_verified: false phone: name: Joe Bloggs avatar: @@ -21547,6 +21553,7 @@ paths: external_id: role: user email: foo@bar.com + email_verified: false phone: name: avatar: From 4ef718dbab4941fe20abb05d201b8c44de6612eb Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 23 Sep 2026 12:59:51 +0100 Subject: [PATCH 3/6] Limit the response field to the Preview description The contact object returns email_verified on Preview only, so the released 2.16 description should not advertise it. --- descriptions/2.16/api.intercom.io.yaml | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 45614d01..75272ea0 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -8070,7 +8070,6 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io - email_verified: false phone: name: joe bloggs avatar: @@ -8159,7 +8158,6 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io - email_verified: false phone: name: joe bloggs avatar: @@ -8353,7 +8351,6 @@ paths: external_id: '70' role: user email: joe@bloggs.com - email_verified: false phone: name: Joe Bloggs avatar: @@ -8561,7 +8558,6 @@ paths: external_id: '70' role: user email: joe@bloggs.com - email_verified: false phone: name: Joe Bloggs avatar: @@ -8987,7 +8983,6 @@ paths: external_id: role: user email: joebloggs@intercom.io - email_verified: false phone: name: avatar: @@ -9148,7 +9143,6 @@ paths: external_id: '70' role: user email: joe@bloggs.com - email_verified: false phone: name: Joe Bloggs avatar: @@ -21553,7 +21547,6 @@ paths: external_id: role: user email: foo@bar.com - email_verified: false phone: name: avatar: @@ -25300,11 +25293,6 @@ components: type: string description: The contact's email domain. example: example.com - email_verified: - type: boolean - description: Whether the contact's email address has been verified. This - is false if the contact's email has changed since it was last verified. - example: true phone: type: string nullable: true From 9a49f3e6b2e2ccfa40f8ce1695a226447db52785 Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 23 Sep 2026 13:28:22 +0100 Subject: [PATCH 4/6] Say what a verified email actually means "Has been verified" read as though we had checked the address ourselves. It can equally be your own assertion, so the description now names both origins and says the field does not distinguish them. --- descriptions/0/api.intercom.io.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index ec50cca7..c378077f 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31298,8 +31298,7 @@ components: example: example.com email_verified: type: boolean - description: Whether the contact's email address has been verified. This - is false if the contact's email has changed since it was last verified. + description: Whether the contact's email address has been verified as belonging to them. Verification can come from either side. You set it yourself when you create or update the contact, or when you identify them to the Messenger or a mobile SDK with a signed identity. Intercom sets it when it sees the contact prove they control the address, such as entering a one-time code sent to it, or emailing in from it with passing sender domain authentication. This field does not say which of those happened, so treat a true value as only as strong as the verification behind it. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. example: true phone: type: string From edcd1abdf373b96bb9be321525d29293d1a342e6 Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 23 Sep 2026 13:30:29 +0100 Subject: [PATCH 5/6] Correct what inbound mail proves about a verified address Mail arriving from an address marks it verified on its own, so the previous wording overstated the evidence by tying it to sender domain authentication. Also names file import, and drops the signed-identity routes, which are not available to every workspace. --- descriptions/0/api.intercom.io.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index c378077f..8dc930f1 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31298,7 +31298,7 @@ components: example: example.com email_verified: type: boolean - description: Whether the contact's email address has been verified as belonging to them. Verification can come from either side. You set it yourself when you create or update the contact, or when you identify them to the Messenger or a mobile SDK with a signed identity. Intercom sets it when it sees the contact prove they control the address, such as entering a one-time code sent to it, or emailing in from it with passing sender domain authentication. This field does not say which of those happened, so treat a true value as only as strong as the verification behind it. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. + description: Whether the contact's email address is marked as verified. This can come from you, by setting email_verified to true when you create or update the contact or by importing the contact from a file, or from Intercom, when the contact confirms the address themselves, such as by entering a one-time code sent to it. Receiving mail from the address can also mark it verified, which is weaker evidence, because it reflects only who the message claimed to be from. The field does not say which route produced it, so treat a true value as a record that the address was verified somewhere rather than as proof the contact owns it. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. example: true phone: type: string From 875cbffcea4f13b77bcc2ee2b7f9ec1ee0ea14b0 Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 23 Sep 2026 13:42:06 +0100 Subject: [PATCH 6/6] Name only the routes that actually set the field The previous wording described routes that are not reachable today, which read as behaviour rather than intent. --- descriptions/0/api.intercom.io.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 8dc930f1..d67a75bb 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31298,7 +31298,7 @@ components: example: example.com email_verified: type: boolean - description: Whether the contact's email address is marked as verified. This can come from you, by setting email_verified to true when you create or update the contact or by importing the contact from a file, or from Intercom, when the contact confirms the address themselves, such as by entering a one-time code sent to it. Receiving mail from the address can also mark it verified, which is weaker evidence, because it reflects only who the message claimed to be from. The field does not say which route produced it, so treat a true value as a record that the address was verified somewhere rather than as proof the contact owns it. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. + description: Whether the contact's email address is marked as verified. It is set when the public API marks it as verified on contact create or update, when the contact is imported from a CSV in the help desk, or when the contact is created from mail arriving from that address. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. example: true phone: type: string