# SendGrid

The Wallet Crew can send transactional emails through SendGrid. This covers messages like pass download links, verification emails, etc.

By default, The Wallet Crew uses **its own SendGrid account**. You can switch to **your own SendGrid account** when you need full ownership of deliverability, reputation, and billing.

If you’re not sure which option to pick, start with [Email provider](https://docs.thewalletcrew.io/connect/email-provider).

### Option 1 : Use The Wallet Crew SendGrid account

This is the simplest option, and it’s the default. You don’t need to create a SendGrid account or manage API keys. The Wallet Crew takes care of it.

If you want customers to see your Brand in their inbox, enable a **custom sending domain**. This improves deliverability. It also reduces spoofing and phishing risks.

{% hint style="info" %}
When you use The Wallet Crew SendGrid account, The Wallet Crew must enable the custom sending domain on its side. You will still need to add DNS records (SPF/DKIM, and ideally DMARC) on your domain.
{% endhint %}

{% stepper %}
{% step %}

#### Decide what sender domain you want to use

Prefer a dedicated subdomain such as `wallet.yourbrand.com` or `registration.yourbrand.com`. This keeps email authentication isolated from other mail systems.

{% hint style="info" %}
Delegating a dedicated subdomain reduces your attack surface and improves security by isolating pass-related traffic. We recommend using the same custom domain as your app.
{% endhint %}
{% endstep %}

{% step %}

#### Ask support to enable your sending domain

Contact The Wallet Crew support with the subdomain you want to use. The team will provide the DNS records to add and will enable the domain in SendGrid.
{% endstep %}

{% step %}

#### Configure DNS (SPF, DKIM, DMARC)

Add the DNS records provided by The Wallet Crew, then wait for DNS propagation.

For the general process and why it matters, see [Configuring Custom Domain](https://docs.thewalletcrew.io/configure/platform/configuring-custom-domain).
{% endstep %}

{% step %}

#### Test a real send

Trigger one transactional email and confirm:

* the email is delivered (not blocked or quarantined)
* the visible sender matches your intended domain
* SPF/DKIM pass (check in your mailbox headers if needed)
  {% endstep %}
  {% endstepper %}

### Option 2: Use your own SendGrid account

{% stepper %}
{% step %}

#### Create a SendGrid API key

In SendGrid, go to `Settings` → `API Keys`. Create an API key with **Mail Send** permissions.
{% endstep %}

{% step %}

#### Update `/server/emails.yml`

Open the advanced configuration editor:

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/settings/configuration" class="button secondary">The Wallet Crew Administration - Advanced configuration</a></p>

Then create or edit `/server/emails.yml`.

{% code title="/server/emails.yml" %}

```yaml
provider:
  type: sendgrid
  apiKey: YOUR_SENDGRID_API_KEY
  from:
    email: no-reply@yourbrand.com
    name: Your Brand
resources:
  - /locales/emails/
```

{% endcode %}

Use a `from.email` that belongs to a domain you authenticate in SendGrid.

{% hint style="warning" %}
Treat your SendGrid API key like a password.

Do not paste it in tickets or screenshots.
{% endhint %}
{% endstep %}

{% step %}

#### Configure sender authentication in SendGrid

Authenticate your sending domain in SendGrid using the standard “Domain Authentication” flow. This configures SPF and DKIM. Add a DMARC record for your sending domain if needed. This improves deliverability and reduces spoofing risk.
{% endstep %}

{% step %}

#### Save and test

Save the file. Trigger a single transactional email. Verify the event in your SendGrid activity logs.
{% endstep %}
{% endstepper %}

## Troubleshooting

* If SendGrid returns **401** or **403**, your API key is invalid or missing permissions.
* If the “from” address is rejected, your domain is not authenticated. Check SPF and DKIM first.
* If emails land in spam, re-check authentication, DMARC policy, and sender reputation.
* If nothing changes after editing, confirm you saved the right tenant file. The file must be `/server/emails.yml`.

## FAQ

<details>

<summary><strong>Where do I configure SendGrid in The Wallet Crew?</strong></summary>

Edit `/server/emails.yml` in the advanced configuration editor.

</details>

<details>

<summary><strong>Can we keep The Wallet Crew SendGrid account instead of using our own?</strong></summary>

**Yes**. The Wallet Crew uses its own SendGrid configuration by default.

If you keep it, you can still send from a domain you control. Ask support to enable a custom sending domain, then configure SPF/DKIM and DMARC on your DNS.

</details>

<details>

<summary><strong>Do we need to authenticate our domain in SendGrid?</strong></summary>

**Yes**. Enable SendGrid Domain Authentication (SPF/DKIM). Also add a DMARC record for the domain or subdomain you use for `from.email`.

</details>

<details>

<summary><strong>Can we use different SendGrid accounts per environment?</strong></summary>

Yes. Each tenant has its own configuration. You can use different API keys per tenant.

</details>

<details>

<summary><strong>What’s the fastest way to validate the integration?</strong></summary>

Save `/server/emails.yml`, trigger a single transactional email, then verify it in your SendGrid Activity feed.

</details>
