fastify-x-twilio

email.validate / email.addContact / email.searchContact / email.deleteContact / email.createList / email.getLists / email.deleteList

Validate email addresses and manage SendGrid marketing contacts and lists.

email.validate / addContact / searchContact / deleteContact / createList / getLists / deleteList

SendGrid contact management and email validation via the SendGrid Marketing API. Validate addresses before sending, maintain suppression lists, and organize contacts into groups.

Signatures

fastify.email.validate(email: string): Promise<{
  email: string;
  valid: boolean;
  verdict: string;
  score: number;
  result: object;
  error?: string;
}>

fastify.email.addContact(
  email: string,
  data?: { firstName?: string; lastName?: string; customFields?: Record<string, unknown> },
  listIds?: string[]
): Promise<{ success: boolean; jobId: string; email: string }>

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

fastify.email.deleteContact(contactId: string): Promise<boolean>

fastify.email.createList(name: string): Promise<{ success: boolean; list: object }>

fastify.email.getLists(): Promise<object[]>

fastify.email.deleteList(listId: string): Promise<boolean>

Params

validate

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

addContact

Name	Type	Required	Description
`email`	`string`	Yes	Contact email address.
`data.firstName`	`string`	No	Contact first name.
`data.lastName`	`string`	No	Contact last name.
`data.customFields`	`object`	No	Custom field key-value pairs.
`listIds`	`string[]`	No	SendGrid list IDs to add the contact to.

searchContact / deleteContact

Name	Type	Required	Description
`email`	`string`	Yes (search)	Email address to look up.
`contactId`	`string`	Yes (delete)	SendGrid contact ID (from `searchContact` or addContact job).

createList / deleteList

Name	Type	Required	Description
`name`	`string`	Yes (create)	Display name for the new list.
`listId`	`string`	Yes (delete)	SendGrid list ID.

Returns

validate

Field	Type	Description
`email`	`string`	The validated email address.
`valid`	`boolean`	`true` if verdict is `"Valid"`.
`verdict`	`string`	SendGrid verdict: `"Valid"`, `"Invalid"`, `"Risky"`.
`score`	`number`	Confidence score (0-1).
`result`	`object`	Full SendGrid validation result.
`error`	`string`	Only present if the validation call itself failed.

addContact

Field	Type	Description
`success`	`boolean`	`true` if the upsert job was accepted.
`jobId`	`string`	Async job ID (contacts may take seconds to appear).
`email`	`string`	The email added.

searchContact

Field	Type	Description
`found`	`boolean`	Whether the contact exists.
`contact`	`object`	The contact object if found.

Examples

validate — pre-flight check before sending

const result = await fastify.email.validate("user@example.com");

if (!result.valid) {
  throw new Error(`Email ${result.email} failed validation: ${result.verdict}`);
}

addContact — add a new subscriber

const lists = await fastify.email.getLists();
const newsletterList = lists.find((l) => l.name === "Newsletter");

await fastify.email.addContact(
  "subscriber@example.com",
  { firstName: "Alice", lastName: "Smith" },
  [newsletterList.id]
);

const { found, contact } = await fastify.email.searchContact("user@example.com");

if (found) {
  await fastify.email.deleteContact(contact.id);
}

createList + deleteList — manage segments

const { list } = await fastify.email.createList("Q1 2026 Campaign");
console.log(list.id); // use to add contacts

// After campaign ends:
await fastify.email.deleteList(list.id);

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

  const validation = await fastify.email.validate(email);
  if (!validation.valid) {
    return reply.code(400).send({ error: "Invalid email address" });
  }

  const lists = await fastify.email.getLists();
  const mainList = lists.find((l) => l.name === "Main Newsletter");

  await fastify.email.addContact(email, { firstName }, [mainList.id]);

  await fastify.email.sendTemplate(
    email,
    "Welcome to our newsletter!",
    process.env.WELCOME_TEMPLATE_ID,
    { firstName }
  );

  return reply.send({ subscribed: true });
});

Throws

[xTwilio] email.validate: email (string) is required
[xTwilio] email.addContact: email (string) is required
[xTwilio] email.searchContact: email (string) is required
[xTwilio] email.deleteContact: contactId (string) is required
[xTwilio] email.createList: name (string) is required
[xTwilio] email.deleteList: listId (string) is required
[xTwilio] Failed to add contact: <message> — SendGrid API error

AI Context

package: "@xenterprises/fastify-xtwilio"
decorator: fastify.email
methods: validate, addContact, searchContact, deleteContact, createList, getLists, deleteList
use-when: SendGrid Marketing contact and list management through the xTwilio plugin

Edit this pageorReport an issue

conversations.*

Manage Twilio Conversations — create threads, add participants, send messages, and configure webhooks.

email.send / email.sendTemplate / email.sendWithAttachments / email.sendBulk / email.sendPersonalizedBulk

Send transactional emails via SendGrid — plain HTML, dynamic templates, attachments, and bulk campaigns.