# How to test email and SMS in PHP Learn how to automate testing of email and SMS messages in PHP, using Mailosaur. ## 1. Create a Mailosaur account If you already have an account, skip to step 2. To create a new trial account, [sign up here](/app/signup). ## 2. Create a sample project ### Install PHP To see if you already have PHP installed, open a terminal window and run this command: ```bash php --version ``` If PHP is installed, you’ll see a version number. If you see an error instead, then [download PHP](https://www.php.net) and install it. ### Create a new project Run each of these commands to create a new folder for your PHP project: ```bash mkdir EmailTests cd EmailTests ``` ### Install the Mailosaur PHP library Run this command to install the [Mailosaur PHP package](https://github.com/mailosaur/mailosaur-php): ```bash composer require mailosaur/mailosaur ``` If you don’t have composer installed, [download and install it here](https://getcomposer.org). ## 3. Send email to your Mailosaur inbox Inboxes allow you to group tests, permissions, and other settings together. Each inbox has an **Inbox ID** and a **domain name**. You need these values to both send email to Mailosaur, and to set up automated testing. You also need an [API key](/docs/managing-your-account/api-keys) to use. You can learn more about [creating API keys here](/docs/managing-your-account/api-keys). ### Retrieve your inbox’s attributes 1. In the left-hand navigation, locate the **Inboxes** section. 2. Click on the name of the inbox you want to test with. 3. Click the **Settings** tab. 4. Make a note of the **Inbox ID** and **Domain**. 5. Get an API key from the [API Keys](/app/keys) page. ### Send an email to your inbox If the **domain name** of your inbox above was: ```bash example.mailosaur.net ``` Then you can send an email to it with these steps: 1. Open up an email client and send an email to `anything@example.mailosaur.net` 2. In the left-hand navigation, locate the **Inboxes** section. 3. Click on the name of the inbox you sent an email to. 4. Confirm the email is there. Note that some services (like Gmail) may take 10-20 seconds to send a message through. To learn more, read our guide on [sending email to Mailosaur](/docs/email-testing/sending-to-mailosaur). ## 4. Find an email for automated testing Now that you have a sample project, your inbox’s credentials, and an email to test, then you’re ready to continue. Create a file named `hello.php` and type or paste in this code sample, replacing the template code with the values from step 3 above: ```php sentTo = 'anything@' . $serverDomain; $email = $mailosaur->messages->get($serverId, $criteria); print('Subject: ' . $email->subject); ?> ``` This code connects to Mailosaur and looks for any email that has been sent to the address provided in the search criteria. Save your changes and run the code: ```bash php hello.php ``` If everything is set up correctly, you should see the subject line of the last email you sent, printed to screen: ```bash Subject: My example email ``` ### Troubleshooting If you see an error, e.g. ‘No matching messages found in time’: - Make sure you have set the **sent to** address correctly in your code. - Ensure that you have sent an email to the **sent to** address (check this is visible in the Mailosaur Dashboard). - Note that by default, the **get** method will only look for messages that were received by Mailosaur within the last hour. You can override this using the `receivedAfter` option (see library reference below). ## 5. Narrowing your search results ### Only find messages received after a certain time By default, searches include messages received in the last hour, but you can customise the search window with the `receivedAfter` option. This example shows you how to only include emails received after your test started: ```php $testStart = new \DateTime(); // Perform the steps that send a message here $criteria = new SearchCriteria(); $criteria->sentTo = '...'; $message = $mailosaur->messages->get( '...', $criteria, 10000, // Wait for up to 10 seconds $testStart ); ``` ### Search criteria As you can see in the examples so far, you can search for the email address or phone number a message was sent to, but you can also search using these criteria: | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **sentFrom** | The full email address from which the target message was sent. | | **sentTo** | The full email address to which the target message was sent. | | **subject** | Find emails where the subject line contains this text. | | **body** | Finds messages where the message body contains this text. | ## 6. Start writing tests Now that you have a working project that fetches an email, you can use this to begin writing tests for various pieces of functionality. Check out these guides on the most common test cases: > [!LINK](/docs/automation/text-content) > ### How to test the text content of email or SMS > Learn how to test the text content of email or SMS with Mailosaur. > [!LINK](/docs/automation/html-content) > ### HTML content of an email > Learn how to work with the HTML content found within your emails. > [!LINK](/docs/automation/codes) > ### Extracting codes from email and SMS > Learn how to test verification codes found in email and SMS messages with Mailosaur. > [!LINK](/docs/automation/links) > ### Extracting links from email and SMS > Learn how to test hyperlinks found in email and SMS messages with Mailosaur. > [!LINK](/docs/automation/attachments) > ### Email attachments > Learn how to test the email attachments with Mailosaur. > [!LINK](/docs/automation/images) > ### Images and web beacons > Learn how to work with images, including web beacons, within an HTML email. > [!LINK](/docs/automation/message-properties) > ### Message properties > Learn how to test the common properties of an email or SMS message with Mailosaur. > [!LINK](/docs/automation/spam) > ### How to test email spam score > Learn how to test the SpamAssassin score of an email with Mailosaur. ## SMS Testing You can test SMS messages in much the same way as email. Take a look at our [guide on testing SMS messages](/docs/sms-testing) for more information. ## Library reference The PHP client library gives you access to several other methods. ### Messages Messages is the collective name given to the email and/or SMS messages that are sent into Mailosaur for testing. The [message object](/docs/api) contains everything you need to perform in-depth automated testing. #### messages->get(server, criteria, timeout, receivedAfter) Waits for a message to be found. Returns as soon as a message matching the specified search criteria is found. **Recommended:** This is the most efficient method of looking up a message, therefore we recommend using it wherever possible. ```php $criteria = new SearchCriteria(); $criteria->sentTo = 'someone@SERVER_ID.mailosaur.net'; $message = $mailosaur->messages->get('SERVER_ID', $criteria); ``` To learn about inbox IDs, and what to replace `SERVER_ID` with, see [sending email to Mailosaur](/docs/email-testing/sending-to-mailosaur). ##### Criteria | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **sentFrom** | The full email address from which the target message was sent. | | **sentTo** | The full email address to which the target message was sent. | | **subject** | The subject line of the target email. | | **body** | Search for part of the message body. | | **match** | If set to `ALL` (default), then only results that match all specified criteria will be returned. If set to `ANY`, results that match any of the specified criteria will be returned. | ##### Options | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **timeout** | Specify how long to wait for a matching result (in milliseconds, _default value is 10 seconds_). | | **receivedAfter** | Limits results to only messages received after this date/time (_default 1 hour ago_). | ```php $criteria = new SearchCriteria(); $criteria->sentTo = 'someone@SERVER_ID.mailosaur.net'; $tenMinutesAgo = new \DateTime(); $tenMinutesAgo->sub(new \DateInterval('PT10M')); # Search all messages received in the last 10 minutes (with 10s timeout) $message = $mailosaur->messages->get('SERVER_ID', $criteria, 10000, $tenMinutesAgo); ``` #### messages->all(server, page, itemsPerPage, receivedAfter) Returns a list of your messages in summary form. The summaries are returned sorted by received date, with the most recently-received messages appearing first. > [!SUCCESS] > The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call [`getById`](#messages-getbyidid). Alternatively, we recommend using the [`get`](#messages-getserver-criteria-timeout-receivedafter) method, which is a far more efficient approach. ```php # List the most recent messages $result = $mailosaur->messages->all('SERVER_ID'); # Get the most recent message (the first one in the list) $message = $result->items[0]; print('Subject: ' . $message->subject); ``` ##### Options - **receivedAfter** Allows you to customise how far back to look for messages. - **page** Used alongside `itemsPerPage` to paginate through results. This is zero-based, meaning `0` is the first page of results. - **itemsPerPage** A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50. - **dir** Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`. ```php $tenMinutesAgo = new \DateTime(); $tenMinutesAgo->sub(new \DateInterval('PT10M')); # List all results received in the last 10 minutes. # Limit results to the first 10 matches only. $result = $mailosaur->messages->all('SERVER_ID', 0, 10, $tenMinutesAgo); ``` #### messages->search(server, criteria, page, itemsPerPage, timeout, receivedAfter) Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first. > [!SUCCESS] > The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call [`getById`](#messages-getbyidid). Alternatively, we recommend using the [`get`](#messages-getserver-criteria-timeout-receivedafter) method, which is a far more efficient approach. ```php $criteria = new SearchCriteria(); $criteria->sentTo = 'someone@SERVER_ID.mailosaur.net'; $result = $mailosaur->messages->search('SERVER_ID', $criteria); # Get the most recent match $message = $result->items[0]; print('Subject: ' . $message->subject); ``` ##### Criteria | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **sentFrom** | The full email address from which the target message was sent. | | **sentTo** | The full email address to which the target message was sent. | | **subject** | The subject line of the target email. | | **body** | Search for part of the message body. | | **match** | If set to `ALL` (default), then only results that match all specified criteria will be returned. If set to `ANY`, results that match any of the specified criteria will be returned. | ##### Options | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **timeout** | If provided, determines how long to wait for a matching result (provided in milliseconds). | | **errorOnTimeout** | When set to `false`, an error will not be thrown if timeout is reached (default: `true`). | | **receivedAfter** | Allows you to customise how far back to look for messages. | | **page** | Used alongside `itemsPerPage` to paginate through results. This is zero-based, meaning `0` is the first page of results. | | **itemsPerPage** | A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50. | | **dir** | Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`. | ```php $criteria = new SearchCriteria(); $criteria->sentTo = 'someone@SERVER_ID.mailosaur.net'; # Search for all messages sent to someone@SERVER_ID.mailosaur.net, # received in the last 2 hours. Limit results to the first 10 matches only. $twoHoursAgo = new \DateTime(); $twoHoursAgo->sub(new \DateInterval('PT2H')); $result = $mailosaur->messages->search('SERVER_ID', $criteria, 0, 10, null, $twoHoursAgo); ``` #### messages->getById(id) Retrieves the detail for a single email message. Must be used in conjunction with either [`all`](#messages-allserver-page-itemsperpage-receivedafter) or [`search`](#messages-searchserver-criteria-page-itemsperpage-timeout-receivedafter) in order to get the unique identifier for the required message. **We always recommend using the** [`get`](#messages-getserver-criteria-timeout-receivedafter) **method instead**. ```php $result = $mailosaur->messages->all('SERVER_ID'); $messageId = $result->items[0]->id; $message = $mailosaur->messages->getById($messageId); print('Subject: ' . $message->subject); ``` #### messages->delete(id) Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone. ```php $mailosaur->messages->delete($messageId); ``` #### messages->deleteAll(server) Permanently deletes all messages held in the specified inbox. Also deletes any attachments related to each message. This operation cannot be undone. ```php $mailosaur->messages->deleteAll('SERVER_ID'); ``` #### messages->create(server, messageCreateOptions) Creates a new message that can be sent to a verified email address. This is useful in scenarios where you want an email to trigger a workflow in your product. ```php $options = new MessageCreateOptions(); $options->to = 'verified-address@example.com'; $options->send = TRUE; $options->subject = 'Request'; $options->text = 'Please can you give us a call back?'; $mailosaur->messages->create('SERVER_ID', $options); ``` ##### Options - **to** The email address to which the email will be sent. Must be a verified email address. - **send** If true, email will be sent upon creation. - **subject** The email subject line. - **text** The plain text body of the email. - **html** The HTML body of the email. #### messages->forward(messageId, messageForwardOptions) Forwards the specified email to a verified email address. ```php $options = new MessageForwardOptions(); $options->to = 'verified-address@example.com'; $options->text = 'FYI'; $mailosaur->messages->forward('MESSAGE_ID', $options); ``` ##### Options - **to** The email address to which the email will be sent. Must be a verified email address. - **text** Any additional plain text content to forward the email with. - **html** Any additional HTML content to forward the email with. #### messages->reply(messageId, messageReplyOptions) Sends a reply to the specified email. This is useful for when simulating a user replying to one of your emails. ```php $options = new MessageReplyOptions(); $options->text = 'FYI'; $mailosaur->messages->reply('MESSAGE_ID', $options); ``` ##### Options - **text** Any additional plain text content to include in the reply. - **html** Any additional HTML content to include in the reply. ### Servers Inboxes capture emails and SMS messages, group your tests and settings, and manage access for your team. #### servers->all() Returns a list of your inboxes. Inboxes are returned sorted in alphabetical order. ```php $result = $mailosaur->servers->all(); print('You have an inbox called: ' . $result->items[0]->name); ``` #### servers->create(server) Creates a new inbox. Only the `name` property is required to create a new inbox via the API. ```php $createOptions = new ServerCreateOptions('My email tests'); $mailosaur->servers->create($createOptions); ``` #### servers->get(id) Retrieves the detail for a single inbox. Simply supply the unique identifier for the required inbox. ```php $server = $mailosaur->servers->get('SERVER_ID'); ``` #### servers->getPassword(id) Retrieves the password, for use with SMTP and POP3, for a single inbox. Simply supply the unique identifier for the required inbox. ```php $password = $mailosaur->servers->getPassword('SERVER_ID'); ``` #### servers->update(id, server) Updates a single inbox. ```php $retrievedServer = $mailosaur->servers->get('SERVER_ID'); $retrievedServer->name = 'Updated inbox name'; $mailosaur->servers->update($retrievedServer->id, $retrievedServer); ``` #### servers->delete(id) Permanently deletes an inbox. Also deletes all messages and associated attachments within the inbox. This operation cannot be undone. ```php $mailosaur->servers->delete('SERVER_ID'); ``` #### servers->generateEmailAddress(id) Utility method to help you generate a random email address for a given inbox. ```php $emailAddress = $mailosaur->servers->generateEmailAddress('SERVER_ID'); print($emailAddress); // "bgwqj@SERVER_ID.mailosaur.net" ``` To learn about inbox IDs, and what to replace `SERVER_ID` with, see [sending email to Mailosaur](/docs/email-testing/sending-to-mailosaur). ### Files #### files->getEmail(messageId) Downloads an EML file representing the specified email. Simply supply the unique identifier for the required email. #### files->getAttachment(attachmentId) Downloads a single attachment. Simply supply the unique identifier for the required attachment. ### Analysis #### analysis->spam(messageId) Perform spam testing on the specified email. ### Usage #### usage->limits() Retrieve account usage limits. Details the current limits and usage for your account. This endpoint requires authentication with an account-level API key. #### usage->transactions() Retrieves the last 31 days of transactional usage. This endpoint requires authentication with an account-level API key.