Email Alias API Python Tutorial: Provision Aliases in Minutes Email Alias API Python 教程：几分钟内批量创建邮箱别名
Email aliases are the backbone of modern email management. Whether you are a QA engineer spinning up test accounts or a SaaS builder managing customer support, you need to create and delete aliases fast. Doing it manually through a dashboard is slow and error prone. That is where an email alias API comes in.
In this tutorial, you will learn how to use the GridInbox API with Python to provision email aliases in minutes. You will build a reusable Python client, automate alias creation for QA workflows, and explore real world use cases. By the end, you will have a working script that can create, list, and delete aliases programmatically.
An email alias API lets you create and manage email aliases programmatically through HTTP requests instead of a web dashboard.
Email Alias API: A RESTful interface that allows developers to create, update, list, and delete email aliases using standard HTTP methods like POST, GET, and DELETE.
GridInbox exposes a REST API that works with any email provider including AWS SES and Cloudflare Email Routing. Every alias you create can send and receive email bidirectionally, and you can attach custom domains. For Python developers, this means you can write a few lines of code and provision hundreds of aliases in seconds.
Why automate email aliases with Python?
Manual alias management breaks down at scale. A typical SaaS company might need 50 to 200 test aliases per QA cycle. A customer support team could rotate through 30 shared inbox aliases per week. Doing that by hand takes hours and introduces typos. Python combined with a reliable email alias API reduces that time to under 60 seconds.
Before writing any code, you need a GridInbox account, an API key, and Python 3.8 or higher installed on your machine.
Start by signing up for GridInbox. Once logged in, navigate to the API Keys section and generate a new key. Copy the key and store it securely. You will also need your GridInbox workspace ID, which you can find in your account settings.
Create a new directory for this project and set up a virtual environment:
mkdir email-alias-api-tutorial
cd email-alias-api-tutorial
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activateInstall the requests library, which we will use to call the GridInbox API:
pip install requestsCreate a file named gridinbox_client.py and add your credentials at the top:
import requests
import json
API_KEY = "your-api-key-here"
WORKSPACE_ID = "your-workspace-id"
BASE_URL = "https://api.gridinbox.com/v1"Keep your API key out of version control. Use environment variables or a .env file in production.
Building a Python client for the GridInbox email alias API requires only the requests library and three core functions.
We will create three functions: create_alias, list_aliases, and delete_alias. Each function will handle authentication and error checking.
Function 1: Create an alias
The create_alias function sends a POST request to the /aliases endpoint. You must specify the alias email prefix, the target email address (where mail is forwarded), and optionally a custom domain.
def create_alias(prefix, target_email, domain=None):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/aliases"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"alias_prefix": prefix,
"target_email": target_email,
"domain": domain # None defaults to gridinbox.app
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 201:
return response.json()
else:
raise Exception(f"Create alias failed: {response.status_code} {response.text}")To create an alias, call the function like this:
new_alias = create_alias("qa-test-42", "[email protected]")
print(new_alias["alias_email"]) # [email protected]GridInbox returns the full alias email address, which you can use immediately for sending and receiving.
Function 2: List all aliases
Listing aliases is useful for auditing or building a management dashboard. The GET endpoint returns a paginated list.
def list_aliases(page=1, per_page=50):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/aliases"
headers = {"Authorization": f"Bearer {API_KEY}"}
params = {"page": page, "per_page": per_page}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
return response.json()
else:
raise Exception(f"List aliases failed: {response.status_code} {response.text}")Iterate through the results to find a specific alias or count total aliases:
aliases = list_aliases()
print(f"Total aliases: {aliases['total']}")
for alias in aliases['data']:
print(alias['alias_email'])Function 3: Delete an alias
Cleanup is critical in automated workflows. The delete function removes an alias by its ID.
def delete_alias(alias_id):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/aliases/{alias_id}"
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.delete(url, headers=headers)
if response.status_code == 204:
return True
else:
raise Exception(f"Delete alias failed: {response.status_code} {response.text}")Call it with the alias ID from a create or list response:
delete_alias(new_alias['id'])QA teams can use the email alias API with Python to provision disposable test accounts for each test run, reducing setup time by 80%.
Manual QA often requires creating email accounts for signup flows, password resets, and notification testing. With GridInbox and Python, you can automate the entire cycle.
Scenario: Testing a signup flow
Suppose your app sends a verification email after registration. You need a fresh email alias for each test. Here is a complete script that creates an alias, waits for the email, and then deletes it.
import time
import uuid
# Generate a unique prefix
test_id = str(uuid.uuid4())[:8]
prefix = f"test-signup-{test_id}"
# Create alias
alias = create_alias(prefix, "[email protected]")
print(f"Created alias: {alias['alias_email']}")
# Simulate test: trigger signup in your app, then check inbox
# (GridInbox API also provides email retrieval)
time.sleep(5)
# Clean up
delete_alias(alias['id'])
print("Alias deleted.")This pattern works for any workflow that requires a unique email address per test run. In a CI/CD pipeline, you can run this script before your test suite and tear down aliases afterward.
Real numbers from a production deployment
A QA team at a mid-size SaaS company using GridInbox reported that they reduced alias provisioning time from 3 minutes per alias to under 2 seconds. Over a quarter with 2,000 test runs, that saved 95 hours of manual work.
Build internal tools and agent workflows with the GridInbox email alias API by creating shared inbox aliases that route to multiple team members.
GridInbox supports team shared inboxes with role based access control (RBAC). You can create an alias that forwards to a group of people, then manage permissions through the API.
Creating a shared inbox alias
To create a shared inbox, you specify multiple target emails in the payload:
def create_shared_inbox(prefix, target_emails, domain=None):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/shared-inboxes"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"alias_prefix": prefix,
"members": target_emails,
"domain": domain
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 201:
return response.json()
else:
raise Exception(f"Create shared inbox failed: {response.status_code} {response.text}")Call it with a list of team emails:
shared = create_shared_inbox(
"support-team",
["[email protected]", "[email protected]", "[email protected]"]
)
print(f"Shared inbox created: {shared['alias_email']}")Agent workflow automation
For customer support agents, you can programmatically assign aliases based on ticket severity. For example, create a dedicated alias for a critical issue and route it to senior agents only. Use the API to change the member list in real time.
def update_shared_inbox(inbox_id, new_members):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/shared-inboxes/{inbox_id}"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {"members": new_members}
response = requests.patch(url, headers=headers, json=payload)
if response.status_code == 200:
return response.json()
else:
raise Exception(f"Update failed: {response.status_code} {response.text}")This pattern is used by operations teams to dynamically route emails during incidents or high volume periods.
When using the GridInbox email alias API with Python, respect rate limits, handle errors gracefully, and store API keys securely.
GridInbox enforces a rate limit of 100 requests per minute per API key. Exceeding this returns a 429 status code. Implement exponential backoff in your client.
import time
def api_call_with_retry(func, *args, max_retries=3):
for attempt in range(max_retries):
try:
return func(*args)
except Exception as e:
if "429" in str(e) and attempt < max_retries - 1:
wait = 2 ** attempt
time.sleep(wait)
else:
raiseAlways validate alias prefixes. GridInbox accepts lowercase alphanumeric characters and hyphens. Prefixes must be between 3 and 64 characters long.
Store your API key in an environment variable:
import os
API_KEY = os.environ.get("GRIDINBOX_API_KEY")Never commit API keys to a public repository. Use a .gitignore file to exclude .env files.
Most issues with the email alias API in Python stem from incorrect authentication, invalid payloads, or hitting rate limits.
If you get a 401 Unauthorized error, double check that your API key is correct and that it has not expired. If you see a 422 Unprocessable Entity, inspect your payload for missing or malformed fields. A 429 Too Many Requests means you need to slow down.
GridInbox returns detailed error messages in the response body. Always log the full response when debugging:
response = requests.post(url, headers=headers, json=payload)
if not response.ok:
print(f"Error {response.status_code}: {response.text}")After mastering the basics, integrate the GridInbox email alias API with your CI/CD pipeline, monitoring tools, or customer onboarding flow.
Use the API to automatically create aliases when a new customer signs up. For example, generate a dedicated alias for each customer support ticket. Or build a Slack bot that calls the API to create aliases on demand.
GridInbox works with AWS SES and Cloudflare Email Routing, so you can route email through your existing infrastructure. The API also supports webhooks for real time notifications when an alias receives email.
For advanced use cases, explore the GridInbox documentation for bulk alias creation, domain management, and audit logs. The Python client you built today is a solid foundation for any automation project.
Frequently Asked Questions
How do I create an email alias using Python?
Use the GridInbox API with the requests library. Send a POST request to the /aliases endpoint with your API key, a unique prefix, and a target email address. The response contains the full alias email.
What is the best email alias API for Python developers?
GridInbox is the best option because it offers bidirectional aliases, custom domain support, team shared inboxes with RBAC, and a simple REST API that works with Python in under 10 lines of code.
Can I automate email alias creation for QA testing?
Yes. Use the GridInbox API to create a unique alias before each test run and delete it after. This eliminates manual setup and reduces provisioning time from minutes to seconds.
How do I delete an email alias with the API?
Send a DELETE request to the /aliases/{alias_id} endpoint with your API key. The alias is removed immediately and cannot be recovered.
What are the rate limits for the GridInbox email alias API?
GridInbox allows 100 requests per minute per API key. If you exceed this, you receive a 429 status code and should implement exponential backoff in your code.
Can I use the email alias API with AWS SES or Cloudflare Email Routing?
Yes. GridInbox works seamlessly with AWS SES and Cloudflare Email Routing. You can configure routing rules in your GridInbox dashboard and manage aliases through the API.
邮箱别名是现代邮件管理的基石。无论是 QA 工程师快速创建测试账号，还是 SaaS 构建者管理客户支持，你都需要快速创建和删除别名。通过仪表盘手动操作既慢又容易出错。这正是 Email Alias API 的用武之地。
在本教程中，你将学习如何使用 GridInbox API 配合 Python 在几分钟内批量创建邮箱别名。你将构建一个可复用的 Python 客户端，自动化 QA 工作流中的别名创建，并探索真实应用场景。最终，你将拥有一个能通过编程方式创建、列出和删除别名的可用脚本。
Email Alias API 让你通过 HTTP 请求以编程方式创建和管理邮箱别名，无需使用网页仪表盘。
Email Alias API：一个 RESTful 接口，允许开发者使用 POST、GET 和 DELETE 等标准 HTTP 方法创建、更新、列出和删除邮箱别名。
GridInbox 提供了一个 REST API，可与任何邮件提供商（包括 AWS SES 和 Cloudflare Email Routing）配合使用。你创建的每个别名都可以双向收发邮件，并且可以绑定自定义域名。对于 Python 开发者来说，这意味着只需几行代码就能在几秒内创建数百个别名。
为什么用 Python 自动化邮箱别名？
手动管理别名在规模化时会崩溃。一家典型的 SaaS 公司每个 QA 周期可能需要 50 到 200 个测试别名。客户支持团队每周可能轮换 30 个共享收件箱别名。手动操作需要数小时且容易出错。Python 结合可靠的 Email Alias API 可将时间缩短至 60 秒以内。
在编写代码之前，你需要一个 GridInbox 账户、一个 API 密钥，以及安装 Python 3.8 或更高版本。
首先注册 GridInbox。登录后，导航到 API Keys 部分并生成一个新密钥。复制密钥并安全存储。你还需要 GridInbox 工作区 ID，可在账户设置中找到。
为此项目创建一个新目录并设置虚拟环境：
mkdir email-alias-api-tutorial
cd email-alias-api-tutorial
python -m venv venv
source venv/bin/activate # Windows 上: venv\Scripts\activate安装 requests 库，我们将用它来调用 GridInbox API：
pip install requests创建一个名为 gridinbox_client.py 的文件，并在顶部添加你的凭据：
import requests
import json
API_KEY = "your-api-key-here"
WORKSPACE_ID = "your-workspace-id"
BASE_URL = "https://api.gridinbox.com/v1"将 API 密钥排除在版本控制之外。在生产环境中使用环境变量或 .env 文件。
构建 GridInbox Email Alias API 的 Python 客户端只需 requests 库和三个核心函数。
我们将创建三个函数：create_alias、list_aliases 和 delete_alias。每个函数都会处理身份验证和错误检查。
函数 1：创建别名
create_alias 函数向 /aliases 端点发送 POST 请求。你必须指定别名邮箱前缀、目标邮箱地址（邮件转发地址），以及可选的自定义域名。
def create_alias(prefix, target_email, domain=None):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/aliases"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"alias_prefix": prefix,
"target_email": target_email,
"domain": domain # None 默认为 gridinbox.app
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 201:
return response.json()
else:
raise Exception(f"创建别名失败: {response.status_code} {response.text}")像这样调用函数来创建别名：
new_alias = create_alias("qa-test-42", "[email protected]")
print(new_alias["alias_email"]) # [email protected]GridInbox 返回完整的别名邮箱地址，你可以立即用于收发邮件。
函数 2：列出所有别名
列出别名对于审计或构建管理仪表盘非常有用。GET 端点返回分页列表。
def list_aliases(page=1, per_page=50):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/aliases"
headers = {"Authorization": f"Bearer {API_KEY}"}
params = {"page": page, "per_page": per_page}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
return response.json()
else:
raise Exception(f"列出别名失败: {response.status_code} {response.text}")遍历结果以查找特定别名或统计别名总数：
aliases = list_aliases()
print(f"别名总数: {aliases['total']}")
for alias in aliases['data']:
print(alias['alias_email'])函数 3：删除别名
清理工作在自动化工作流中至关重要。删除函数通过别名 ID 移除别名。
def delete_alias(alias_id):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/aliases/{alias_id}"
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.delete(url, headers=headers)
if response.status_code == 204:
return True
else:
raise Exception(f"删除别名失败: {response.status_code} {response.text}")使用创建或列出响应中的别名 ID 调用它：
delete_alias(new_alias['id'])QA 团队可以使用 Email Alias API 配合 Python 为每次测试运行配置一次性测试账号，将设置时间减少 80%。
手动 QA 通常需要为注册流程、密码重置和通知测试创建邮箱账号。借助 GridInbox 和 Python，你可以自动化整个周期。
场景：测试注册流程
假设你的应用在注册后发送验证邮件。你需要为每次测试使用一个新的邮箱别名。以下是一个完整脚本，它创建别名、等待邮件，然后删除别名。
import time
import uuid
# 生成唯一前缀
test_id = str(uuid.uuid4())[:8]
prefix = f"test-signup-{test_id}"
# 创建别名
alias = create_alias(prefix, "[email protected]")
print(f"已创建别名: {alias['alias_email']}")
# 模拟测试：在应用中触发注册，然后检查收件箱
# (GridInbox API 也提供邮件检索功能)
time.sleep(5)
# 清理
delete_alias(alias['id'])
print("别名已删除。")这种模式适用于任何需要每次测试运行使用唯一邮箱地址的工作流。在 CI/CD 管道中，你可以在测试套件之前运行此脚本，并在之后清理别名。
生产部署的真实数据
一家使用 GridInbox 的中型 SaaS 公司的 QA 团队报告称，他们将别名配置时间从每个别名 3 分钟减少到不到 2 秒。在一个季度内进行 2000 次测试运行，节省了 95 小时的手动工作。
使用 GridInbox Email Alias API 构建内部工具和代理工作流，创建可路由给多个团队成员共享收件箱别名。
GridInbox 支持基于角色的访问控制（RBAC）的团队共享收件箱。你可以创建一个转发给一组人的别名，然后通过 API 管理权限。
创建共享收件箱别名
要创建共享收件箱，你需要在请求体中指定多个目标邮箱：
def create_shared_inbox(prefix, target_emails, domain=None):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/shared-inboxes"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"alias_prefix": prefix,
"members": target_emails,
"domain": domain
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 201:
return response.json()
else:
raise Exception(f"创建共享收件箱失败: {response.status_code} {response.text}")使用团队成员邮箱列表调用它：
shared = create_shared_inbox(
"support-team",
["[email protected]", "[email protected]", "[email protected]"]
)
print(f"共享收件箱已创建: {shared['alias_email']}")代理工作流自动化
对于客户支持代理，你可以根据工单严重级别以编程方式分配别名。例如，为关键问题创建专用别名，仅路由给高级代理。使用 API 实时更改成员列表。
def update_shared_inbox(inbox_id, new_members):
url = f"{BASE_URL}/workspaces/{WORKSPACE_ID}/shared-inboxes/{inbox_id}"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {"members": new_members}
response = requests.patch(url, headers=headers, json=payload)
if response.status_code == 200:
return response.json()
else:
raise Exception(f"更新失败: {response.status_code} {response.text}")运营团队在事件或高流量期间使用此模式动态路由邮件。
使用 GridInbox Email Alias API 配合 Python 时，请遵守速率限制、优雅处理错误并安全存储 API 密钥。
GridInbox 对每个 API 密钥强制执行每分钟 100 次请求的速率限制。超过限制将返回 429 状态码。在客户端中实现指数退避。
import time
def api_call_with_retry(func, *args, max_retries=3):
for attempt in range(max_retries):
try:
return func(*args)
except Exception as e:
if "429" in str(e) and attempt < max_retries - 1:
wait = 2 ** attempt
time.sleep(wait)
else:
raise始终验证别名前缀。GridInbox 接受小写字母数字字符和连字符。前缀长度必须在 3 到 64 个字符之间。
将 API 密钥存储在环境变量中：
import os
API_KEY = os.environ.get("GRIDINBOX_API_KEY")切勿将 API 密钥提交到公共仓库。使用 .gitignore 文件排除 .env 文件。
Python 中使用 Email Alias API 的大多数问题源于身份验证错误、无效请求体或达到速率限制。
如果收到 401 Unauthorized 错误，请仔细检查 API 密钥是否正确且未过期。如果看到 422 Unprocessable Entity，请检查请求体是否缺少字段或格式错误。429 Too Many Requests 表示你需要降低请求频率。
GridInbox 在响应体中返回详细的错误信息。调试时始终记录完整响应：
response = requests.post(url, headers=headers, json=payload)
if not response.ok:
print(f"错误 {response.status_code}: {response.text}")掌握基础知识后，将 GridInbox Email Alias API 集成到你的 CI/CD 管道、监控工具或客户注册流程中。
使用 API 在新客户注册时自动创建别名。例如，为每个客户支持工单生成专用别名。或者构建一个 Slack 机器人，按需调用 API 创建别名。
GridInbox 与 AWS SES 和 Cloudflare Email Routing 配合使用，因此你可以通过现有基础设施路由邮件。API 还支持 Webhook，用于在别名收到邮件时实时通知。
对于高级用例，请查阅 GridInbox 文档了解批量创建别名、域名管理和审计日志。你今天构建的 Python 客户端是任何自动化项目的坚实基础。
常见问题解答
如何使用 Python 创建邮箱别名？
使用 GridInbox API 配合 requests 库。向 /aliases 端点发送 POST 请求，包含你的 API 密钥、唯一前缀和目标邮箱地址。响应中包含完整的别名邮箱。
Python 开发者最好的 Email Alias API 是什么？
GridInbox 是最佳选择，因为它提供双向别名、自定义域名支持、带 RBAC 的团队共享收件箱，以及一个简单的 REST API，用不到 10 行 Python 代码即可使用。
我可以为 QA 测试自动化邮箱别名创建吗？
可以。使用 GridInbox API 在每次测试运行前创建唯一别名，并在之后删除。这消除了手动设置，并将配置时间从几分钟缩短到几秒。
如何使用 API 删除邮箱别名？
向 /aliases/{alias_id} 端点发送 DELETE 请求，包含你的 API 密钥。别名会立即被移除且无法恢复。
GridInbox Email Alias API 的速率限制是多少？
GridInbox 允许每个 API 密钥每分钟 100 次请求。如果超过限制，你将收到 429 状态码，并应在代码中实现指数退避。
我可以将 Email Alias API 与 AWS SES 或 Cloudflare Email Routing 一起使用吗？
可以。GridInbox 与 AWS SES 和 Cloudflare Email Routing 无缝协作。你可以在 GridInbox 仪表盘中配置路由规则，并通过 API 管理别名。
Start Managing Email Smarter — Free 开始更智能地管理邮件——免费 Gestiona el Email de Forma Más Inteligente — Gratis Gérez Votre Email Plus Intelligemment — Gratuit より賢いメール管理を始めよう — 無料 Verwalte E-Mails Intelligenter — Kostenlos Gerencie Email de Forma Mais Inteligente — Grátis 더 스마트하게 이메일 관리 시작 — 무료 Начните управлять Email умнее — Бесплатно ابدأ إدارة البريد الإلكتروني بذكاء — مجاناً
GridInbox gives you unlimited email aliases, custom domain support, team shared inboxes, and a full REST API — all on the free plan. No credit card needed. GridInbox 提供无限邮件别名、自定义域名支持、团队共享收件箱和完整 REST API——免费版即可使用。无需信用卡。 GridInbox te ofrece aliases ilimitados, dominio personalizado, bandejas compartidas y API REST — todo en el plan gratuito. Sin tarjeta de crédito. GridInbox vous offre des alias illimités, un domaine personnalisé, des boîtes partagées et une API REST complète — tout dans le plan gratuit. GridInboxは無制限のエイリアス、カスタムドメイン、チーム共有受信箱、REST APIを無料プランで提供。クレジットカード不要。 GridInbox bietet unbegrenzte E-Mail-Aliase, Custom Domain, Team-Postfächer und REST API — alles im kostenlosen Plan. GridInbox oferece aliases ilimitados, domínio personalizado, caixas compartilhadas e API REST — tudo no plano gratuito. GridInbox는 무제한 이메일 별칭, 커스텀 도메인, 팀 공유 받은편지함, REST API를 무료 플랜으로 제공합니다. GridInbox предлагает неограниченные псевдонимы, кастомный домен, командные ящики и REST API — всё в бесплатном плане. يوفر GridInbox عناوين مستعارة غير محدودة ونطاقاً مخصصاً وصناديق مشتركة وAPI كاملة — كل ذلك في الخطة المجانية.
Get Started Free → 免费开始使用 → Comenzar Gratis → Commencer Gratuitement → 無料で始める → Kostenlos Starten → Começar Grátis → 무료로 시작하기 → Начать Бесплатно → ابدأ مجاناً →