> For the complete documentation index, see [llms.txt](https://docs.mailtrap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mailtrap.io/email-api-smtp/setup/api-integration.md).

# API Integration

<details>

<summary>For use with AI assistants</summary>

AI-readable resources:

This page as Markdown — <https://docs.mailtrap.io/email-api-smtp/setup/api-integration.md>

API reference as Markdown — <https://docs.mailtrap.io/developers/email-sending/transactional.md>, <https://docs.mailtrap.io/developers/email-sending/bulk.md>

llms.txt — <https://docs.mailtrap.io/llms.txt>

llms-full.txt — <https://docs.mailtrap.io/llms-full.txt>

SDK repos:\
.NET — <https://github.com/mailtrap/mailtrap-dotnet>\
Elixir — <https://github.com/mailtrap/mailtrap-elixir>\
Java — <https://github.com/mailtrap/mailtrap-java>\
Node.js — <https://github.com/mailtrap/mailtrap-nodejs>\
PHP — <https://github.com/mailtrap/mailtrap-php>\
Python — <https://github.com/mailtrap/mailtrap-python>\
Ruby — <https://github.com/mailtrap/mailtrap-ruby>

For setup with AI assistant follow these steps. Pause and confirm with the user before proceeding at steps marked with ⏸️.

1. ⏸️ Ask the user for their tech stack (language/framework) and whether they need transactional emails, bulk emails, or both.
2. ⏸️ Ask the user for their API token, verified sending domain, and "from" email address (must be on the verified domain, e.g. <hello@yourdomain.com>). If they don't have a token or domain yet, direct them to API Tokens setup (<https://docs.mailtrap.io/email-api-smtp/setup/api-tokens.md>) and Sending Domain setup (<https://docs.mailtrap.io/email-api-smtp/setup/sending-domain.md>).
3. Install the appropriate SDK if one is available for the user's stack. Refer to the matching SDK repo above for installation instructions.
4. Generate sending code using the Transactional Stream endpoint (POST <https://send.api.mailtrap.io/api/send>) or Bulk Stream endpoint (POST <https://bulk.api.mailtrap.io/api/send>) depending on the user's choice in step 1.
5. ⏸️ Send a test email to verify the integration works. Confirm the recipient address with the user before sending.
6. Check that the email appears in the recipient's inbox and in Mailtrap Email Logs (<https://mailtrap.io/api-smtp/email-logs>).

My tech stack: \[tell the assistant your language/framework]

My API token: \[paste your token here — only share in a private AI assistant session]

My sending domain: \[your verified domain]

My "from" address: \[e.g. <hello@yourdomain.com>]

Transactional or bulk: \[tell the assistant which stream you need]

</details>

Use API credentials to integrate Mailtrap with your project.

{% @arcade/embed url="<https://app.arcade.software/share/LyuU7ciMYs6jXmOuDuEW>" flowId="LyuU7ciMYs6jXmOuDuEW" %}

{% stepper %}
{% step %}
Go to the [**Sending Setup**](https://mailtrap.io/api-smtp/sending-setup) page under **API/SMTP** and choose the domain you want to send emails from. Remember that you'll be able to start sending emails once the domain is verified.
{% endstep %}

{% step %}
Select whether you want to send emails with the **Transactional** or **Bulk Stream**.

{% hint style="info" %}
**Transactional Stream** is used to send automated, non-promotional application emails triggered by a specific user action.\
**Bulk Stream** is used to send a single marketing campaign to a large group of recipients in bulk. Toggle the switch to **API**.
{% endhint %}
{% endstep %}

{% step %}
Toggle the switch to **API**.
{% endstep %}

{% step %}
Build the authenticated HTTP request in your programming language or framework and configure it with Mailtrap Host and API Token.
{% endstep %}

{% step %}
Alternatively, choose the programming language or framework from the menu under Code Samples and copy the sample configuration (it will already contain your credentials). In this menu, you'll find official SDKs for PHP, Python, Ruby, and Node.js.

{% hint style="info" %}
For now, only Ruby, PHP (Laravel + Symfony), and Node.js SDKs support Bulk Stream, but others are in development. Request and response examples are also available [here](https://docs.mailtrap.io/developers/email-sending/transactional).
{% endhint %}
{% endstep %}
{% endstepper %}

### Verifying your configuration

Once you add Mailtrap Email API to your project, try sending an email from the tool of your choice or the project you're working on. If you did everything correctly, you should find the sent email in the inbox of the email address you specified in the script. The email will also appear in the [Mailtrap Email Logs](https://docs.mailtrap.io/email-api-smtp/analytics/logs).

<figure><img src="/files/cQWln8yzeT294axB0y08" alt=""><figcaption></figcaption></figure>

### API tokens

Remember that each domain has different API tokens. You can also create additional API tokens by going to **Settings** → **API Tokens** and clicking **Add Token**.

<a href="/pages/PMvbz81YHELFGmZaSgq1" class="button primary" data-icon="magnifying-glass">Learn more about API Tokens</a>

<figure><img src="/files/sDJB0Jq2WmKE5L5gBvcp" alt=""><figcaption></figcaption></figure>

Mailtrap Email Sending API supports:

* attachments
* [email templates](https://docs.mailtrap.io/email-api-smtp/email-templates)
* [custom variables](/email-api-smtp/advanced/custom-variables.md)
* [email categories](/email-api-smtp/analytics/categories.md)

{% hint style="info" %}
If you need any help with API integration, please, contact our support team at <support@mailtrap.io>.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mailtrap.io/email-api-smtp/setup/api-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.