fastify-xemail

contacts-search

Search for a SendGrid Marketing contact by email address.

searchContact

Search for a contact in SendGrid Marketing by email address. Returns the full contact object if found, or { found: false } if not.

Signature

fastify.xEmail.searchContact(
  email: string
): Promise<{ found: boolean; contact?: object }>

Params

Name	Type	Required	Description
`email`	`string`	Yes	Email address to search for.

Returns

Promise<{ found: boolean; contact?: object }>

Property	Type	Description
`found`	`boolean`	`true` if a contact with the email exists in SendGrid Marketing.
`contact`	`object`	Full SendGrid contact object (present only when `found` is `true`).

Throws

[xEmail] 'email' (string) is required for searchContact().
[xEmail] Failed to search contact: <reason> — SendGrid API error.

Examples

Basic — check before adding

fastify.post("/newsletter/subscribe", async (request, reply) => {
  const { email } = request.body;

  const existing = await fastify.xEmail.searchContact(email);

  if (existing.found) {
    return reply.code(409).send({ error: "Already subscribed" });
  }

  await fastify.xEmail.addContact(email, {}, [process.env.LIST_ID]);
  return { subscribed: true };
});

Realistic — look up contact before unsubscribe

fastify.delete("/newsletter/unsubscribe", async (request, reply) => {
  const { email } = request.body;

  const result = await fastify.xEmail.searchContact(email);

  if (!result.found) {
    return reply.code(404).send({ error: "Contact not found" });
  }

  await fastify.xEmail.deleteContact(result.contact.id);

  return { unsubscribed: true };
});

AI Context

package: "@xenterprises/fastify-xemail"
method: fastify.xEmail.contactsSearch(email)
use-when: Search for a marketing contact by email address
params: email (string)
returns: Promise<contact object | null>

Edit this pageorReport an issue

contacts-delete

Delete a SendGrid Marketing contact by ID.

lists-create

Create a new SendGrid Marketing contact list.