Developer guides

Prepare your workspace

Keep the first test small: one sender, one recipient you control and one message.

1. Sign up or sign in, then confirm your account email. Complete workspace setup and select the workspace that will own this integration.
2. Choose your first workflow: sending a welcome email, receiving replies or testing a verification journey. You do not need every feature configured to begin.
3. Have access to your domain’s DNS settings if you want to send from your own domain. Keep a separate mailbox you control available to check delivery.

Verify your sending domain

Domain verification establishes your sender identity. It is separate from setting up an inbox to receive mail.

1. Open Settings → Sending domains and add the domain you intend to send from.
2. Copy the DNS records shown by InboxIt into your DNS provider. Use the exact host names, record types and values displayed for your domain; do not copy values from another workspace or tutorial.
3. Return to InboxIt and run verification after saving the records. DNS changes may take time to become visible. Resolve any outstanding checks before attempting a send.
4. If sending is still unavailable, review the sending-domain status and the action shown in the dashboard. A saved domain is not necessarily a verified, ready sender.

Send your first message from the dashboard

Prove the basic path works before adding application code.

1. Open Send email in the same workspace and choose an available sender. Enter the external mailbox you control as the recipient.
2. Use a recognizable subject such as “My first InboxIt test”. Add a short message so you can distinguish this test from later retries.
3. Send the message, then open Logs to inspect its status. Check the recipient mailbox, including its spam folder.
4. If the message fails, read the error before retrying. Check domain readiness, the recipient address and your remaining allowance.

Connect your application

Once the dashboard test works, move the send into a server-side application workflow.

1. Create an API key in Settings → API keys & access. Grant the permissions your integration needs; sending uses emails:send. Keep the key in a server-side secret store, never in browser code or a public repository.
2. Follow the sending API documentation to submit your sender, recipient, subject and text or HTML. If your application already uses an SMTP library, follow the SMTP setup guide instead.
3. Assign one stable Idempotency-Key to each logical email. Reuse it when retrying the same event and payload, and use a new key for a genuinely new message.
4. Save the returned email identifier with your application event. Handle errors explicitly: retry temporary failures with bounded delays, and investigate authentication, validation or allowance errors before retrying.

Receive and read a reply

A verified sender and a receiving inbox serve different purposes. Test both ends of the conversation.

1. Create a receiving inbox in the intended workspace and wait for the address to become active. Use the receiving documentation for custom-domain configuration.
2. Send a message from an external mailbox to that address. Open Messages, select the inbox and confirm that the message appears.
3. For application access, use a key with inboxes:read and messages:read. Retrieve the inbox’s messages, then fetch the message content you need.
4. If your workflow sends replies, preserve the message relationship using the original Message-ID and in_reply_to. Test a full round trip rather than relying on matching subjects.

Test a signup or password-reset journey

Use a dedicated test address so your test runner can find the right message.

1. Open Testing and create a temporary inbox. Wait for the address to become active, then use it for an account in your application’s test environment.
2. Start waiting for a new email before triggering the signup or reset action. Apply sender or subject filters where useful.
3. Trigger the action in your application. Retrieve the new message and check the expected code or link. Validate the link’s domain before opening it.
4. Finish the journey in your test environment. Check expired or reused tokens as well as the happy path. Your application owns token generation and validation; InboxIt supplies the email.

Track events and prepare for production

Keep a record of what happened after your application requested a send.

1. Configure the email event webhooks your workflow needs from the workspace Webhooks page. Follow the documented signature-verification procedure on your server.
2. Deduplicate repeated events before updating records or triggering another action. Keep the email identifier so you can connect an event to the original send.
3. Review account usage, daily limits, storage and retention before increasing volume. Decide how your application will stop or reschedule when an allowance is reached.
4. Test a failed send and an unavailable webhook endpoint. Keep useful error details and identifiers in logs without exposing API keys or private message content.

If something does not work

My domain will not verify

Compare each published DNS record with the values in Settings. Check whether your DNS provider automatically appends the domain to the host name. Allow time for changes to propagate, then verify again.

My API request is rejected

Check the key’s workspace and permissions, the request format and the sender’s domain status. Read the returned error instead of repeatedly submitting the same invalid request.

The send was accepted but I cannot find the email

Inspect Logs for the latest delivery outcome, confirm the recipient spelling and check spam. API acceptance and remote-server acceptance are different stages from placement in a recipient’s inbox.

I cannot find a reply

Confirm that the reply destination is an active receiving address. Select the correct inbox and workspace, and test direct delivery from an external mailbox before debugging your conversation logic.

My test is timing out

Start waiting before triggering the email, check that filters match the message and confirm your application used the new test address. Do not substitute an old message just to make the test pass.