Normalize Email
identity.normalize_email
Overview
You send an email and we return a normalized form for comparison — trimming whitespace, lowercasing the domain, IDNA-normalizing internationalized domains, and optional Gmail dot/plus folding only in provider_aware mode for recognized Gmail domains (always with a warning). We never assume provider rules for arbitrary domains and never silently merge distinct addresses. Do not use this to verify deliverability or confirm a mailbox exists.
Over-eager normalization is how two different people end up sharing one account. Stripping dots is right for Gmail and wrong almost everywhere else, so we only do it for the two domains where it holds, and we tell you when we did.
Reliability
Same address and same options, same result every time, and running the output through us again changes nothing. Nothing here touches the network, so a normalized address says nothing about whether mail will arrive. An address we cannot make sense of still comes back as a success — with the input echoed and an INVALID_SYNTAX, MULTIPLE_AT or IDNA_ERROR entry in warnings — so read warnings rather than expecting an error. Be careful with provider_aware: folding is irreversible, so keep the original if you may need to mail the address back. We reject the call outright when email is missing, is not a string, or is longer than 1024 characters, when mode is not one of syntax_only, conservative or provider_aware, or when one of the boolean options is not a boolean; retrying the same payload will not help.
Context footprint
Single call replaces ad-hoc string munging with explicit warnings. A successful call costs 1 execution credit.
When to use it
When you need a stable comparison key for addresses you already hold, before storing, matching or de-duplicating them.
When you need to know whether the mailbox exists or accepts mail, or when you only want a syntax verdict and no rewriting.
Scope
Non-goals
- Does not verify deliverability or MX records
- Does not assume provider rules for arbitrary domains
- Does not confirm mailbox ownership
Properties
Capabilities
Cost & billing
Flat rate per invocation
File handling
How we handle your data
What this means
This skill may receive sensitive content and may return submitted, transformed, extracted, or reformatted content.
Squillify guarantees
- Runs inside Squillify
- This skill runs inside Squillify.
- Payloads are not sent to an external service by this skill.
- Squillify does not permanently store submitted payloads.
- Telemetry records metadata only, not submitted content.
- Submitted payloads are not used for training.
- Submitted payloads are not reviewed by humans.
- This skill does not target sensitive data.
- The response may contain submitted or transformed content.
Your responsibility
Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.
Input schema
| Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Email address to normalize. | |
| mode | string | No | Normalization mode; omit it for conservative. |
| lowercaseDomain | boolean | No | Whether the domain is lower-cased; omit it for true. |
| lowercaseLocalPart | boolean | No | Whether the local part is lower-cased; omit it for false. |
| trimWhitespace | boolean | No | Whether surrounding whitespace is removed; omit it for true. |
| idnaDomain | boolean | No | Whether domains are converted to Punycode; omit it for true. |
Output schema
| Field | Type | Required | Description |
|---|---|---|---|
| original | string | Yes | Exact submitted email address. |
| normalized | string | Yes | Normalized email component. |
| changed | boolean | Yes | Whether normalization changed the input. |
| localPart | string | No | Normalized email component. |
| domain | string | No | Normalized email component. |
| asciiDomain | string | No | Normalized email component. |
| warnings | array | Yes | From 0 through 4 bounded normalization warnings, each a closed code and a safe message. |
API contract
POST /v1/executecurl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"identity.normalize_email","input":{"email":"[email protected]"}}'import { Squillify } from "@squillify/sdk";
const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });
const { output } = await sq.execute("identity.normalize_email", {"email":"[email protected]"});Errors
| Code | HTTP | Retryable | Description |
|---|---|---|---|
| VALIDATION_ERROR | 400 | No | The request payload failed schema validation. |
| UNAUTHORIZED | 401 | No | Missing or invalid API key. |
| SKILL_NOT_ACCESSIBLE | 403 | No | The API key is not granted access to this skill. |
| SKILL_NOT_AVAILABLE_FOR_PLAN | 403 | No | This skill is not included in your current plan. |
| PLAN_ELIGIBILITY_UNAVAILABLE | 503 | Yes | Plan eligibility could not be decided. Retry after backoff. |
| SKILL_NOT_FOUND | 404 | No | The requested skill or version does not exist. |
| TENANT_RATE_LIMITED | 429 | Yes | Request rate limit exceeded. Retry after backoff. |
| QUOTA_EXCEEDED | 429 | Yes | Plan quota exhausted. Retryable once the quota period resets. |
| EXECUTION_TIMEOUT | 504 | Yes | Execution exceeded the allowed time budget. |
Other limits
| Limit | Value |
|---|---|
| Recommended inline bytes | 32 KiB |
Limitations
- Does not verify deliverability or MX records
- Does not assume provider rules for arbitrary domains
- Does not confirm mailbox ownership
- Confirming an address is real (requires network)
- Assuming all providers behave like Gmail
- Syntax validation without normalization (use identity.validate_email_syntax)
How to call
POST /v1/execute (requires authentication)
{
"skillKey": "identity.normalize_email",
"input": {
"email": "[email protected]"
}
}Examples
Lowercase the domain only — conservative default
{
"email": "[email protected]"
}{
"asciiDomain": "example.com",
"changed": true,
"domain": "example.com",
"normalized": "[email protected]",
"original": "[email protected]",
"localPart": "User",
"warnings": []
}Gmail dot and plus-tag folding in provider_aware mode
{
"mode": "provider_aware",
"email": "[email protected]"
}{
"asciiDomain": "gmail.com",
"changed": true,
"domain": "gmail.com",
"normalized": "[email protected]",
"original": "[email protected]",
"localPart": "john",
"warnings": [
{
"message": "Applied Gmail-specific dot/plus folding to the local part.",
"code": "PROVIDER_NORMALIZATION"
}
]
}Recommended use cases
- Compare or deduplicate email addresses before you store them
- Canonicalize domain casing on signup forms
- Fold Gmail dot/plus aliases when you explicitly opt into provider_aware mode
Avoid for
- Confirming an address is real (requires network)
- Assuming all providers behave like Gmail
- Syntax validation without normalization (use identity.validate_email_syntax)
Related skills
Composable with
Safety & privacy
- Runs without calling any external service.
- Your payloads are never stored permanently.
- Telemetry captures metadata only — never your payload contents.
- We never train models on your payloads.
- No human reviews your payloads.